PCF Tile Developer Guide v1 - Pivotal Software...workshop is free for all Pivotal partners. Pivotal recommends any interested partner to register for Partner Days . If you are not

PCFTileDeveloperGuide

v1.12

Published:8April2019

©2019PivotalSoftware,Inc.AllRightsReserved.

2369

101217182224262728293031333435373941434450515263676869707376828384

100111

TableofContents

TableofContentsPCFTileDeveloperGuidePCFv1.12PartnersReleaseNoticeTileBasicsHowPCFandPCFServicesWorkHowTilesWorkConfiguringDiskandVMTypeDefaultsforOn-DemandServiceTilesManagingRuntimeConfigsTestingTilesTypesofIntegrationUser-ProvidedServiceBrokeredServiceServiceBrokersManagedServiceBOSHReleasesErrandsOn-DemandServiceBuildpacksCredHubCreatingNewVariablesinCredHubMigratingExistingCredentialstoCredHubFetchingVariableNamesandValuesEmbeddedAgentsLogs,Metrics,andNozzlesDevelopmentToolsDevelopmentEnvironmentsTileGeneratorpcfCommandLineUtilityConcoursePivotalCloudFoundryServicesSDKPublishandUpdateTileDocumentationPartnerSoftwareProductReleaseCycleUpgradingTilesReferencesDevelopmentWorkflowReferenceProductTemplateReferencePropertyReferenceContactUs

©CopyrightPivotalSoftwareInc,2013-2019 2 1.12


Pagelastupdated:

ThistopicexiststohelpPivotalCloudFoundry(PCF)Partnerslearnthehigh-levelprocessofbuildingandpublishingatileonPivotalNetwork .

Foradvanceddeveloperswithpreviousexperiencebuildingtiles,seeProductTemplateReferenceandDevelopmentWorkflowReference.

WhatisaTile?TilesarepackagedsoftwarethatcanbeintegratedintoPCF.PCFoperatorscaninstalltilesonPCF.PCFdeveloperscanusetheseservicesoncetheyareinstalled.

TiledeveloperscanpublishtilesonPivotalNetwork,whereservicesandtilesareavailablefordownload.

TileStructureTilesarepackagedascompressedfileswitha .pivotal fileextension.Thesecompressedfilesrequirethreesubdirectories: metadata , migrations ,andreleases .

WhenyoupackageyoursoftwarewithTileGenerator,itgeneratesthesesubdirectoriesforyou.Youcanperformdifferentactionswithineachsubdirectory:

Directory Description

metadata ConfiguresettingsforyoursoftwareinaYAMLfile.

migrationsTrackchangesacrossdifferentreleasesina .js file.Onlytileswithmultiplereleasesusethissubdirectory.Donotmodifythefilesinthissubdirectoryduringyourfirsttilerelease.

releases Deployyourservicesourcecodeandotherinputsforyourbuild,suchasaBOSHrelease.

WhyBuildaTile?TherearemultiplereasonstobuildandpublishatileonPivotalNetwork.Tilescanhelpyou:

Findthewidestpossibleaudienceforyourservice.

Joinagrowingecosystemthatcaneasilyintegrateyourservice.

Enableoperatorsandappdeveloperstointeractwithyourserviceinanaccessibleandstandardizedway.

BuildingYourFirstTileTherearetwooptionsforbuildingyourfirsttile.Youcaneitherattendpartnerdaysordevelopindependently.However,PivotalstronglyrecommendsattendingPartnerDaysforhands-onguidance.

AttendingPartnerDaysPartnerDaysarethesinglebestresourcetointroduceyoutoPCFandtiledevelopment.Duringthesethree-dayworkshops,PivotalandpartnerIndependentSoftwareVendor(ISV)engineerscollaboratetoprototypeandbuildasoftwareintegrationwithPCF.

Theseeventsstreamlineyourdevelopmentprocessbyprovidinghands-onguidance,givingyouaheadstartforpublishingatileonPivotalNetwork.TheworkshopisfreeforallPivotalpartners.

PivotalrecommendsanyinterestedpartnertoregisterforPartnerDays .IfyouarenotaPivotalpartneryet,youcansignupforthepartnerprogram .

Note:PCFTileDeveloperGuidev1.12isnotdesignedforusewiththecurrentversionsofOpsManager.Foryourtilestostayuptodatewiththelatestsoftware,features,andsecurityupdates,usethelatestversionofthePCFTileDeveloperGuide.


https://network.pivotal.io/

https://pivotal.io/event/partner-days/

https://pivotal.io/partners/programs/tech

YoucanseefootageofpreviousPartnerDaysinthisbriefYouTubevideo .

DevelopingIndependentlyIfyouwanttobuildatilewithoutattendingPartnerDays,followtheprocedurebelowtominimizethelearningcurvefortiledevelopment.

Creatingatileisacomplexprocessandcanbetimeconsumingtocompleteonyourown.YoucanmessagethePivotalPartnersSlackchannelwithquestionsifyouregisterforthePivotalPartnerprogram .

1.DecideWhattoBuild

IfyouuseTileGeneratortopackageyoursoftwareyoualsoneedtodeterminetheinputsyouneedtobuildbeforedevelopment.Inputsforyourtilealsodependontheserviceyouareproviding.

Beforestartingtiledevelopment,seeHowPCFandPCFServicesWork.

Dependingonwhatyoubuild,youmightneedtoinstallthefollowingtools:

TileGenerator:Usedtopackageyoursoftwareintoatile.

BOSHCommandLineInterface(CLI) :ACLIforrunningBOSHcommands.YouneedBOSHcommandstorunTileGenerator.

CloudFoundryCommandLineInterface(cfCLI) :ACLIfordeployingandmanagingappsonCloudFoundry.IfyouaredevelopingonCloudFoundry,youusecfCLIwhenbuildingyourtile.

KubernetesCommandLineTool(kubectl) :AcommandlineinterfacefordeployingandmanagingappsonKubernetes.IfyouaredevelopingonKubernetes,youusekubectlwhenbuildingyourtile.

CFDev (optional):AlightweightPCFinstallationfordeployinganddebuggingappslocally.YoucanuseCFDevifyouwanttorunPCFonyourlocalworkstation.

2.GenerateaTile

TileGeneratorisatoolthatsimplifiesthebuildingprocessfortiles.TouseTileGenerator,uploadyoursoftwarecomponents,suchastheservicebroker,buildpack,andDockerimage,andthetoolgeneratesabasetile.

ForinformationonsettingupTileGeneratorandbuildingabasetile,seeTileGenerator.

3.TestYourTile

Beforeyoupublishyourtile,youcantestitmanuallyusingaPartnerIntegrationEnvironment(PIE).InPIEyoucanseehowthetilefunctionsonanIaaS,suchasAmazonWebServices(AWS)orGoogleCloudPlatform(GCP).Youcanupload,configure,andinstallyourtileinPIEjustlikeanoperatorwould.

TogainaccesstoyourPIE,reachouttoyourcontactatPivotalorregisterasapartner .

IfyoualreadyhaveaccesstoyourPIE,forinformationonhowtologin,seeSharedPCFDevelopmentEnvironments.

4.DocumentYourTile

Whenyouarereadytopublishyourtile,writedocumentation.Documentationisvaluableforoperatorswhouseyourtile.

Formoreinformationonhowtowriteandpublishdocumentationforyourtile,seeTileDocumentation.

5.PublishYourTileonPivotalNetwork

ContactyourPivotalrepresentativewhocanguideyouthroughtheprocessofuploadingyourtiletoPivotalNetwork.WhenyouuploadyourtiletoPivotalNetwork,itbecomesavailableforoperatorsanddeveloperstodothefollowing:

Audience Benefits

Downloadandinstallyourserviceasatile.


https://www.youtube.com/embed/eX2c8zXF6D4?rel=0

https://pivotal.io/partners/programs/tech

https://bosh.io/docs/cli-v2/

https://github.com/cloudfoundry/cli#downloads

https://kubernetes.io/docs/tasks/tools/install-kubectl/

https://github.com/cloudfoundry-incubator/cfdev

https://partners.pivotal.io/

Operators ConfigureyourserviceusingaUI.

Updateyourservicewithasingleclick.

Developers

SeeyourserviceonPivotalNetwork.

Selectserviceplanstowhichtheywouldliketosubscribe.

Createinstancesofyourserviceandcallthemfromtheirapps.

Supportacontinuousandfastdevelopmentcycle.

ForinformationonthereleasecycleforPartnertiles,seePartnerSoftwareReleaseCycle.

ContactUsIfyouwanttolearnmoreaboutthePivotalISVPartnerProgramorrequestassistancewithyourintegrationproject,seeContactUs.


PCFv1.12PartnersReleaseNoticePagelastupdated:

ThistopicdescribesthechangesthatPivotalCloudFoundry(PCF)v1.12introduceswhichmayberelevanttopartnerservicetiles.

AdditionalCredentialMigrationsVersion1.11.0ofPCFintroducedCredHubforcredentialmanagement,andPCFv1.11.1addedsupportformigrating secret credentialstoCredHub.

OpsManagerv1.12addedsupportformigratingadditionalcredentialtypes,including rsa_pkey_credential and simple_credential typesinthev1.12Alphareleaseand salted_credential inthev1.12Betarelease.TiledeveloperscanmigratethesecredentialtypesusingthesameJavaScriptmigrationprocessassecret credentials.

SeeMigratingExistingCredentialstoCredHubformoreinformation.

TernaryOperatorEvaluatesBooleanConstantsOpsManagerv1.12addssupportforevaluatingbooleanconstantsusingternaryoperators.Previously,theternaryoperatorsupportedstringconstants,propertyreferences,or named_manifest declarations.

InpreviousversionsofOpsManager,toexposeapropertytooperatorsasacheckboxthatischeckedbydefault,atileauthordefinedthetrueandfalsepropertiesinthejobmanifestasaworkaround.Inthefollowingexample,the disable_security_protocols jobspecpropertytakesabooleanvalue:

property_blueprints:-name:truetype:booleanconfigurable:falsedefault:true-name:falsetype:booleanconfigurable:falsedefault:false

manifest:disable_security_protocols:'((.properties.secure_the_system?.properties.false:.properties.true))

InOpsManagerv1.12,theternaryoperatormanagesbooleanvaluesnatively.Atileauthorcanrewritetheaboveexampleusingthefollowingsyntax:

disable_security_protocols:'((.properties.secure_the_system?false:true))'

Whenusingthissyntax,encloseeverythingfollowingtheinitialcolonwitheithersingleordoublequotationmarksandincludethespacebetweenthebooleanexpressionandthequestionmark,asshownabove.

SupportforEmptyArraysinDoubleParenthesesOpsManagernowsupportsemptyarraysindoubleparentheses.Formoreinformation,seetheDouble-ParenthesesExpressionssectionofthePropertyReferencetopic.

ResourceConfigPaneHidesZero-InstanceJobs

BreakingChange:Whenmigrating salted_credentials ,CredHubdoesnotretainthesalt.Ifyourtiledependsonthesalt,refactorbeforemigratingtoCredHub.

BreakingChange:Ifyoudefinetrueandfalseinany property_blueprint names,asshownintheworkaroundbelow,updateyourjobmanifesttousebooleanconstants.


Aservicetile’sResourceConfigpaneliststhejobsthattheservicerunsandletsoperatorsallocateresourcestothejobsthatareconfigurable.

Tilescandefineajobas non_configurable andsetitsinstancecountto 0 .Thispreventsthejobfromrunning,butletsexternalservicesaccessthejobproperties.TheOpsManager1.12ResourceConfigpaneandAPIendpoints donotincludethesezero-instancejobs.

ElasticRuntimeTilePropertyChangesPropertiesintheElasticRuntimetilehavechanged.Tiledevelopersmustchangeany ((..cf.PROPERTY.NAME)) callsaccordinglyiftheirtilesaccessElasticRuntimepropertyvalues.

ThefollowingtableslistthepropertiesthatPivotalremoved,added,renamed,andretypedbetweenElasticRuntimev1.11andv1.12:

RemovedProperties

.ccdb.credentials

.diego_database.skip_consul_locks

.etcd_tls_server.election_timeout_in_milliseconds

.etcd_tls_server.heartbeat_interval_in_milliseconds

.properties.cf_etcd_client_cert

.properties.cf_etcd_peer_cert

.properties.cf_etcd_server_cert

.properties.container_networking.disable.garden_network_pool

.uaadb.credentials

AddedProperties

.cloud_controller.staging_timeout_in_seconds

.ha_proxy.internal_only_domains

.ha_proxy.trusted_domain_cidrs

.properties.container_networking_log_traffic

.properties.container_networking_log_traffic.enable.iptables_accepted_udp_logs_per_sec

.properties.container_networking_log_traffic.enable.iptables_denied_logs_per_sec

.properties.doppler_ssl_ciphers

.properties.enable_grootfs

.properties.garden_image_plugin

.properties.garden_image_plugin_empty

.properties.garden_image_plugin_empty_args

.properties.garden_image_plugin_extra_args

.properties.haproxy_forward_tls

.properties.haproxy_forward_tls.enable.backend_ca

.properties.loggregator_client_cert

.properties.metron_ssl_ciphers

.properties.nfs_volume_driver.enable.ldap_server_host

.properties.nfs_volume_driver.enable.ldap_server_port

.properties.nfs_volume_driver.enable.ldap_service_account_password

.properties.nfs_volume_driver.enable.ldap_service_account_user

.properties.nfs_volume_driver.enable.ldap_user_fqdn

.properties.rep_preloaded_rootfses_garden

.properties.rep_preloaded_rootfses_grootfs

.properties.router_backend_max_conn

.properties.routing_minimum_tls_version


https://opsman-dev-api-docs.cfapps.io/#retrieving-resource-configuration-for-a-product

.properties.secure_diego_communication

.router.enable_isolated_routing

RenamedProperties

v1.11Name v1.12Name

.properties.container_networking.enable.network_cidr .properties.container_networking_network_cidr

.properties.container_networking.enable.vtep_port .properties.container_networking_vtep_port

.properties.networking_point_of_entry.external_ssl.ssl_ciphers .properties.gorouter_ssl_ciphers

.properties.networking_point_of_entry.external_ssl.ssl_rsa_certificate .properties.networking_poe_ssl_cert

.properties.networking_point_of_entry.haproxy.disable_http .properties.routing_disable_http

.properties.networking_point_of_entry.haproxy.max_buffer_size .properties.haproxy_max_buffer_size

.properties.networking_point_of_entry.haproxy.ssl_ciphers .properties.haproxy_ssl_ciphers

.properties.networking_point_of_entry.haproxy.ssl_rsa_certificate .properties.networking_poe_ssl_cert

.push-apps-manager.secret_token .push-usage-service.secret_token

RetypedProperties

Property v1.11Type v1.12Type

.autoscaling.broker_credentials salted_credentials simple_credentials

.autoscaling.encryption_key salted_credentials secret

.properties.mysql_backups.s3.region dropdown_select string

.properties.system_blobstore.external.region dropdown_select string

ProductDependencySyntaxTileauthorscanspecifyproductversiondependenciesintilemetadatausing ~> .OpsManagerinterpretsthisoperatorbasedonthecontextinthemetadata.Forexample:

-name:cfversion:"~>1.8"-name:example-productversion:"~>1.12.1"

Iftheversionnumbercontainsonlytwosegments,OpsManagerinterprets ~> as >= .Intheexampleabove,thisincludesallversionsof cf greaterthan1.8 .

Iftheversionnumbercontainsmorethantwosegments,OpsManagerevaluates ~> forthefinalsegment.Intheexampleabove,thisincludesversions1.12.x onlyof example-product .


TileBasicsPagelastupdated:

Thissectiongivesahigh-leveloverviewofhowtiles,PivotalCloudFoundry(PCF),andPCFservicebrokersworktogether.

CloudFoundryServiceBrokersandPCFTilesServicebrokersletdeveloperscreateserviceinstancesintheirdevelopmentspacesthattheycancallfromtheircode.Todothis,thebrokersprovideaninterfacebetweentheCloudControllerandtheadd-onsoftwareservicethattheyrepresent.TheservicecanruninternalorexternaltoaCFdeployment,buttheservicebrokeralwaysrunsinsidethecloud.

TheservicebrokerworksbyprovidinganAPIwhichtheCloudControllercallstocreateserviceinstances,bindthemtoapps,andperformotheroperations.CloudFoundryservicebrokersareimplementedasHTTPserversthatconformtotheservicebrokerAPI .

InadditiontoprovidinganAPI,aservicebrokerpublishesaservicecatalogthatmayincludemultipleserviceplans,suchasafreetierandameteredtier.BrokersregistertheirserviceplanswiththeCloudControllertopopulatetheMarketplace,whichdevelopersaccesswith cf

marketplaceorthroughthe

PivotalCloudFoundry(PCF)AppsManager.

OnPCF,cloudoperatorsmakesoftwareservicesavailabletodevelopersbyfindingthemonPivotalNetwork andtheninstallingandconfiguringthemthroughatileinterfaceintheOpsManagerInstallationDashboard.Installingaservicetilecreatesaservicebroker,registersitwiththeCloudController,andpublishestheserviceplansthatthebrokeroffers.Developerscanthencreateserviceinstancesintheirspacesandbindthemtotheirapps.

Seethefollowingtopics:

HowPCFandPCFServicesWork

HowTilesWork


http://docs.cloudfoundry.org/services/api.html


HowPCFandPCFServicesWorkPagelastupdated:

TherearemanywaystointegrateserviceswithPivotalCloudFoundry(PCF).Therightoneforeachservicedependsonwhattheservicedoes,andhowcustomerapplicationsconsumeit.Todeterminethebestwaytointegrateyourservice,you’llneedagoodunderstandingofPCFconceptslikeapplications,containers,services,brokers,andbuildpacks.

Thispageprovidesacollectionoflinkstodocumentationforthemostrelevantconcepts.Ifyouprefertolearnthroughguidedtraining,askusaboutavailabletrainingoptions.

GeneralOverviewForgeneraloverviewofPCF,andthevariouswaystointeractwithit,usethefollowinglinks:

CloudFoundrySubsystems provideshigh-leveldescriptionsofinternalfunctionsperformedbydifferentPCFcomponents.

CloudFoundryCommandLineInterface(cfCLI) linkstotopicsthatexplainhowtodirectPCFdeploymentfromyourlocalcommandline.

PivotalOpsManager describestheOpsManagerandInstallationDashboardinterfaces,wherecloudoperatorssee,install,configure,anddeployservicetiles.

PivotalAppsManager describestheAppsManagerinterface,whereappdeveloperscreateandconfigureserviceinstancesandbindthemtotheirapps.

ApplicationsCloudFoundryisprimarilyacloudnativeapplicationplatform.TounderstandhowtointegrateyourserviceswithCloudFoundry,youshouldunderstandhowyourcustomersareusingtheplatformtodevelop,deploy,andoperatetheirapplications.

DeveloperGuide explainshowtopushanapptorunonPCFandenableittouseservices.

LoggingandMonitoring describeshowPCFaggregatesandstreamslogsandmetricsfromtheappsithostsandfrominternalsystemcomponents.

ServicesMostvalue-addintegrationsaredonebyexposingyoursoftwaretocustomerapplicationsasservices.Tounderstandtheserviceconcepts,andwhataserviceintegrationlookslike,readthefollowingdocumentation:

ServicesOverview explainshowdevelopersprovisionanduseexistingservicesintheirapps.

CloudFoundryServiceBrokersandPCFTiles brieflydescribesthetwomainelementsofPCFserviceintegration:theservicebrokerAPI,whichconnectstheservicetoPCFinternallybytakingcommandsfromtheCloudController;andthetile,apackagedinterfacethatcloudoperatorsusetoinstallandconfigureaservicewithinPCF.

CustomServices explainshowserviceauthorspackagetheirserviceasaManagedServicethatisavailableforusebyPCFoperatorsanddevelopers,andwhichrunslocallyonPCFratherthanrunningremotely.

BuildpacksWhenapplicationcodeisdeployedtoCloudFoundry,itisprocessedbyalanguage-specificbuildpack.Languagebuildpacksprovideaconvenientintegrationhookforanyservicethatneedstoinspectorembellishapplicationcode.Supplyingbuildpacksalsoprovidesalanguage-agnosticwaytoinjectyourcodeintotheapplicationcontainerimage.

ApplicationStagingProcess explainshowPCFpackagesanddeploysappsincontainerswithbuildpackssothattheycanrunonmultipleVMsinterchangeably.

LanguageBuildpacks describesthelanguage-specificbuildpackssupportPCFapps.

CustomBuildpacks describeshowtousesupplybuildpackstoadddependenciesorcodewithouthavingtochange(multiple)language-sepcificbuildpacks.


mailto:[email protected]

http://docs.pivotal.io/pivotalcf/concepts/overview.html

http://docs.pivotal.io/pivotalcf/cf-cli/index.html

http://docs.pivotal.io/pivotalcf/customizing/pcf-interface.html

http://docs.pivotal.io/pivotalcf/console/index.html

http://docs.pivotal.io/pivotalcf/devguide/index.html

http://docs.pivotal.io/pivotalcf/loggregator/index.html

http://docs.pivotal.io/pivotalcf/devguide/services/index.html

http://docs.pivotal.io/on-demand-service-broker/about.html#cf-broker

http://docs.pivotal.io/pivotalcf/services/index.html

http://docs.pivotal.io/pivotalcf/concepts/how-applications-are-staged.html

http://docs.pivotal.io/pivotalcf/buildpacks/index.html

https://docs.pivotal.io/pivotalcf/buildpacks/custom.html

EmbeddedAgentsSomeintegrationsdependontheabilitytoinjectcodeintotheapplicationcontainer.Werefertotheseinjectedcomponentsas“container-embeddedagents”.Buildpacksprovideamechanismtoinjectcomponentsintotheapplicationcontainerimage,andthe .profile.d directoryprovidesawaytostartagentsbeforeoralongsidethecustomerapplication.

AgentInjectionwithasupplybuildpack

Using.profile.d

NozzlesCloudFoundry’sloggingsystem,Loggregator,hasafeaturenamedfirehose.Thefirehoseincludesthecombinedstreamoflogsfromallapps,plusmetricsdatafromCloudFoundrycomponents,andisintendedtobeusedbyoperatorsandadministrators.

Anozzletakesthisdataandforwardsittoanexternalloggingand/ormetricssolution.

Loggregatorsystem



http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/deploy-app.html#profile

https://github.com/cloudfoundry/loggregator

HowTilesWorkPagelastupdated:

ProducttilesmakeiteasyforcloudoperatorstooffernewandupgradedsoftwareservicestodevelopersinaPivotalCloudFoundry(PCF)deployment.PivotalNetwork distributesthesetilesaszippedcodedirectories,withfilenameextension .pivotal ,thatcontainorpointtoallofthesoftwareelementsthatperformthetile’sfunctions.

ThistopicexplainswhateachfunctionalelementofatiledoesandhowyoucreateorspecifyitasinputtotheTileGeneratortoolthatcreates .pivotal

files.

Thistopicalsodescribesthetypicalstructureofatiledirectory.ThisisusefulinformationformodifyinggeneratedtilesorlegacytilesthatwerecreatedwithouttheTileGenerator.

TileFunctionsPCFservicetilesperformmultiplefunctionsthatstreamlinetheuseofsoftwareservicesonPCF,including:

DeployaservicebrokerthatinterfacesbetweentheCloudController,PCF’smainexecutivecomponent,andtheservice.

PublishacatalogofavailableserviceplanstotheServicesMarketplace.

DefineaninterfaceforconfiguringservicepropertiesinOpsManager.

GenerateaBOSHmanifestfordeployinginstancesoftheservice,populatingitwithbothuser-configuredandfixedproperties.

RunBOSHerrands:deployerrandsthatsetPCFuptoruntheservicewhenanoperatorfirstdeploystheservice,anddeleteerrandsthatcleanupwhenanoperatordeletestheservice.

Definedependenciesforthetile,topreventOpsManagerfrominstallingtheservicewhenitsdependenciesaremissing.

Supportone-clickinstallationandupgradingfrompreviousversions.

Thesefunctionsaredescribedinmoredetailbelow.

ServiceBrokerServicebrokersintegrateserviceswithPCFbyprovidinganAPIfortheCloudControllertocreateserviceinstances,bindthemtoapps,andperformotheroperations.TheServiceBrokerAPIv2.10 topicspecifiesrequirementsforthisAPI.

Eachservicetileactsasawrapperforaservicebroker.Installingthetilecreatesitsservicebroker,registersitwiththeCloudController,andpublishestheserviceplansthatthebrokeroffers.

Youcanwriteaservicebrokerinanylanguage,anditcanrunanywhere,insideyourPCFinstallationorexternal.SeeExampleServiceBrokers forsamplecodeinRuby,Java,andGo.

Specifytheservicebrokerforatileinthetiledirectory’s tile.yml file,asapackagewith type: setto app-broker , docker-app-broker ,or external-broker .Theexternal-broker typerequiresa uri value,fortheservicebrokerlocation.

Catalog

Servicebrokersincludecatalogmetadata thatlisttheirserviceplans.ThisinformationpublishestotheMarketplacethatappdevelopersusetobrowseandselectservices.

DevelopersoneitherPCForopen-sourceCloudFoundryseeaplain-textversionoftheMarketplacebyrunning cfmarketplace

.ButPCFalsofeaturesa

graphicalMarketplace,andPCFservicebrokerssupportthisMarketplacewithadditionalcatalogmetadatafieldsfordisplaynames,logoimages,andlinkstomoreinformationanddocumentation.

DefinethiscatalogmetadataforyourservicebywritingyourservicebrokertoreturntheAPIcallslistedintheCatalogMetadata topic.

ConfigurationIntheOpsManagerInstallationDashboard,servicetilespresentaform-basedinterfacethatcloudoperatorsusetoconfiguretheservice.These


https://network.pivotal.io

http://docs.pivotal.io/pivotalcf/services/api.html

http://docs.pivotal.io/pivotalcf/services/examples.html

http://docs.pivotal.io/pivotalcf/services/catalog-metadata.html

http://docs.pivotal.io/pivotalcf/services/catalog-metadata.html

configuredpropertiesbecomepartoftheBOSHmanifestthatPCFusestodeployinstancesoftheservice.

Youdefinethisconfigurationinterfaceinthe forms: sectionofthe tile.yml configurationfilethatyoupasstotheTileGenerator.Eachnamedformelementdefinesaconfigurationpaneaccessibleunderthetile’sSettingstab.

Aleft-sidemenulistsallconfigurationpanesandindicateswithcheckmarkswhichoneshavebeenconfigured.Themenulistsservice-specificpanes,definedbythetiledeveloper,betweensystem-levelpaneslikeAssignAZsandNetworksandResourceConfigthatallPCFproductsandservicesuse.

Eachform,orconfigurationpane,has label forthemenutext,a description toappearuptop,and property_inputs thatdefinetheconfigurationfieldsthemselves.Constructyour forms byfollowingtheProductTemplateReferencetopicandthePropertyBlueprintReferencesectionoftheAboutPCFTilestopic.

Foreachproperty,youcancombinespecificationsfor name , type , default , configurable , options ,and constraints ,underboththe[FormProperties](./product-template-reference.html#form-properties]andPropertyBlueprintssectionsofthetopic.

TileAppearance

IntheOpsManagerInstallationDashboard,yourservicetilebearsanidentifyinglabel,description,andlogoicon.Specifytheseatthetopofyour tile.ymlconfigurationfileas label , description ,and icon_file .Thevalueof icon_file shouldbethenameofa128×128pixelPNGimage.

Note:Inthetileinstaller .yml thatTileGeneratorcreates,formpropertiesappearintwolocations:a form_types sectionthatdefinesthecontentsandlayoutoftheconfigurationinterface,anda property_blueprints sectionthatdefinesthecorrespondingfieldvaluetypesandconstraints.


FixedPropertiesAtilealsowritesfixed,unconfigurablepropertiesintotheBOSHmanifestthatitcreates.Youspecifythesepropertiesinyour tile.yml configurationfileusingDouble-ParenExpressionsformat.

Credentials

IncludecredentialstopassintoaBOSHmanifestas salted_credentials inyour tile.yml file.Butyouneednotincludecredentialsthatalreadyexistinothertiles,suchasElasticRuntime.BOSHautomaticallygeneratestheseforanypackagesthatrequirethem.

ErrandsTileGeneratorautomaticallygenerates deploy and delete lifecycleerrandsforpackagesthatdeploytoPCF.TheseerrandscriptsdeploytheservicetoPCFandpublishitsplansintheMarketplace,andremovetheservicefromPCFandtheMarketplace.

Youcanalsodefineadditional post_deploy and pre_delete errandscriptsin tile.yml thatpreparePCFtohosttheserviceorcleanupbeforedeletingit.YoucanconfiguretheseerrandstorunontheirowndedicatedVMsorco-locatethemonexistingerrandVMs.

For bosh-release and docker-bosh packages,whichrunjobsdirectlyonBOSHratherthanonthePCFlayer,youneedtoinclude post_deploy and pre_delete

errandswiththeirpackagedefinitionsin tile.yml .Labelthemaslifecycleerrandsusing lifecycle:errand andeither post_deploy:true or pre_delete:true .

TileGeneratorwritesthe bosh-release errandsintothemainBOSHreleasethatitcreatesfortheservice,andadds docker-bosh errandsintoaseparateDockerBOSHreleasethatthemainreleasedependson.

DependenciesIncludeproductdependenciesunder requires_product_versions atthetopofyour tile.yml file.

UpdateRulesTileGeneratorautomaticallygeneratestheJavaScriptmigrationfilethatenablesone-clickupdatesfromOpsManager.Thisfiledescribeshowtochangeexistingtilepropertynamesandvaluesinordertomatchthenewversionofthetile.

Amaturetilemaycontainseveralofthese .js files,frompreviousversionsandthecurrentone,toenabletileupdatestoautomaticallychaintogetherinsequence.

Youcanaddcustomupdatecodeinthe tile.yml TileGeneratorconfigurationfile,followingthepropertiesdocumentedintheMigratingTileVersionstopic.

TileFileFormatandStructureTiledirectoriescontainthefollowingcomponents,whichincludeeachotherasshown:

BOSHrelease

ServicesourcecodeServicebrokerLanguage-specificbuildpack(s)Errands(servicestartandstopscripts)BOSHmanifest(deploymentpropertiesforservice)

PackagesDependencies

Tilemanifesttemplate(addspropertiesintoBOSHmanifest)

ConfigurationformsandpropertiesCatalogmetadata(fortheMarketplace)

Migrations


Thethreerequiredtop-levelsubdirectoriesina .pivotal tiledirectoryare:

metadata -high-levelinformationforconfiguringandpublishingyourservice.

migrations -rulesthatgoverntileupgrades.

releases -theBOSHreleasesthatdeployyourservice.

Thetilemanifesttemplatedefinesthesesubdirectorylocations,sotheycanresideanywhereinthedirectory,butthetypicalstructurelookslikethis:

.├──example-product│├──metadata││└──example-product.yml│├──migrations││└──v1││├──201512301616_convert_14_transmogrifier_rules.js││├──201512301631_convert_15_16_transmogrifier_rules.js││└──201611060205_example_migration.js│└──releases│└──example-release-18.tgz

.pivotalFileFormatWithinthetiledirectory,theBOSHreleaseexistsasagzippedtarfile.

Theentiretiledirectoryisalsoagzippedtarfile,withthe .tgz extensionrenamedto .pivotal .

Youcanuseanyziputilitytocreatea .pivotal file.Ensurethatthetop-levelsubfoldersasseenaboveinthe example-product folderremain.

ExampleWorkflow

$cdexample-product$zip-rexample-product.pivotalmetadata/migrations/releases/$unzip-lexample-product.pivotalArchive:example-product.pivotalLengthDateTimeName--------------------008-09-1616:10metadata/8945808-09-1616:10metadata/example-product.yml007-08-1609:32migrations/007-08-1609:32migrations/v1/42307-08-1609:32migrations/v1/201512301616_convert_14_transmogrifier_rules.js122807-08-1609:32migrations/v1/201512301631_convert_15_16_transmogrifier_rules.js58207-08-1609:32migrations/v1/201611060205_example_migration.js008-09-1616:11releases/007-12-1617:19releases/example-release-18.tgz

GitHubRepositoryStructureTiledeveloperstypicallydevelopandarchivetheircodeonGitHub,andtheirConcoursebuildpipelinepullsfromGitHubtoperformcontinuousintegration.

TileGeneratordoesnotdictateanydirectorystructureforaGitHubrepository,butbyconventionyourtilerepositorymightlooklikethis:

/tile.yml/src#sourcecodeforallcomponentsdeployedbythetile/resources#otherresources,suchasiconimagesandimportedDockerimagesorboshreleases/release#generatedboshrelease(s)/product#generatedtile

PackagesPCFservicestypicallyrequiremultiplecomponentjobprocessestorunconcurrently,suchasamainapp,ahelperapp,andaservicebroker.Theyalso


requirebuildpacksthatrunasone-timecompilationtasks.Servicesalsorequirecomponentssuchasexternalbrokersorstorage,whichdonotrunasjobs,butneverthelessneedtoremainavailable.

The tileyml filethatyoupasstoTileGeneratordefinestheseservicecomponentsitits packages: section.Eachpackagehasanameandapackagetype.ThelistofpossiblepackagetypestopasstoTileGeneratorisintheTileGeneratorcode .Itincludes:

app- cf push edtoPCF

docker-app- cf push edtoPCF(imagewillnotbeembeddedsorequiresDockerregistryaccess)

app-broker- cf push edtoPCFandregisteredasabroker

docker-app-broker- cf push edtoPCFandregisteredasabroker(imageisnotembedded,sorequiresDockerregistryaccess)

external-broker-Registeredasabroker

buildpack-installedwith cf create-buildpack ;runsasaone-timetaskratherthanalong-runningprocess

docker-bosh-describesacollectionofDockerimagesthatembedinthetileandrunonBOSH-managedVMs,notPCF

bosh-release-apre-existingBOSHreleasewrappedinatile,torunonBOSH-managedVMs,notPCF;requiresyoutodescribealljobs(long-runningprocessesanderrands)

Packagestypicallycontainasingleprocess,butcanincludemorethanone,packagedtoruninthesamelocation.

WherePackageProcessesRun

Wherepackagedprocessesrundependsontheirpackagetype,asfollows:

app , docker-app , app-broker ,and docker-app-broker packagescall cfpush torunprocessesincontainersonaDiegocell.

docker-bosh and bosh-release packagesruntheirprocessesonVMsintheunderlyingBOSHlayer.

external-broker and buildpack packagesrunone-timetasks,notlong-runningprocesses,onDiegocells.

PackageVMResources

Theservicetile’sResourceConfigpaneletstheoperatorconfigureresourcesindividuallyforeachpackage.ThispanealsoletsoperatorsprovisionresourcesforVMsthathandleone-timetasks,withthe acceptance-tests , deploy-all ,and delete-all rows.


https://github.com/cf-platform-eng/tile-generator/blob/master/tile_generator/config.py#L59-L70

ConfiguringDiskandVMTypeDefaultsforOn-DemandServiceTilesPagelastupdated:

ThistopicdescribeshowtileauthorscanconfigurethedropdownmenuitemsforVMtypesandpersistentdisktypesintheirtile.

On-demandservicetileshaveaconfigurationpaneforeachserviceplan.OperatorsusedropdownmenusontheplanconfigurationpanetosettheVMtypeandpersistentdisktypeforeachinstanceofthatplan.

OpsManagerpopulatesthemenuswithoptionsbasedontheVManddiskoptionsavailableonthecurrentIaaS.SettingdefaultvaluesforVMsanddisktypeshelpsoperatorstochoosetherightresourcesforon-demandservicebroker(ODB)serviceswhenusingon-demandplans.

VMandPersistentDiskTypesThepropertythatdefinestheVMtypeoptionsis vm_type_dropdown ,andthemenuoptionsfordisktypecomefromthe disk_type_dropdown property.Tileauthorsdonotspecifythemenuitemsintheproducttemplate.

BecauseVManddiskoptionsdifferbyIaaS,OpsManagerusesabest-fitalgorithmtomatchdefaultstotheirclosestequivalentsontheIaaS,similartohowtheResourceConfigpanehandlesitsVMTypeandPersistentDiskTypeoptions.

IfatiledeveloperdoesnotincludeadefaultvalueforaVMordiskresource,andthenanoperatorconfiguringthetiledoesnotchooseavaluefromthedropdown,OpsManagerbydefaultsetstheresourcetothesmallestoptionavailableontheIaaS.

SetVMTypeDefaultsFor vm_type_dropdown theresourcesare ram , ephemeral_disk ,and cpu .Tileauthorscanalsoapply constraints toanyoftheseresources.Constraintscaninclude min or power_of_two .Forexample:

-name:example_vm_typetype:vm_type_dropdownconfigurable:trueresource_definitions:-name:ramdefault:1024constraints:min:1024power_of_two:true-name:ephemeral_diskdefault:1024-name:cpudefault:1

SetPersistentDiskTypeDefaultsFor disk_type_dropdown theresourceis persistent_disk .Tileauthorscanalsoapply constraints tothisresource.Constraintscaninclude min or power_of_two .Forexample:

-name:example_disk_type_dropdowntype:disk_type_dropdownconfigurable:trueresource_definitions:-name:persistent_diskdefault:2000constraints:min:50power_of_two:false

Note:OpsManager2.0andlatersupportsdefiningVManddisktypedefaultsandconstraints.


ManagingRuntimeConfigsPagelastupdated:

ThistopicexplainshowtodefineandmanagenamedruntimeconfigswithyourservicetileforPivotalCloudFoundry(PCF).

Tileauthorscancreateanewruntimeconfiginanexistingproducttile,deletearuntimeconfigfromatile,oraddatilethatcontainsaruntimeconfigonly.

SeetheBOSHdocumentation formoreinformationaboutruntimeconfigs.

OverviewAruntimeconfigisasectionofthetilemetadatathatcandefineglobaldeploymentconfigurations.Whenatileauthorincludesaruntimeconfigasatop-levelkeyinthetilemetadata,BOSHappliestheruntimeconfigtoeveryVMinthedeployment.

Totheoperator,aruntimeconfigappearsinOpsManagerasatilewithminimalconfigurationoptions.Runtimeconfigtilescontainnostemcell,network,availabilityzone(AZ),orresourceconfiginformation.

WhenyouclickApplyChanges,OpsManagercombinestheruntimeconfiginformationfromeverytileinthedeploymentandassignseachnamedruntimeconfigauniqueidentifier.OpsManagercreatesthenameusingthetilename,ageneratedGUID,andtheruntimeconfignamedefinedinthemetadatainthefollowingformat:

TILE_NAME-GUID-RUNTIME_CONFIG_NAME

CreateaRuntimeConfigTileauthorscanadd runtime_configs asatop-levelkeyintilemetadata.Inthiskey,thetileauthordefinesconfigurationpropertiesthatOpsManagerappliestoalldeployments.Atilecansupportanynumberofruntimeconfigs.

Anamedruntimeconfig,suchas MY-RUNTIME-CONFIG intheexamplebelow,cancontainanynumberofaddons.Eachaddoncancontainanynumberofjobs.

Toaddaruntimeconfigtoatile,addthefollowingsectiontothetilemetadata:

Note:OpsManager2.0Alphaintroducessupportforruntimeconfigs.


https://bosh.io/docs/runtime-config.html

runtime_configs:-name:MY-RUNTIME-CONFIGruntime_config:|releases:-name:os-confversion:15addons:-name:MY-ADDON-NAMEjobs:-name:MY-RUNTIME-CONFIG-JOBrelease:os-confproperties:MY-ADDON-NAME:...

Replacethetextintheexampleabovewiththefollowing:

MY-RUNTIME-CONFIG :Chooseanamefortheruntimeconfig.

MY-ADDON-NAME :Chooseanamefortheaddonthatcontainstheruntimeconfigjob.

MY-RUNTIME-CONFIG-JOB :Chooseanameforthejobtheruntimeconfigdescribes.

Definetheruntimeconfigjobpropertiesinthe properties section.

DeleteaRuntimeConfigTileauthorscanremoveanexistingruntimeconfigfromatilebyuploadingablankruntimeconfiginitsplace.Removetheconfigurationforthenamedruntimeconfigfromthetilemetadata,leavingthenameinplace.

Thefollowingexampledeletes example-runtime-config :

runtime_configs:-name:example-runtime-configruntime_config:

CreateaRuntimeConfig-OnlyTileTileauthorscancreateatilethatonlycontainsaruntimeconfig.Theonlyreleasethatatileauthormustincludeinaruntimeconfigtileis os-conf .Whencreatingaruntimeconfig-onlytile,atileauthorisnotrequiredtodefinethefollowingtop-levelkeys:

post_deploy_errands

pre_delete_errands

job_types

ExampleRuntimeConfig-OnlyTileThefollowingexampleshowsaruntimeconfig-onlytilewithminimalconfiguration:

Important:Thenamesyouchoosemustbeuniqueacrossadeployment.Pivotalrecommendsappendingyourproductnameoranotheruniqueidentifiertoeachofthenameditemsinthe runtime_configs section.


---name:runtime-config-only-example-productproduct_version:"3.4"minimum_version_for_upgrade:"2.0"metadata_version:"2.0"label:'RuntimeConfigOnlyExampleProduct'description:Anexampleproducttodemonstrateruntimeconfigfeaturesrank:1service_broker:false#Defaultvaluestemcell_criteria:os:ubuntu-trustyversion:STEMCELL-VERSION

releases:-name:os-conffile:os-confversion:'15'

post_deploy_errands:[]

pre_delete_errands:[]

form_types:-name:example_formlabel:'Exampleform'description:'Anexampleform'property_inputs:-reference:.properties.example_stringlabel:'Examplestring'

property_blueprints:-name:example_stringtype:stringconfigurable:truedefault:Pizza

job_types:[]

runtime_configs:-name:example-runtime-configruntime_config:|releases:-name:os-confversion:15addons:-name:loginjobs:-name:login-bannerrelease:os-confproperties:login_banner:text:|((.properties.example_string.value)).

Intheexampleruntimeconfigabove,the login-banner jobprintsabannerwhenauserlogsintoanyVMinthedeployment.Theoperatorcanusethedefaultvaluedefinedinthe form_types sectionofthemetadataorconfigurethebannerbyeditingtheExamplestringvalueinOpsManager.



TestingTilesPagelastupdated:

Thistopicexplainsrecommendedtestingpracticesfortiledevelopers.

TileTestingGoodtestingassurestiledevelopersthattheirproductinstallsandrunsproperlyondiverseplatformsandassuresPCFplatformoperatorsthatthetiletheyinstallcanprovideitsservicesuccessfullyontheirplatform.

Pivotalrecommendsapyramidstructurefortesting,startingwithunittestsandsteppinguptosuccessivelybroaderandmoreautomatedlevelsofintegration.PivotalusesandrecommendsConcourseforcreatingbuildpipelinesthatfollowthisteststructure.Othercontinuousintegrationtoolsshouldalsosupportapyramidtestingapproach.

TileTestPyramidForPCFtiles,atypicaltestpyramidprogressesasfollows:

1. Unittestsforeachtilecomponent(e.g.servicecomponents,broker,adapter,andmetricsemitter),manualbydeveloperandinautomatedpipeline.

2. Systemtestsofthetile’sBOSHrelease,including:

Functionaltestscoveringthemainfeaturesoftheservice.Themainfeaturestypicallyinteractwithalmostallimportantexternalintegrationpoints,sothesetestsconfirmproductfunctionality.Smoketests(lifecycletests)forserviceinstancesthatcreateandbindaserviceinstance,callitfromatestapp,checkthelogsitgenerates,anddeleteit.Foratypicalend-to-endtestsequence,seeSmokeTestsbelow.

3. SystemtestsoftileoperationwithinOpsManager.

Theseinclude:

ConfigurationchecksthattesteveryexternalconfigurableintegrationpointandconnectiontoremoteserversusingconfiguredcredentialsDefaultchecksthatconfirm“happypath”functionality.

UsetheOpsManagerAPItoverifythatpropertyblueprintsinthetilemetadataarecorrectandthattheytranslatecorrectlytotheBOSHmanifestthatOpsManagergenerates.UsetheOm tooltocalltheOpsManagerAPIprogrammaticallyfromGo.AvoidtheunsupportedopsmgrgemthatcalledtheOpsManagerAPIfromRuby.ConfirmmanuallythatthetilewirespropertyblueprintstotheexpectedpaneandformcontrolsintheUI.TestyourenvironmentusingoneoftheenvironmentsdescribedinDevelopmentEnvironments

SmokeTestsSmoketestsareend-to-endlifecycletestsforserviceinstancesthatyoucanincludeaspost-deployerrandswithinatileandalsoautomateinConcourseorotherintegrationplatforms.

Atypicalsmoketestrunsasfollows:

1. Createanorgandspaceforthetesttorunin.

2. Registerthetile’sservicebroker.

3. Enableserviceaccessforthecreatedorg.

4. Iteratethroughallserviceplans(orasubsetofthem)todothefollowing:

a. Createaserviceinstancefortheplan.

Note:Systemtestsmightincurcostsfromusingthirdpartyservices,IaaSresources,etc.


https://github.com/pivotal-cf/om

b. Pushatestapp.c. Bindtheserviceinstancetotheapp.d. Usetheappinawaythatexercisestheserviceinstance.Foradataservice,forexample,writeandreadfromtheserviceinstance.e. Unbindtheserviceinstance.f. Deletetheserviceinstance.g. Deletethetestapp.

5. Deletetheservicebroker.

6. Deletethetestorgandspace.

GeneralRecommendationsThefollowingaregeneralrecommendationsfordesigningandrunningtestsonPCFtiles:

Cleanupafteryourself.Leavetheenvironmentexactlyasitwasbeforethetestwasrun.

Generateverboseloggingwithlotsofcontextualdatatomaketroubleshootingeasier.

Designtestsuitesforre-usabilitybymakingthemhighlyparameterizable.Importantparametersinclude:

Externalsettingssuchasdomains,creds,andcertsPlanstotestagainst.Forexample,theRedisforPCF smoketestsuseidenticalcodefortwodifferentserviceplans,pre-provisionedandon-demand.Timeouts,numbersofretries,andotherthingsthatyouneedtoadjustfordifferentenvironmentsSwitchestoincludeorexcludeportionsofthetestssuchasgeneratingmetricsorbackups

Re-useteststhatexistalready,forexampleinConcourse.

UseanexampleCFappthatusesyourservice.Thisappcanservefortesting,demoingyourtilecapabilities,andasacodecodeexample.SeetheMySQLTestApp anexample.

Whentestingmanually,usingtheUIisbetterthancallingtheunderlyingAPIdirectly.UseUIsandAPIsthewayacustomerwould.


https://github.com/pivotal-cf/cf-redis-smoke-tests

https://github.com/cloudfoundry-incubator/cf-mysql-acceptance-tests/tree/master/assets/sinatra_app

TypesofIntegrationPagelastupdated:

IntegrationLevelsAservicecanintegratewithPCFatfourlevels,shownhereinorderofincreasingintegration.Ingeneral,user-experienceandproduction-readinessimprovesastheintegrationlevelincreases.Butnoneofthehigherlevelsisrequired.Youcanstopserviceintegrationanddeclareitcomplete(enough)afteranyofthese:

Whenintegratingthird-partysoftwarewithCloudFoundry,theefforttypicallyprogressesthroughincreasinglevelsofintegration.Werecommendthisstagedapproachbecauseitenablesearlyfeedbackonthevalueandthedesignoftheintegration,whichhelpsmakebetterdecisionsaboutfuturestages.

Fornon-serviceintegrations(suchasapplicationsorbuildpacks),asimilarstagedintegrationapproachisoftenpossibleanddesirable.

Level1.User-ProvidedServiceTheservicerunsexternaltoPCFandhasnoservicebrokerortile.Touseaservicewithanapp,thedevelopercreatesaservicebrokerbyrunningcfcreate-user-provided-service

fromtheCloudFoundryCommand-LineInterface(cfCLI).

Configuring,running,upgrading,andpayingforauser-providedservicearealluptothedeveloper.

Level2.BrokeredServiceAbrokeredservicerunsexternaltoPCF,buthasatileonPivotalNetwork (PivNet).

PivNetdesignatesbrokeredservicesbyincluding“ServiceBrokerforPCF”inthename.

Operatorsinstall,configure,andupgradethetilethroughtheOpsManagerInstallationDashboard.DeveloperscanthenseeyourserviceplansandcreateserviceinstancesinAppsManager,orbyrunning cf

marketplaceand cfcreate-

servicefromthecommand-line.

TheBrokeredServicetopichasmoreinformationaboutbrokeredservicetilesandhowtocreatethem.


http://network.pivotal.io

Level3.ManagedServiceWithamanagedservice,boththeservicebrokerandtheserviceitselfrunwithinPCF.ThisenablesPCFtomanage,monitor,andincreaseserviceperformance.

Aswiththebrokeredservice,theservicehasaservicebrokerandatilelistedonPivNet.PivNetlistsmanagedservicesas“forPCF,”without“ServiceBroker”inthename.

Whentheoperatorinstallsthetile,theyallocateablockofVMstorunserviceinstancesandprovisionstheirCPUandmemoryresourcesuniformly.

TheManagedServicetopichasmoreinformationaboutmanagedservicetilesandhowtocreatethem.

Level4.On-Demand(Dynamic)ServiceAswithamanagedservice,anon-demandserviceandbrokerbothrunwithinPCF,andPivNetliststheservicetilewithout“ServiceBroker”inthename.Butunlikeamanagedservice,anon-demandservicedoesnotlimitthenumberofserviceinstanceVMs.Theoperatordoesnothavetopre-allocateandprovisionVMresourcesfortheservice.

Whenadevelopercreatesaninstanceofanon-demandservice,theyprovisionitsresources(withinanallowedrange)andBOSHdynamicallycreatesanew,dedicatedVMfortheinstance.

TheOn-DemandServicetopichasmoreinformationaboutOn-Demandservicetilesandhowtocreatethem.


User-ProvidedServicePagelastupdated:

Thistopicexplainshowtocreateauser-providedserviceforPCF.

OverviewAPCFdevelopercancallyourservicefromtheirappcode,eveniftheservicerunsoutsideofPCFandhasnoservicebroker.Usecasesforthisinclude:

YoursoftwareisavailableasaSaaS.

Youalreadyhaveawaytoinstallyoursoftwareon-premisesatacustomersite.

Yourcustomeralreadyusesyoursoftware,isnowadoptingPCF,andwantstoconsumeyoursoftwarefromapplicationsthattheydeployonPCF.

Thisdo-it-yourselfsolutionrepresentsthelowestlevelofPCFserviceintegration.ItworksonlyforservicesrunningexternaltoPCF,anddoesnotpublishtheservicestotheServicesMarketplaceormakethemavailabletoanyoneoutsidethespaceofthedeveloperwhorunsthesecommands.SeetheUser-ProvidedServiceInstances topicformoreinformation.

Runningappswithauser-providedserviceisagreatwaytodeterminewhatinformationneedstobepassedinthecredentialstructure(usefulinhigherintegrationlevels),verifythattheintegrationworks,anddevelopatestappthatcancontinuetobeusedathigherlevels.Fromtheappdeveloperperspective,onceauser-providedserviceworks,laterintegrationsoftheservicewillnotrequireanyfurthercodechanges.User-providedservicebindingsarefullyforward-compatiblewithbrokeredservicebindings.

UsingaUser-ProvidedServiceTouseanexternalservicethathasnotile,theydothefollowingfromtheCloudFoundryCommand-LineInterface(cfCLI).

1. Run cfcreate-user-provided-serviceMY-SERVICE-NAME-pCREDENTIALS (or cfcups )tocreateaserviceinstance.The CREDENTIALS argumentshouldbeavalidJSONstringthatcontainstheURLandcredentialsnecessarytoconnecttoyourexternally-deployedservice.

2. Run cfbind-service tobindtheserviceinstancetotheirapp.

Bydoingthis,appdeveloperscanbindtheirappstoyourserviceandwriteallcodenecessarytoaccessitthroughaCloudFoundryservicebinding.


http://docs.pivotal.io/pivotalcf/devguide/services/user-provided.html

BrokeredServicePagelastupdated:

ThetopicsinthissubsectionexplainhowtointegrateyoursoftwareservicewithPivotalCloudFoundry(PCF)tocreateabrokeredserviceandservicetileforPCF.

OverviewYoucanachievethefirstrealimprovementinyourPCFcustomersuserexperiencebycreatingaServiceBrokerforyourservice.

AbrokeredservicerunsexternaltoPCF,butithasatileonPivotalNetwork (PivNet).Operatorsinstall,configure,andupgradethetilethroughtheOpsManagerInstallationDashboard.

TheservicebrokereliminatestheneedforyourcustomerstoknowtheURLsandcredentialsforyourservices;theyaremanagedautomaticallybythebroker.

Buildingabrokerfora(still)externallydeployedserviceisgenerallyagoodwaytopublishafirsttilethataddsrealvalueforcustomerswhohavebothyoursoftwareandPCF.

CreateaBrokeredServiceAbrokeredservicerequiresaservicebroker,whichpublishesanAPItotheCloudController.ServiceBrokersexplainshowtocreateone.

RouteServicesexplainshowtocreatearouteservice,foruseintheroutinglayerofPCFratherthanbyhostedPCFapps.

CatalogexplainshowtodesignthepartofyourservicebrokerAPIthatpublishesserviceplaninformationtotheServicesMarketplace.

Youcanwriteyourservicebrokerinthelanguageofyourchoice.Buildpacksexplainshowtocreatealanguage-specificbuildpackthatcompilesandpackagesyourservicebrokertorunonPCF.

Onceyouhavetheindividualcomponentsforyourbrokeredserviceintegration,youcanworkthroughBuildingYourFirstTile tocreateyourtile.

Atanylevelofintegration,PivotalrecommendsandsupportsusingConcourseforcontinuousintegrationduringdevelopment.



https://docs.pivotal.io/tiledev/1-12/#tile-steps

ServiceBrokersPagelastupdated:

Thistopicprovidesresourcesforbuildingservicebrokersandroutingservices.

ServiceBrokerResourcesTheCustomServicesOverview topicgivesahigh-leveldescriptionofhowservicebrokersworkinPivotalCloudFoundry(PCF).

ServiceBrokerAPI givesamoredetailedexplanationofPCFservicebrokers,andprovidesafullspecificationfortheendpoints,requests,responses,andstatuscodesthataservicebrokermustsupport.

ExampleServiceBrokers offersexamplebrokerswritteninRuby,Java,andGo.

RouteServicesResourcesRouteServices explainshowrouteserviceswork,andwhatarethedifferentarchitecturesforusingtheminaCloudFoundrydeployment.

ExampleRouteServices givesexamplesofaloggingrouteservice,arate-limitingrouteservice,andanotherloggingservicewritteninSpringBoot.Italsooffersatutorialonsettinguptheloggingrouteservice.

CatalogResourcesCatalogMetadata explainshowtopublishserviceplaninformationtotheServicesMarketplace,includingtheicons,displaynames,andlinksthatappearinthePCFAppsManagerUIbutnottheplaintextoutputof cf marketplace .


http://docs.pivotal.io/pivotalcf/services/overview.html

http://docs.pivotal.io/pivotalcf/services/api.html

http://docs.pivotal.io/pivotalcf/services/examples.html

http://docs.pivotal.io/pivotalcf/services/route-services.html

http://docs.pivotal.io/pivotalcf/services/route-services.html#examples

https://docs.pivotal.io/pivotalcf/services/catalog-metadata.html

ManagedServicePagelastupdated:

ThetopicsinthissubsectionexplainhowtointegrateyourbrokeredservicemorecloselywithPivotalCloudFoundry(PCF)tocreateamanagedserviceandservicetileforPCF.

OverviewThenextlevelofintegrationistogetyourservicetobedeployedonPCFratherthanexternally,onthesameIaaSthatyourparticularCloudFoundryinstanceisdeployedon,andbythesameorchestrationtool,BOSH .

Thisisusuallyoneofthemoreinvolvedintegrations,asyouwillhavetochangeyourpackagingtoallowyourservicecomponentstobedeployedbyBOSH ontothePCFinfrastructure.

OfferingyoursoftwareasamanagedservicemeansthatyourPCFcustomerswillnothavetolearndifferentwaystodeploy,manage,andmonitordifferentcomponentsoftheirapplicationplatform.

Aswiththebrokeredservice,theservicehasaservicebrokerandatilelistedonPivNet.PivNetlistsmanagedservicesas“forPCF,”without“ServiceBroker”inthename.

Tointegrateyourserviceatthislevel,youwillhavetolearnaboutstemcells,BOSHreleases,andmanifests.Youwillalsohavetodecidehowyourservicemapstovirtualmachinesandhowpersistentstorageismanaged.

MinimalViableProductForaMinimalViableProduct(MVP)versionofamanagedservice,wetypicallyrecommendthatyouaimforasingle,sharedserviceinstance,anddon’tyetworrytoomuchaboutHighAvailabilityofthisinstance.ThisintegrationlevelismostlyaboutgettingtheBOSHpackaging,deployment,andmonitoringworkingcorrectly.

HighAvailabilityOnceyouhaveamanagedservice,youmaydecidetoprioritizeeitheron-demandprovisioningofserviceinstances,ormakingyoursinglesharedserviceinstancemorehighlyavailable.

Whenproperlyconfigured,BOSHmonitorsandrestartsanyfailingprocessesandvirtualmachinesthatarepartofyourservicedeployment.Buttofurtherincreaseavailability,youwillhavetothinkaboutspreadingyourresourcesacrossmultipleavailabilityzonesorevenregions,andreplicatingyourpersistentstorageacrossthoseaswell.

CreateaManagedServiceForBOSHtomanageyourservice,youneedtocreateaBOSHreleaseforit.BOSHReleasesexplainshowtodothis,andhowtouseyouralready-existingDockerimageasashortcut.

OnceyouhavecreatedaBOSHreleaseforyourmanagedserviceintegration,youcanworkthroughBuildingYourFirstTile tocreateyourtile.

TheTileGeneratortoolautomaticallycreatesthelifecycleerrandsthatcanrunafteraPCFtileisdeployedorbeforeitisremoved.PCFoperatorscontrolwhicherrandsrunthenexttimetheyclickApplyChangestoredeploy.SeetheErrandstopicforhowPCFoperatorscontrolwhenerrandsrun,andhowtosetdefaulterrandrunrulesinthetile.



http://bosh.io

http://bosh.io


BOSHReleasesPagelastupdated:

ThistopicprovidesresourcesforcreatingaBOSHreleasethatintegratesasoftwareservicewithPivotalCloudFoundry(PCF)atthemanagedservicelevel.

OverviewABOSHreleaseisadirectorythatcontainsthesourcecodeforyourservicealongwitheverythingelsethatBOSHneedstodeployitreproduciblytocloudVMsrunningaspecifiedoperatingsystem(stemcell).Thesecontentsincludebutarenotlimitedtobuildpacks,startupscripts,binaryartifacts,andaBOSHmanifestcontainingconfigurationanddeploymentproperties.

TheBOSHmanifestspecifiesthefollowingmajorcomponents:

PackagesthatcanbeinstalledonPCFstemcellstocreatevirtualmachineimages

Jobsthatdescribehowtoinstall,run,andremoveyoursoftware

AMonitorscript,thatdescribeshowtomonitorthehealthofyourservicecomponentsandstoporrestartthem

BOSHResourcesThesetopicsgivemoredetailsonBOSHandBOSHreleases:

BOSHDocumentation isthetop-levelcontentspageforBOSHdocumentation.

BOSHProblemStatement explainswhatBOSHdoes.

BOSHBasicWorkflow liststhehigh-levelstepsforcreatingaBOSHdeployment.

CreatingaBOSHReleaseThesetopicsexplainhowtocreateaBOSHrelease:

CreatingaRelease

DefiningyourJobs

DefiningyourVMs

DefiningyourRuntimeConfigs

MonitoringtheHealthofyourService

Shortcut:StartwithDockerImagesIfyouhavealreadypackagedyourserviceasDockerimages,youcanemulateamanagedservicedeploymentusingtheTileGenerator’ssupportfordocker-bosh packages.Thisfeatureletsyoudeploypre-existingDockerimagesintoBOSHmanagedvirtualmachinesonthePCFinfrastructure.

Whilethisisagreat,easywaytodeployyourserviceonPCF,wedon’trecommendthisasalong-term,production-readysolution.ThereisreallynobenefitofrunningyourserviceincontainersontheVMs,anditdoeshaveanumberofoperational(“day2”)drawbacks:

Youintroducemoresoftware(Docker)whichneedstobekeptup-to-date,andhasthepotentialforbugs,downtime,andsecurityvulnerabilities.

YoucannolongertakeadvantageofthepatchingcapabilitiesofPCFforstemcellsandapplicationdependencies,likeframeworksandlibraries.Instead,youbecomedirectlyresponsibleformanagingallsoftwarethatisintheDockerimagesyoudeploy.


http://bosh.io/docs

http://bosh.io/docs/problems.html

http://bosh.io/docs/basic-workflow.html

http://bosh.io/docs/create-release.html

http://bosh.io/docs/jobs.html

http://bosh.io/docs/vm-struct.html

https://bosh.io/docs/runtime-config.html

http://bosh.io/docs/monitoring.html

ErrandsPagelastupdated:

LifecycleerrandsareBOSHerrands(scripts)thatrunatthebeginningandendofaninstalledproduct’savailabilitytime.Productteamscreateerrandsaspartofaproductpackage,andaproductcanonlyrunerrandsitincludes.

FormoreinformationaboutBOSHerrands,seeBOSHdocumentation ,andformoreinformationabouterrandsinPivotalCloudFoundry(PCF),seeManagingErrandsinOpsManager .

Productscanhavetwokindsoferrands.Post-deployerrandsrunafteraproductinstallsbutbeforeOpsManagerdisplaysmakesitavailableforuse.Pre-deleteerrandsrunafteranoperatorchoosestodeleteaproduct,butbeforeOpsManagerfinishesremovingitfromuse.

Tosavedeploymenttime,operatorscanseterrandrunrulesthatdictatewhetherornoterrandsrun.Tileauthorscansetdefaultsfortheserunrules.

Post-DeployErrandsPost-deployerrandsrunafteraproductinstalls,butbeforeOpsManagermakesitavailableforuse.

Typicalpost-installerrandsincludesmokeoracceptancetests,databaseinitializationordatabasemigration,andservicebrokerregistration.

Post-deployerrandsrunbydefault.Anoperatorcanpreventapost-deployerrandfromrunningbysettingitsrunruletoOffunderPendingChangesintheOpsManagerInstallationDashboardorontheproducttile’sSettingstabErrandspane,beforeinstallingtheproduct.

Forexample,RedishasaBrokerRegistrarpost-deployerrandthattheElasticRuntimetileusestoregisteritsservicebrokerwiththeCloudControllerandpublishitsserviceplans.

IfanoperatorchoosesOffinthedrop-downmenuforElasticRuntime’sBrokerRegistrarerrandbeforeinstallation,ElasticRuntime’sservicebrokerisnotregisteredwiththeCloudControlleranditsserviceplansarenotmadepublic.


https://bosh.io/docs/errands

http://docs.pivotal.io/pivotalcf/customizing/managing_errands.html

Pre-DeleteErrandsPre-deleteerrandsrunafteranoperatorchoosestodeleteaproduct,butbeforeOpsManageractuallyfinishesdeletingit.

Typicalpre-deleteerrandsincludecleanupofapplicationartifactsandservicebrokerde-registration.Forexample,PivotalMySQLhasaBrokerDeregistrarpre-deleteerrandthat:

Purgestheserviceoffering

Purgesallserviceinstances

Purgesallapplicationbindings

DeletestheservicebrokerfromtheCloudController

WhenanoperatorchoosestodeletethePivotalMySQLproduct,OpsManagerfirstrunstheBrokerDeregistrarpre-deleteerrand,thendeletestheproduct.

Pre-deleteerrandsrunbydefault.Anoperatorcanpreventapre-deleteerrandfromrunningbysettingitsrunruletoOffunderPendingChangesintheOpsManagerInstallationDashboardorontheproducttile’sSettingstabErrandspane,beforeinstallingtheproduct.

ErrandRunRules

Someerrandsdonotalwaysneedtorun.Forexample,installingaminorpatchtoaexistingservicemightnotrequirere-registeringitsbroker.OpsManagerletsoperatorssaveinstallationtimebyturningerrandsofforon.Theysettheseerrandrunrulesintwoplaces:

One-TimeRulesunderPendingChangesintheOpsManagerInstallationDashboard.TheserulesonlyapplytothenexttimeyourunApplyChangesanddonotpersistafterthenextsuccessfulinstallation.

PersistentRulesinthetile’sErrandspane.Theserulespersistthroughsubsequentinstallations,untilchangedintheErrandspane.

Formoreinformation,seeConfigureRunRulesinOpsManager .

warning:InOpsManagerv1.10.0andlater,errandssettotheWhenChangedruledonotalwaysrunwhenthetilehasrelevantchanges.InsteadofusingWhenChanged,PivotalrecommendsthattiledevelopersleavethedefaultrunruleforerrandsasOnandletoperatorsuseone-timerules toturnerrandsoffandsavedeploytime.


http://docs.pivotal.io/pivotalcf/customizing/managing_errands.html#changes-view

http://docs.pivotal.io/pivotalcf/customizing/managing_errands.html#modify

On-DemandServicePagelastupdated:

Thistopicexplainshowtointegrateyoursoftwareasanon-demandserviceandservicetileforPCF.

OverviewBrokeredserviceandmanagedserviceintegrationsassumethatyouhaveasingleVMinstancedeployedforyoursoftwaredeployed,oralimitednumberofVMs.

TheseVMscanbemulti-tenant,andyoucanpossiblyscalethemmanuallytoaccommodatemanyconcurrentapplications.Butforrealproductiondeployments,mostofyourcustomerswillwantdedicatedVMinstancesofyourserviceforeachapplication.

On-demand(dynamic)servicesenablethisflexibilityinascalableway.Whenanoperatordeploystheservice,donotpre-allocateVMresourcesforserviceinstances.Instead,theydefineanallowablerangeofVMmemoryandCPUsizesandcreateadedicatednetworkontheIaaStohostanyrequirednumberofserviceinstanceVMs.

Whenadevelopercreatesaninstanceofanon-demandservice,theyprovisionitsresourceswithintheallowedrange,andBOSHdynamicallycreatesanew,dedicatedVMfortheinstance.

CreateanOn-DemandServiceThebestwaytocreateanon-demandserviceistousetheOn-DemandServicesSDK .

Theon-demandservicesSDKprovidesagenericon-demandservicebroker(ODB)thatTileGeneratorcanconsumelikeanyotherservicebroker.

Theon-demandserviceauthordoesnotwriteaservicebroker.Instead,theywriteaserviceadaptercomponentthattakesrequestsfromtheODBandinterfaceswiththeirservicesoftwaretofulfillrequestsfromtheODB.

Tocreatetheirtile,thetileauthorthenfeedstheirserviceadapterandtheBOSHreleaseoftheODBtoTileGenerator.

[On-DemandServicesSDK]documentationexplainshowtowriteaserviceadapterforanon-demandservicethatusestheODB.

Onceyouhavetheindividualcomponentsforyourbrokeredserviceintegration,youcanworkthroughBuildingYourFirstTile tocreateyourtile.


HighAvailabilityIfyouhadnotalreadyconfiguredyourserviceforHighAvailabilityasamanagedservice,thefinalstepwouldbetoconsiderhowyoucanmakeeachofyourdynamically-provisionedserviceinstancesmorehighlyavailable.


http://docs.pivotal.io/on-demand-service-broker


BuildpacksPagelastupdated:

BuildpackscompileandpackageappstorunonPivotalCloudFoundry(PCF).ThistopiclistsresourcesforusinganddeployingbuildpackswithPCFapps,andforcreatingyourowncustombuildpack.

OfficialBuildpacksJavabuildpack (byfarthemostcomplicated!)

Gobuildpack

Rubybuildpack

Node.jsbuildpack

Pythonbuildpack

PHPbuildpack

Staticfilebuildpack (forstaticwebcontent)

Binarybuildpack

OtherBuildpacksBuildpackscanalsobeusedtoinjectadditionalcodeintotheapplicationcontainer.Formoreinformation,seethefollowing:

ThePCFdocumentationtopicCreatingCustomBuildpacks

ThegithubrepoEurekaRegistrarSidecar

ThegithubrepoSpringConfigInjection

CustomBuildpacksCreatingaCustomBuildpack


https://github.com/cloudfoundry/java-buildpack

https://github.com/cloudfoundry/go-buildpack

https://github.com/cloudfoundry/ruby-buildpack

https://github.com/cloudfoundry/nodejs-buildpack

https://github.com/cloudfoundry/python-buildpack

https://github.com/cloudfoundry/php-buildpack

https://github.com/cloudfoundry/staticfile-buildpack

https://github.com/cloudfoundry/binary-buildpack


https://github.com/cf-platform-eng/eureka-registrar-sidecar

https://github.com/cf-platform-eng/spring-config-injection

http://docs.pivotal.io/pivotalcf/buildpacks/custom.html

CredHubPagelastupdated:

CredHubisasecurecredentialmanagementcomponentthatrunsontheBOSHVMtominimizethesurfaceareawherecredentialscanbecompromised.ThistopicprovidesresourcesforconfiguringservicetilestouseCredHub,insteadofencodingcredentialsinproducttemplateandjobtemplatefiles.

SeetheCredHubdocumentation formoreinformation.

OverviewManyPCFcomponentsusecredentialstoauthenticateconnections,andPCFinstallationsoftenhavehundredsofactivecredentials.Securecredentialmanagementisessentialtopreventdataandsecuritybreaches.

InPivotalCloudFoundry(PCF)v1.11.0,CredHubrunsontheBOSHVM,alongsidetheBOSHDirectorandUAA.OpsManagerv1.11storesitscredentialsinCredHub,anduserscanretrievethemusingtheCredHubAPIortheCredentialstaboftheOpsManagerDirectortile.TiledeveloperscanembedCredHubcallsinmanifestsnippetsandPCFappscanretrievecredentialsusingtheCredHubAPI.

SeeFetchingVariableNamesandValuesforhowtofetchvariablenamesandvaluesusingtheCredHubAPI.

CredHubCredentialTypesCredHubstoresandretrievesthefollowingtypesofcredentials:

value —singlestringvalue

json —arbitraryJSONobject

password —passwordstring

certificate —objectcontainingcertificateauthority(CA),certificate,andprivatekey

ssh —objectcontainingSSHpublickeyandprivatekey

rsa —objectcontainingRSApublickeyandprivatekey

Formoreinformation,readCredHubCredentialTypes .

CreatingNewVariablesTouseCredHubinyourdeployment,youmustcreatenewvariablesandstoretheminCredHub.Bydefault,variablenamespacesarewrittentopreventcollisionacrossdeployments,butyoucantypevariablenamespreciselyifyouwish.

Formoreinformation,readCreatingNewVariablesinCredHub.

MigratingCredentialsTomigrateexistingnon-configurablecredentialstoCredHub,suchasblobstoresecretsandbackupencryptionkeys,usetheJavaScriptmigrationprocess.Afterasuccessfulmigration,OpsManagerdeletesthemigratedcredentialsfrominstallation.yml.

Formoreinformation,readMigratingExistingCredentialstoCredHub.

FetchingVariableNamesandValuesAPIendpointsareavailabletohelpyoufindvariablenamesandvaluesforproductsknowntotheOpsManagerDirector.

Formoreinformation,readFetchingVariableNamesandValues.


https://docs.cloudfoundry.org/credhub/index.html

https://docs.cloudfoundry.org/credhub/credential-types.html

CredHubinManifestSnippetsTiledeveloperscanembedCredHubinproducttemplateandjobtemplatemanifestsnippetsusingtriple-parenthesisnotation:

manifest:|credhub:concatenated_password:prefix-(((credhub-password)))-suffixpassword:(((credhub-password)))

PCFv1.11.0LimitationsPCFv1.11.0supportsCredHubforcredentialstorage,butitdoesnotsupportthefollowing:

AutomaticbackupandrestoreforCredHub,alongwithotherPCFsystemcomponents.

Automatictileupgradesthatmigratealltypesofcredentialsdefinedinpropertyblueprintsinprevioustileversions,tostorageinCredHub.

UsingCredHubtogeneratenewcredentials.

TileauthorsmaychoosetowaituntilPCFsupportssomeorallofthesefeaturesbeforeincorporatingCredHubintotheirservice.


CreatingNewVariablesinCredHubPagelastupdated:

ThistopicexplainshowCredHubmanagesvariablesinthecontextofalargerdeployment,andhowtocreatenewvariablesforuseinCredHub.

BackgroundWhenatileauthordefinesatop-level variables sectionintheproducttemplate,OpsManagerpassesthe variables sectiontotheproductmanifest.tileauthorscandefinevariablesintheproducttemplateasfollows:

variables:-name:EXAMPLE-CREDHUB-PASSWORDtype:password

Youcanreferencethesevariablesinthemanifestsnippetsintheirtilemetadatausingatripleparenthesessyntax:

(((EXAMPLE-CREDHUB-PASSWORD)))

UsingtripleparenthesesletsOpsManageridentifyCredHubvariableswhilestillsupportingtheBOSHdoubleparenthesessyntax.Avariablereferencedwithintripleparenthesesisreplacedbydoubleparenthesesinthegeneratedmanifest.AftercontactingCredHub,BOSHpopulatesthatvariablevalueinternally.

ThebenefitofthisapproachisthattheOpsManagerYAMLfiledoesnotcontainsensitivecredentialswhenthemetadatamanifestsnippetshavetripleparentheses.Theresultingmanifestfilecontainsvariableswithindoubleparentheses,ratherthanunobscuredcredentials.

Forexample,atileauthoraddscredentialstoamanifestsnippetinthefollowingformat:

key:(((EXAMPLE-CREDHUB-PASSWORD)))key:prefix-(((ANOTHER-CREDHUB-PASSWORD)))-suffix

OpsManagerevaluatestheaboveexampletogeneratethefollowingsectionintheproductmanifest:

((EXAMPLE-CREDHUB-PASSWORD))prefix-((ANOTHER-CREDHUB-PASSWORD))-suffix

HowCredHubWorksWithinaDeploymentCredHubisdistributedasaBOSHrelease.Aspartofthisinstallation,OpsManagerco-locatestheCredHubreleaseontheOpsManagerDirector,includingtheCredHubjobconfigurations,andtheDirectorisconfiguredtopointtotheCredHubAPI.

OnceCredHubhasbeendeployedandconfiguredontheDirector,anyDirectordeploymentcanuseCredHubvariablesinplaceofcredentialvalues.Usingvariables,ratherthanvalues,providesanextralayerofsecuritywhentransmittingcredentialswithinyourdeployment.

ChangingYourDeploymentManifesttoIncludeCredHubVariablesTheOpsManagerDirectorinterpolatescredentialvaluesintomanifeststhatusethe ((variables)) syntax.WhentheDirectorencountersavariableusingthissyntax,itrequeststhecredentialvaluefromCredHub.Ifthecredentialdoesnotexistandthereleaseormanifestcontainsgenerationproperties,thecredentialvalueisgeneratedautomatically.

Themanifestexcerptbelowincludesreferencestotwocredentials, EXAMPLE-PASSWORD and EXAMPLE-TLS .

Whenthismanifestisdeployed,theOpsManagerDirectorretrievesthestoredvariablesandreplacesthemwiththecredentialvaluesassociatedwitheachvariable.The EXAMPLE-TLS variablesincludepropertyaccessors,soonlythe certificate and private_key componentsareinterpolated.


name:demo-deploy

instance_groups:jobs:-name:demorelease:demoproperties:demo:password:((EXAMPLE-PASSWORD))tls:certificate:((EXAMPLE-TLS.certificate))private_key:((EXAMPLE-TLS.private_key))

OpsManagerconfigurestheDirectortogenerateacredentialifitdoesnotexist.Themanifestincludesgenerationparametersthatdefinehowthecredentialshouldbegenerated.Thesegenerationparametersaredefinedinthevariablessectionasshownbelow.

---name:demodeploy

variables:-name:EXAMPLE-PASSWORDtype:password-name:EXAMPLE-CAtype:certificateoptions:is_ca:truecommon_name:'ExampleCertificateAuthority'-name:EXAMPLE-TLStype:certificateoptions:ca:EXAMPLE-CAcommon_name:example.com

instance_groups:jobs:-name:demorelease:demoproperties:demo:password:((EXAMPLE-PASSWORD))tls:certificate:((EXAMPLE-TLS.certificate))private_key:((EXAMPLE-TLS.private_key))

VariableNamespacingDeploymentmanifestsoftenusecommonvariablenames;forexample, ((PASSWORD)) .Toavoidvariablenamecollisionsbetweendeployments,theOpsManagerDirectorautomaticallystoresvariableswiththeOpsManagerDirectornameanddeploymentname.Forexample,thevariable((EXAMPLE-PASSWORD)) isstoredinCredHubas/Ops-Manager-Director-name/deployment-name/example-password.

OtherNamespacingOptionsUseaBOSHlinktosharecredentialsacrossdeployments.Alternatively,ifyouwanttouseanexactname,prefixingthevariablewithaforwardslash(/)willcausetheDirectortousetheexactnameyoutype.Anexampleofapreciselytypedvariablefollows.

((/EXAMPLE-PASSWORD))


MigratingExistingCredentialstoCredHubPagelastupdated:

Thistopicexplainshowtomigratenon-configurablesecretsfromOpsManagerintoCredHub.

CredHubCredentialTypesCredHubusesBOSHcredentialtypes,whichmayhavedifferentnamesfromOpsManagercredentialtypes.ThefollowingtableliststheOpsManagercredentialtypesyoucanmigratetoCredHubandthecorrespondingCredHubcredentialtypes.

OpsManagerCredentialType CredHubCredentialType SupportedOpsManagerVersion

secret password 1.11.1

simple_credential user 1.12Alpha1

salted_credential user 1.12Beta1

rsa_pkey_credential rsa 1.12Alpha1

SeePropertyReferenceformoreinformationaboutcredentialtypes.

UsetheJavaScriptMigrationProcessTileauthorscanwriteaJavaScriptmigrationtomovetheirexistingnon-configurablesecretsintoCredHub.Afterasuccessfulmigration,OpsManagerdeletescredentialsfrominstallation.yml.

1. UsethefollowingexampletowritetheJavaScriptmigration.SavetheJavaScriptfiletothePRODUCT/migrations/v1directoryofyour.pivotaltile,followingthenamingconventionsdiscussedintheUpdateValuesorPropertyNamesUsingJavaScripttopic.

exports.migrate=function(input){input.variable_migrations.push({from:input.properties['.PROPERTY-REFERENCE.EXAMPLE-SECRET'],to_variable:'SECRET-VARIABLE'});returninput;};

Inthecodeblockabove,replacetheexampletextasfollows:

PROPERTY-REFERENCE :Replacewiththepropertyreferencethatcorrespondstothemetadatafile,suchas properties .SeeTileUpgradesformoreinformationaboutmigratingproperties.EXAMPLE-SECRET :Replacewiththenameofthekey.SECRET-VARIABLE :Chooseavariablenameforthemigratedsecret.

2. RemovethepropertyblueprintforthesecretandreplaceitwithaCredHubvariable.

Inyourmetadata,removetheblockthatincludesthecredential.Forexample,removetheblockthatincludes -name:EXAMPLE-SECRET andtype:secret :

property_blueprints:-name:EXAMPLE-SECRETtype:secret-name:generated_uuidtype:uuid-name:configured_secrettype:secretconfigurable:trueoptional:true-name:configured_simple_credentialstype:simple_credentialsconfigurable:trueoptional:true

Note:CredHubdoesnotretainthesaltwhenmigrating salted_credentials .


Inhandcraft.yml,addavariablessectionandincludethevariablenameandtype:

variables:-name:SECRET-VARIABLEtype:password

3. Inyourmanifestsnippet,replacetheexistingsecretvaluewiththenewtriple-parenthesissyntax.

Removetheexistingsecretfromthemanifestsnippet:

secret:((.PROPERTY-REFERENCE.SECRET-VARIABLE.SECRET-VALUE))

AddthenewCredHubvariabletothemanifestsnippet:

secret:(((SECRET-VARIABLE)))

4. Runatestdeployofyourtile.

5. UseanAPIendpointtoconfirmthatthecredentialisstoredinthevariable.Formoreinformationabouttheendpoint,seeFetchingVariableNamesandValues.

Note:Whilethepropertyblueprintreferstotheabovetypeas secret ,BOSHreferstothetypeas password .SeetheCredHubCredentialTypestableatthebeginningofthistopicformoreinformationaboutcredentialtypes.


FetchingVariableNamesandValuesPagelastupdated:

OverviewCredHubhastwoAPIendpointstoidentifyandre-usevariables.Operatorswhowanttoseeallthecredentialsassociatedwiththeirproduct,orsupportengineerswhowanttotroubleshootissuesspecifictoonevirtualmachine(VM),canusetheseAPIsforthosepurposes.

TheAPIendpointsperformthesefunctions:

Identifyingandprintingthenameofavariable

Usingthenameofthevariabletoidentifyandprintthevalueofthevariable

UsingtheAPIEndpointsUsetheseendpointstoviewvariablesforanyproductinOpsManager,excepttheOpsManagerDirector.Theseendpointsareread-only.Youcannotusethemtoadd,remove,orrotatevariables.

FetchingVariablesThisendpointreturnsthelistofvariablesassociatedwithaproductthatarestoredinCredHub.NotallvariablesarestoredinCredHub.IfyoucallavariablethatisnotstoredinCredHub,thecallreturnsanemptyvalue.

$curl"https://OPS-MAN-FQDN/api/v0/deployed/products/product-guid/variables"\-XGET\-H"Authorization:BearerEXAMPLE_UAA_ACCESS_TOKEN"

ExampleResponse

HTTP/1.1200OK

{"variables":["FIRST-EXAMPLE-VARIABLE","SECOND-EXAMPLE-VARIABLE","THIRD-EXAMPLE-VARIABLE"]}

QueryParameters

Parameter Description

product_guid Theuniqueproductidentifier,formattedasatextstring

Thisendpointreturnsavariable’sname.Usethenameinthenextendpointtoreturnthevariable’svalue.

FetchingVariableValuesThisendpointreturnsthevalueofavariablestoredinCredHub.NotallvariablesarestoredinCredHub,soifyoucallavariablethatisn’tinCredHub,thecallwillreturnanemptyvalue.

$curl"https://OPS-MAN-FQDN/api/v0/deployed/products/product-guid/variables?name=EXAMPLE-VARIABLE-NAME"\-XGET\-H"Authorization:BearerUAA_ACCESS_TOKEN"


ExampleResponse

HTTP/1.1200OK

{"credhub-password":"EXAMPLE-PASSWORD"}

QueryParameters

Parameter Description

variable_name Thenameofthevariable,formattedasatextstring

product_guid Theuniqueproductidentifier,formattedasatextstring


EmbeddedAgentsPagelastupdated:

Thistopicprovidesresourcesforconfiguringservicesthatusesoftwareagentsembeddedinapplicationcontainers.

OverviewSomeserviceintegrationsdependontheabilitytoinjectcodeintoapplicationcontainers.Examplesinclude:

ApplicationPerformanceMonitoring(APM)agentsformonitoringservices

Container-embeddedAPIgateways

Client-siderouters

Werefertotheseinjectedcomponentsas“container-embeddedagents.”

EmbeddedAgentsResourcesBuildpacksprovideamechanismtoinjectcomponentsintotheapplicationcontainerimage,andthe .profile.d directoryprovidesawaytostartagentsbeforeoralongsidethecustomerapplication.

Using.profile.d


http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/deploy-app.html#profiled

Logs,Metrics,andNozzlesPagelastupdated:

ThistopicexplainshowtointegratePCFserviceswithCloudFoundry’sloggingsystem,theLoggregator,bywritingtoandreadingfromitsFirehoseendpoint.

OverviewCloudFoundry’sLoggregatorloggingsystemcollectslogsandmetricsfromPCFappsandplatformcomponentsandstreamsthemtoasingleendpoint,theFirehose.YourtilecanintegrateitsservicewiththeLoggregatorsystemintwoways:

BysendingyourservicecomponentlogsandmetricstotheFirehose,tobestreamedalongwithPCFcoreplatformcomponentlogsandmetrics.

ByinstallinganozzleontheFirehosethatdirectsFirehosedatatobeconsumedbyexternalservicesorapps.Abuilt-innozzlecanenableaserviceto:

Drainmetricstoanexternaldashboardproduct,forsystemoperatorsSendHTTPrequestdetailstosearchoranalysistoolsDrainapplogstoanexternalsystemAuto-scaleitself basedonFirehosemetrics

Firehose-to-syslog isarealworld,productionexampleofanozzle.

FirehoseCommunicationPCFcomponentspublishlogsandmetricstotheFirehosethroughMetronagentprocessesthatrunlocallyonthecomponentVMs.MetronagentsinputthedatatotheLoggregatorsystembywritingittoLoggregator’setcd key-valuestoreviaagRPC proxy.ThetopicOverviewoftheLoggregatorSystem showshowlogsandmetricstravelfromPCFsystemcomponentstotheFirehose.

ComponentVMsrunningPCFservicescanpublishlogsandmetricsthesameway,byincludingaMetronagentthatwritestoetcd.InPCFv1.10andlater,componentsonlycommunicatewith etcd viasecure,encrypted https protocol.EarlierversionsofPCFallowbothencrypted https andunencryptedhttp communicationswithetcd.

SecureHTTPSProtocol:PCF1.10+ToenableaservicecomponenttosupplylogsandmetricstotheFirehosethroughencryptedcommunications,youneedtoincludeaMetronagentandaConsulagentinitstemplatedefinitions.

TheMetrondefinitionincludesdouble-parenpropertiesdefiningakeypairforaccessingetcd.TheConsuldefinitionincludesdouble-parenpropertiesforsecurelylookinguptheinternalIPaddressesoftheetcdnodesat cf-etcd.service.cf.internal .Thisavoidshard-codinganyetcdserveraddresses.

Forexample:


https://youtu.be/skJKvQfpKD4?t=1021

https://github.com/cloudfoundry-community/firehose-to-syslog

https://coreos.com/etcd/

https://coreos.com/etcd/docs/latest/op-guide/grpc_proxy.html

https://docs.cloudfoundry.org/loggregator/architecture.html

name:servicelabel:Servicetemplates:-name:consulrelease:consul-name:metron_agentrelease:loggregator-name:servicerelease:servicemanifest:|metron_agent:deployment:cf-my-serviceetcd:client_cert:((..cf.properties.cf_etcd_client_cert.cert_pem))client_key:((..cf.properties.cf_etcd_client_cert.private_key_pem))metron_endpoint:shared_secret:((..cf.doppler.shared_secret_credentials.password))loggregator:etcd:require_ssl:truemachines:['cf-etcd.service.cf.internal']ca_cert:(($ops_manager.ca_certificate))consul:encrypt_keys:-((..cf.properties.consul_encrypt_key.value))ca_cert:(($ops_manager.ca_certificate))agent_cert:((..cf.properties.consul_agent_cert.cert_pem))agent_key:((..cf.properties.consul_agent_cert.private_key_pem))agent:domain:cf.internalservers:lan:((..cf.consul_server.ips))

Metronversionsv72andlaterdonotuseetcdtocommunicatewithLoggregator,buttheconfigurationaboveworkswithanyversionofMetron.IftheMetronagentdoesnotneedvaluesforetcd,itsafelyignoresthem.

HTTPProtocol:PCF1.9andEarlierInPCFv1.9,servicecomponentscansendlogsandmetricstotheFirehoseencryptedorunencrypted.Inv1.8andearlierreleases,componentsonlycommunicatetheirlogandmetricsdataunencrypted.

Toenableunencryptedcommunicationswithetcd,defineaMetronagentandlisttheaddressesoftheetcdserversinthetemplatedefinitionsasfollows:

name:servicelabel:Servicetemplates:-name:metron_agentrelease:loggregator-name:servicerelease:servicemanifest:|metron_agent:deployment:cf-my-servicemetron_endpoint:shared_secret:((..cf.doppler.shared_secret_credentials.password))loggregator:etcd:machines:((..cf.etcd_server.ips))

NozzlesAnozzleisacomponentdedicatedtoreadingandprocessingdatathatstreamsfromtheFirehose.Aservicetilecaninstallanozzleaseitheramanagedservice,withpackagetype bosh-release ;orasanapppushedtoElasticRuntime,withthepackagetype app .

DevelopaNozzlePivotalrecommendsdevelopinganozzleinGo,toleveragetheNOAAlibrary .NOAAdoestheheavyliftingofestablishinganauthenticatedwebsocketconnectiontotheloggingsystemaswellasde-serializingtheprotocolbuffers.


https://github.com/cloudfoundry/noaa

Drainingthelogsconsistsof:

1. Authenticating

2. Establishingaconnectiontotheloggingsystem

3. Forwardingeventsontotheirultimatedestination

AuthenticateagainsttheAPI(https://github.com/cloudfoundry-community/go-cfclient )withauserinthe doppler.firehose group:

import"github.com/cloudfoundry-community/go-cfclient"

...

config:=&cfclient.Config{ApiAddress:apiUrl,Username:username,Password:password,SkipSslValidation:sslSkipVerify,}

client,err:=cfclient.NewClient(config)

Usingtheclient’stoken,createaconsumerandconnecttotheFirehosewithasubscriptionid.Theidisimportant,sincetheFirehoselooksforconnectionshavingthesameidandonlysendsaneventtooneofthoseconnections.Thisishowanozzledevelopercanpreventmessagelossduringupgradesanotherdeployments:runatleasttwoinstances.

token,err:=client.GetToken()

consumer:=consumer.New(config.TrafficControllerURL,&tls.Config{InsecureSkipVerify:config.SkipSSL,},nil)events,errors:=consumer.Firehose(firehoseSubscriptionID,token)

Firehose willgivebacktwochannels:oneforeventsandasecondforerrors.

Theeventschannelreceivessixdifferenttypesofevents.

ValueMetric:Someplatformmetricatapointintime,emittedbyplatformcomponents.Forexample,howmany 2xx responsestherouterhassentout.

CounterEvent:Anincrementingcounter,emittedbyplatformcomponents.Forexample,aDiegocell’sremainingmemorycapacity.

Error:Anerror.

HttpStartStop:HTTPrequestdetails,includingbothappandplatformrequests.

LogMessage:Alogmessageforanindividualapp.

ContainerMetric:Applicationcontainerinformation.Forexample,memoryused.

Forthefulldetailsonevents,seethedropsondeprotocol .

Theaboveeventsshowhowthisdatatargetstwodifferentpersonae:platformoperatorsandappdevelopers.Keepthisinmindwhendesigninganintegration.

Having doppler.firehose scopegetsanozzledataforeveryappaswellastheplatform.Anyfilteringbasedontheeventpayloadisthenozzleimplementor’sresponsibility.Anadvancedintegrationcoulddosomethinglikecombineaservicebrokerwithanozzleto:

Letappdevelopersopt-intologging(implementingfilteringinthenozzle)

EstablishSSO exchangeforauthenticationsuchthatdevelopersonlycanaccesslogsfortheirspace’sapps

Forafullworkingexample(suitableasanintegrationstartingpoint),seefirehose-nozzle .

DeployaNozzleOnceyou’vebuildanozzle,youcandeployitaseitheramanagedserviceorasanapp.

AsaManagedService


https://github.com/cloudfoundry-community/go-cfclient

https://github.com/cloudfoundry/dropsonde-protocol/tree/master/events

https://docs.cloudfoundry.org/services/dashboard-sso.html

https://github.com/cf-platform-eng/firehose-nozzle

Visitmanagedserviceformoredetailsonwhatitmeanstobeamanagedservice.

SeealsothisexamplenozzleBOSHrelease .

AsanApp

YoucanalsodeploythenozzleasanapponElasticRuntime.VisittheTileGenerator’ssectiononpushedappsformoredetails.

ExampleNozzlesThereareseveralopensourceexamplesyoucoulduseasareferenceforbuildingyournozzle

firehose-nozzle

Examplethatsimplywritestostandardout

Usefulstartingpoint:scaffolding,tests,etcareinplace

example-nozzle

Asinglefileimplementationwithnotests:asminimalasthingscanget

gcp-tools-release

InadditiontoNozzledata,itdrainscomponentsyslogsandhealthdata

Showshowtodoabosh-addon(foradditionaldataoutsideanozzle)

NozzleismanagedthroughBOSH

Rawlogsandmetricsdatatakedifferentpathsinthesource

firehose-to-syslog

Includesimplementationcodethataddsadditionalmetadata,whichmightbeneededforanaccesscontrollist(ACL)

AppnameSpaceUUIDandnameOrgUUIDandname

logsearch-for-cloudfoundry packagesthisnozzleasaBOSHrelease

splunk-firehose-nozzle

Sourcecodebasedon firehose-to-syslog

PackagedtorunanapponPCF

datadog-firehose-nozzle

Anotherrealworldimplementation

LogFormatforPCFComponentsPivotal’sstandardlogformatadherestotheRFC-5424syslogprotocol ,withlogmessagesformattedasfollows:

<${PRI}>${VERSION}${TIMESTAMP}${HOST_IP}${APP_NAME}${PROD_ID}${MSG_ID}${SD-ELEMENT-instance}${MESSAGE}

TheSyslogMessageElementstableimmediatelybelowdescribeseachelementofthelog,andtheStructuredInstanceDataFormattabledescribesthecontentsofthestructureddataelementthatcarriesCloudFoundryVMinstanceinformation.

SyslogMessageElementsThistabledescribeseachelementofastandardPCFsyslogmessage.


https://github.com/cloudfoundry-incubator/example-nozzle-release

https://github.com/cf-platform-eng/firehose-nozzle

https://github.com/cloudfoundry-incubator/example-nozzle

https://github.com/cloudfoundry-community/gcp-tools-release

https://github.com/cloudfoundry-community/firehose-to-syslog

https://github.com/cloudfoundry-community/logsearch-for-cloudfoundry

https://github.com/cf-platform-eng/splunk-firehose-nozzle

https://github.com/DataDog/datadog-firehose-nozzle

https://tools.ietf.org/html/rfc5424

SyslogMessageElement

MeaningorValue

${PRI}

Priorityvalue(PRI) ,calculatedas 8×FacilityCode+SeverityCode

PivotalusesaFacilityCodevalueof 1 ,indicatingauser-levelfacility.Thisadds 8 totheRFC-5424SeverityCodes,resultinginthenumberslistedinthetablebelow.

Ifindoubt,defaultto 13 ,toindicateNotice-levelseverity.

${VERSION} 1

${TIMESTAMP}Thetimestamp ofwhenthelogmessageisforwarded;typicallyslightlyafteritwasgenerated.Example:2017-07-24T05:14:15.000003Z

${HOST_IP} InternalIPaddress oforiginserver

${APP_NAME}

Processname oftheprogramthegeneratedthemessage.Prefixedwith vcap .Forexample:

vcap.rep

vcap.garden

vcap.cloud_controller_ng

YoucanderivethisprocessnamefromeithertheprogramnameconfiguredforthelocalMetronagentorthe :progname thatblackboxderivesfromthefolderthatsyslog-releaseforwardslogsinto.

${PROD_ID}TheProcessID ofthesyslogprocessdoingtheforwarding.Ifthisisnoteasilyavailable,defaultto - (hyphen)toindicateunknown.

${MSG_ID} Thetype oflogmessage.Ifthisisnoteasilyavailable,defaultto - (hyphen)toindicateunknown.

${SD-ELEMENT-instance}

Structureddata(SD)relevanttoPCFaboutthesourceinstance(VM) thatoriginatesthelogmessage.SeetheStructuredInstanceDataFormattablebelowforcontentandformat.

${MESSAGE} Thelogmessageitself,ideallyinJSON

RFC-5424SeverityCodesPCFcomponentsgeneratelogmessageswiththefollowingseveritylevels.Themostcommonseveritylevelis 13 .

SeverityCode Meaning

8 Emergency:systemisunusable

9 Alert:actionmustbetakenimmediately

10 Critical:criticalconditions

11 Error:errorconditions

12 Warning:warningconditions

13 Notice:normalbutsignificantcondition

14 Informational:informationalmessages

15 Debug:debug-levelmessages

StructuredInstanceDataFormatTheRFC-5424syslogprotocolincludesastructureddataelement thatpeoplecanuseastheyseefit.PivotalusesthiselementtocarryVMinstanceinformationasfollows:

SD-ELEMENT-instance

elementMeaning

${ENTERPRISE_ID} YourEnterpriseNumber,aslisted bytheInternetAssignedNumbersAuthority(IANA)


https://tools.ietf.org/html/rfc5424#section-6.2.1

https://tools.ietf.org/html/rfc5424#section-9.1

https://tools.ietf.org/html/rfc5424#section-9.1







https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers

${DIRECTOR} TheBOSHdirectormanagingthedeployment.

${DEPLOYMENT} BOSH spec.deployment value

${INSTANCE_GROUP} BOSH instance_group ,currently spec.job.name

${AVAILABILITY_ZONE} BOSH spec.az value

${ID}BOSH spec.id value.ThisisaGUID,notanindex.NecessarybecauseBOSHAvailabilityZoneindexvaluesarenotalwaysuniqueorsequential.

MakingSenseofMetricsMonitoringPivotalCloudFoundry hasagreatrundownofthevariousmetricsandhowtomakethemuseful.

OtherResourcesCFSummitVideoMonitoringCloudFoundry:LearningabouttheFirehose

LoggregatorGitHubrepository

OverviewoftheLoggregatorSystem

Loggregator’sSlackChannel


https://docs.pivotal.io/pivotalcf/monitoring/index.html

https://youtu.be/skJKvQfpKD4

https://github.com/cloudfoundry/loggregator/

https://docs.cloudfoundry.org/loggregator/architecture.html

https://cloudfoundry.slack.com/messages/loggregator/

DevelopmentToolsPagelastupdated:

ThetopicsinthissectiondescribetoolsthatPivotalusesandrecommendsfortiledevelopment.

TileGeneratortakesaservicesoftware,aservicebroker,optionalothercomponents,andasimpleconfigurationfileandcreatesatileandeverythingelserequiredtodeployyoursoftwareintoPCF.

ThepcfCommandLineUtilityprovidesacommandlineinterfacefordeployingandtestingPCFtiles,toavoidthelongerprocessofgoingthroughtheOpsManagerGUI.

Concourseisacontinuousintegration(CI)platformwhereyoucancreatebuildpipelinesthatautomateandstreamlineyourtiledevelopmentandintegrationwithPCF.

TheServicesSDKisasuiteoftoolsdesignedtohelpyoubuildenterprise-readyserviceofferingsfortheMarketplace.TheSDKincludestheOnDemandServiceBroker ,ServiceMetricsforPCF ,andServiceBackupsforPCF .


https://docs.pivotal.io/on-demand-service-broker

https://docs.pivotal.io/service-metrics

https://docs.pivotal.io/service-backup/

DevelopmentEnvironmentsPagelastupdated:

Thistopicexplainshowtosetuptiledevelopmentenvironments,fromsimplestandalonetoolstoafullPCFdevelopmentenvironment.Asyouprogressthroughthestagesoftiledevelopment,youwilllikelyalsoprogressthroughtheseenvironments.

PCFDevandBOSHLitePivotalprovidesalightweight(vagrantpackaged)instanceofPCFwithsomebasicservicesasafreeproductnamedPCFDev.ThisisagreatenvironmenttodevelopandtesteverythingthatrunsintheCloudFoundryElasticRuntime.

EitheroftheseenvironmentsallowyoutodevelopthefirstthreelevelsofserviceforPivotalCloudFoundry(PCF):aUser-ProvidedService,aBrokeredService,andaManagedService.

Ifyourintegrationincludesmanagedservices,youwillalsoneedaninstanceofBOSHthatcanmanagevirtualmachinesandBOSHreleasesforyou.BOSH-Lite workswellforthatpurpose.

Betweenthesetwocomponents,youwillhaveeverythingyouneedtodeveloptiles,exceptforPivotal’sOpsManager.ButifyoufollowedtherecommendedworkflowinBuildingYourFirstTile youwillnotneedanactualfullPCFenvironmentuntilthelaterphasesofyourdevelopment.

SettingupBOSH-LiteInstallBOSH-Lite

SettingupPCFDevTryPCFonyourLocalWorkstation

PWSorOtherSupportedCFInfrastructureSetUpYourPWSAccountandDownloadthecfCLI explainshowtogetstartedwithPivotalWebServices(PWS),ahighly-available,production-scalePCFenvironmenthostedbyPivotal.

PCFwithOpsManager

PartnerswhoparticipateinourprogramhaveaccesstoanumberofsharedPCFenvironmentsthatareoperatedandmanagedbyPivotal.Ifyouarenot(yet)inourprogram,needadedicatedenvironment,orwanttobeabletoworkoffline,youcansetupyourownenvironment.Often,adeveloperenvironmentissufficientfortheearlyphasesofanintegrationeffort.Buteventually,youwillneedaccesstoacompleteenvironmentthatincludesPivotal’sOpsManagerononeofthesupportedinfrastructures:

InstallingPivotalCloudFoundry

OperatingPivotalCloudFoundry

UpgradingPivotalCloudFoundry

Note:Forthistypeofdevelopmentenvironment,youonlyneedBOSH-Liteitselftodeploymanagedservicereleases.YoudonotneedtofollowtheinstructionstoDeployCloudFoundryinBOSH-Lite,asCloudFoundryisprovidedbythePCFDevinstallationabove.


https://github.com/cloudfoundry/bosh-lite


https://github.com/cloudfoundry/bosh-lite

http://pivotal.io/platform/pcf-tutorials/getting-started-with-pivotal-cloud-foundry-dev/introduction

http://docs.run.pivotal.io/starting/index.html

http://docs.pivotal.io/pivotalcf/installing/index.html

http://docs.pivotal.io/pivotalcf/opsguide/index.html

http://docs.pivotal.io/pivotalcf/customizing/upgrading-pcf.html

TileGeneratorPagelastupdated:

ThistopicdescribestheTileGeneratortool,whichhelpstileauthorsdevelop,package,test,anddeployservicesandotheradd-onstoPivotalCloudFoundry(PCF).

OverviewTilesaretheinstallationpackageformatusedbyPivotalOpsManagertodeployservicesandotheradd-onstobothpublicandprivateclouddeployments.TileGeneratorusestemplatesandpatternsthatarebasedonyearsofexperienceintegratingthird-partyservicesintoCloudFoundryandeliminatesmuchoftheneedforyoutohaveintimateknowledgeofallthetoolsinvolved.

TileGeneratortakesyoursoftwarecomponentsandasimpleconfigurationfilethatprovidestheminimalamountofinformationtodescribeandcustomizeyourtile.Itthencreateseverythingthat’srequiredtodeployyoursoftwareintoPCF:

BOSHerrandstodeployanddeleteyoursoftware,includingblue/greendeploymentsforzero-downtimeupgrades

ABOSHreleasesuitablefordeployingyoursoftwaretotheElasticRuntimeoropen-sourceCloudFoundry

APivotalOpsManagerTilethatcanbeimportedintoOpsManager,installed,configured,anddeployed,includingUIformsandautomaticupgradesfrompreviousversions

AConcoursepipelineconfigurationtoenableContinuousIntegrationofyoursoftwarewiththelatestversionsofPCF

UseTileGeneratorincombinationwiththepcfutilitytoenablerapiddeployandtestcyclesofyoursoftware.

ThecurrentreleaseofTileGeneratorsupportstilesthathaveanycombinationofthefollowingpackagetypes:

CloudFoundryApplications

CloudFoundryBuildpacks

CloudFoundryServiceBrokers(bothinsideandoutsidetheElasticRuntime)

Dockerimages(bothinsideandoutsidetheElasticRuntime)

LegacyTilesandOSS-CompatibleServiceBrokersManytileauthors,inbothPivotal-internalteamsandatexternalpartnercompanies,builttheirPCFtilesbeforeTileGeneratorexisted.

Manyothertileauthorsservetwomarketswiththeirserviceintegrations,offeringbothaCloudFoundry-compatibleservicebrokertoopen-sourceusersandcorrespondingPCFtileforPCFusers.Theywanttocontinueservingbothsetsofusers.

AllofthesetileauthorscannowuseTileGeneratortosimplifyandspeeduptheirdevelopment.TileGeneratorcangenerateanOSS-compatibleBOSHreleaseservicebrokerBOSHreleaseinadditiontoaPivNet-readyPCFtile.


ScreencastFora7-minuteintroductionintowhatTileGeneratorisanddoes,seethisscreencast .

HowtoUse1. Installthetile-generatorpythonpackage.

Pivotalrecommendsusingavirtualenv environmenttoavoidconflictswithotherPythonpackages.Avirtualenvissimplyadirectorycontainingdependenciesforaproject.Whenavirtualenvironmentisactive,packagesinstallintothevirtualenvinsteadofthesystem-widePythoninstallation.Createavirtualenvwiththe virtualenv command:

virtualenv-ppython2tile-generator-env

Toactivatethevirtualenv,sourcethebin/activatescriptinthevirtualenvdirectory:

sourcetile-generator-env/bin/activate

Theninstallthetile-generatorpackageinsidethevirtualenvwith:

pipinstalltile-generator

Thisputsthe tile and pcf commandsinyour PATH whenthevirtualenvisactive.Todeactivatethevirtualenv,simplyrunthecommanddeactivate .

2. InstalltheBOSHCLI

3. Fromwithintherootdirectoryoftheprojectforwhichyouwanttocreateatile,initializeitasatilerepository.Pivotalrecommendsthatyouuseagitrepository:

cdYOUR-PROD-DIRECTORYtileinit

4. Editthegenerated tile.yml filetodefineyourtile.

5. Buildyourtile:

tilebuild

ThegeneratorfirstcreatesaBOSHreleaseinthe release subdirectory,thenwrapthatreleaseintoaPivotaltile(inthe product subdirectory).Ifrequiredfortheinstallation,itautomaticallypullsdownthelatestreleaseversionoftheCloudFoundryCLI.

TileGeneratorisalsoavailablepre-installedinaDockerimageonDockerHub .Thisimagecontainsthetile-generator tile and pcf commands,allthenecessaryPythondependencies,aswellastheBOSHCLI.

YoucanusethisinConcoursepipelinesbyspecifyingitasthebaseimageforyourtasks:

-task:tile-buildconfig:platform:linuximage:cfplatformeng/tile-generator

Or,youcanderiveyourownDockerimagesfromthisonebyusingitasthebaseimageinyourDockerfile:

FROMcfplatformeng/tile-generator

Note:Thetile-generatorrequiresPython2anddoesnotworkwithPython3.

Note:ToupgradeTileGenerator,runthefollowingcommandwiththevirtualenvactivated: pipinstalltile-generator--upgrade


https://www.youtube.com/watch?v=_WeJbqNJWzQ

https://virtualenv.pypa.io/en/stable/

https://bosh.io/docs/cli-v2.html

https://hub.docker.com/r/cfplatformeng/tile-generator/

BuildtheSampleThetile-generatorrepository includesasampletile thatexercisesmostofthefeaturesofTileGenerator.ThissampletileisusedbyTileGenerator’sCIpipelinetoverifythatthingsworkcorrectly.Youcanbuildthissampleusingthefollowingsteps:

1. DownloadtheRedisBOSHrelease andsaveitto sample/resources/redis-13.1.2.tgz .

2. Runthefollowingcommands:

cdsamplesrc/build.shtilebuild

DefineyourTileintile.ymlAllrequiredconfigurationforyourtileisinthefilecalled tile.yml . tile

initcreatesaninitialversionforyouthatcanserveasatemplate.Thefirstsectionin

thefiledescribesthegeneralpropertiesofyourtile:

name:tile-name#MatchPivotalNetworkproductname,lowercasewithdashesicon_file:resources/icon.pnglabel:BriefTextfortheTileIcondescription:Longerdescriptionofthetile'spurpose

The name shouldbeinformative,forexample,yourcompanynamefollowedbytheproductname,e.g., acme-anvil .ThenameshouldmatchyourproductslugonPivotalNetwork,whichenablesupdatenotificationsforcustomers.Coordinatewithyourproductteamtoagreeuponaname;marketingteamsoftencareaboutthenamebecauseitshowsupinPivotalNetworkURLs.

The icon_file shouldbea128x128pixelimagethatappearsonyourtileintheOpsManagerGUI.Byconvention,anyresourcesusedbythetileshouldbeplacedinthe resources sub-directoryofyourrepository,althoughthisisnotmandatory.The label textappearsonthetileunderyouricon.

PackagesNextyoucanspecifythepackagestobeincludedinyourtile.Theformatofeachpackageentrydependsonthetypeofpackageyouareadding.

PushedApps

Apps(includingservicebrokers)thatarebeing cfpush edintotheElasticRuntimeusethefollowingformat:

Note:ThesampletileincludesaPythonappthatisre-usedinseveralpackages,sometimesasanapp,sometimesasaservicebroker.Oneofthedeployments(app3)usesthesampleappinsideaDockerimagethatiscurrentlyonlymodifiedbytheCIpipeline.Ifyoumodifythesampleapp,youhavetobuildyourownDockerimageusingtheprovided Dockerfile andchangetheimagenamein sample/tile.yml toincludethemodifiedcodeinapp3.


https://github.com/cf-platform-eng/tile-generator

https://github.com/cf-platform-eng/tile-generator/tree/master/sample

https://github.com/cloudfoundry-community/redis-boshrelease/releases/tag/v13.1.2

-name:my-applicationtype:app#orapp-brokermanifest:#anyoptionsthatyouwouldnormallyspecifyinacfmanifest.yml,including</i>buildpack:#requiredcommand:domain:host:instances:memory:path:env:services:health_check:none#optionalconfigurable_persistence:true#optionalneeds_cf_credentials:true#optionalauto_services:#optional-name:p-mysqlplan:100MB-name:p-redisplan:shared-vmconsumes:#optionalredis:from:redis

Forappsthatarenormallypushedasmultiplefiles(node.jsforexample)zipuptheprojectfilesplusalldependenciesintoasingleZIPfile,thenedittile.yml topointtothezippedfile:

cd<yourprojectdir>zip-rresources/<yourprojectname>.zip<listoffileanddirstoincludeinthezip>

Ifyourappisaservicebroker,use app-broker asthetypeinsteadofjust app .Theappisthenautomaticallyregisteredasabrokeroninstall,anddeletedonuninstall.

health_check letsyouconfigurethevalueofthecfcli --health_check_type option.ExpectthisoptiontomoveintothemanifestassoonasCFsupportsitthere.Currently,theonlyvalidoptionsare none and port .

configurable_persistence:true resultsintheuserbeingabletoselectabackingservicefordatapersistence.Ifthereisaspecificbrokeryouwanttouse,youcanusethe auto-services featuredescribedbelow.Ifyouwanttobindtoanalreadyexistingserviceinstance,usethe services propertyofthe manifestinstead.

needs_cf_credentials causestheapptoreceivetwoadditionalenvironmentvariablesnamed CF_ADMIN_USER and CF_ADMIN_PASSWORD withtheadmincredentialsfortheElasticRuntimeintowhichtheyarebeingdeployed.ThisallowsappsandservicestointeractwiththeCloudController.

The auto_services featureisdescribedinmoredetailbelow.

consumes specifiestheBOSHlinks toconsumeandpresentsthehostsandpropertiesfromthelinksasenvironmentvariablesontheapp:

<LINK>_HOST :Theaddressofthefirstinstanceofthelink.

<LINK>_HOSTS :AJSONarrayoftheaddressesofallinstancesofthelink.

<LINK>_PROPERTIES :AJSONobjectofthepropertiesonthelink.

ServiceBrokers

MostmodernservicebrokersarepushedintotheElasticRuntimeasnormalCFapps.Forthesetypesofbrokers,usethePushedApplicationformatspecifiedabove,butsetthetypeto app-broker or docker-app-broker insteadofjust app or docker-app :


https://bosh.io/docs/links.html

-name:my-brokertype:app-brokermanifest:buildpack:#requiredcommand:domain:path:#...needs_cf_credentials:true#optionalauto_services:#optional-name:p-mysqlplan:100MB-name:p-redisplan:shared-vmenable_global_access_to_plans:true#optional

YourbrokerisautomaticallyregisteredwiththeCloudController.TheCloudControllerinvokesyourbroker’sendpoints,anditusesbasicauthenticationtosecurethoseAPIcalls.Thecredentialsitusesarepassedtoyourbrokerintwoenvironmentvariables:

SECURITY_USER_NAMESECURITY_USER_PASSWORD

Yourbrokerisexpectedtoacceptthosecredentials.Ifitdoesn’t,automaticbrokerregistrationfails.

Someservicebrokerssupportoperator-definedserviceplans,forinstancewhentheplansreflectcustomerlicensekeys.Toallowoperatorstoaddplansfromthetileconfiguration,addthefollowingsectionatthetoplevelofyourtile.yml:

service_plan_forms:-name:service_plans_1label:Service1Plansdescription:SpecifytheplansyouwantService1toofferproperties:-name:descriptiontype:stringdescription:"SomeDescription"configurable:true-name:license_key1type:stringconfigurable:truedescription:Thelicensekeyforthisplan-name:num_seats1type:integerconfigurable:truedescription:Thenumberofavailableseatsforthislicensedefault:1constraints:min:1max:500

NameandGUIDfieldsaresuppliedbydefaultforeachplan,butallotherfieldsareoptionalandcustomizable.Multipleformsaresupported.Theoperator-configuredplansarepassedtoyourservicebrokerinJSONformatinanenvironmentvariablenamedafteryourformbutinALLCAPS(inthiscase SERVICE_PLANS_1 ).

Foranexternalservicebroker,use:

-name:my-applicationtype:external-brokeruri:http://broker3.example.comusername:userpassword:#secretinternal_service_names:'service1,service2'

BOSHReleases

YoucanincludeBOSHreleases inyourtilewiththe bosh-release packagetype.Forexample,hereisapackagedefinitiontoincludeaRedisBOSHrelease:

Note:Unlessyouspecifythe enable_global_access_to_plans:true option,yourbroker’sservicesdonotappearintheuser’sMarketplaces.Operatorshavetousethe cfenable-service-access commandtoallowspecificusers,orgs,andspacestoaccessyourservices.


http://bosh.io/docs/release.html

-name:redistype:bosh-releasepath:resources/redis-13.1.2.tgzjobs:-name:redistemplates:-name:redisrelease:redismemory:512ephemeral_disk:4096persistent_disk:4096instances:2cpu:2static_ip:0dynamic_ip:1default_internet_connected:falsemax_in_flight:1properties:password:red!s-name:sanity-teststemplates:-name:sanity-testsrelease:redislifecycle:errandpost_deploy:truerun_post_deploy_errand_default:when-changedmemory:512ephemeral_disk:4096persistent_disk:0cpu:2dynamic_ip:1

ToincludeBOSHlinks inyourbosh-releasepackage’sdeploymentmanifest,youcanincludethe consumes and/or provides declarationsasstringsinthejob’s templates section,e.g.:

#...jobs:-name:job_nametemplates:-name:template_nameconsumes:|consumed_link:{from:foo}provides:|provided_link:{as:bar}

Buildpacks

-name:my-buildpacktype:buildpackpath:resources/buildpack.zipbuildpack_order:99#optional,99meansendofthelist

DockerImages

AppspackagesasDockerimagescanbedeployedinsideoroutsidetheElasticRuntime.TopushaDockerimageasaCFapp,usethePushedApplicationformatspecifiedabove,butusethe docker-app or docker-app-broker typeinsteadofjust app or app-broker .TheDockerimagetobeusedisthenspecifiedusingthe image property:

-name:app1type:docker-appimage:test/dockerimagemanifest:...

Ifthisappisalsoaservicebroker,use docker-app-broker insteadofjust docker-app .ThisoptionisappropriateforDocker-wrapped12-factorappsthatdelegatetheirpersistencetoboundservices.

DockerappsthatrequirepersistentstoragecannotbedeployedintotheElasticRuntime.ThesecanbedeployedtoseparateBOSH-managedVMsinsteadbyusingthe docker-bosh type:



-name:docker-bosh1type:docker-boshcpu:5memory:4096ephemeral_disk:4096persistent_disk:2048instances:1manifest:|containers:-name:redisimage:"redis"command:"--dir/var/lib/redis/--appendonlyyes"bind_ports:-"6379:6379"bind_volumes:-"/var/lib/redis"entrypoint:"redis-server"memory:"256m"env_vars:-"EXAMPLE_VAR=1"-name:mysqlimage:"google/mysql"bind_ports:-"3306:3306"bind_volumes:-"/mysql"-name:elasticsearchimage:"bosh/elasticsearch"links:-mysql:dbdepends_on:-mysqlbind_ports:-"9200:9200"

IfaDockerimagecannotbedownloadedbyBOSHdynamically,provideaready-madeDockerimageandpackageitaspartoftheBOSHrelease.Inthatcase,specifytheimageasalocalfile.

-name:docker-bosh2type:docker-boshfiles:-path:resources/cfplatformeng-docker-tile-example.tgzcpu:5memory:4096ephemeral_disk:4096persistent_disk:2048instances:1manifest:|containers:-name:test_docker_imageimage:"cfplatformeng/docker-tile-example"env_vars:-"EXAMPLE_VAR=1"#Seebelowoncustomforms/variablesandbindingittotheDockerenvvariable-"custom_variable_name=((.properties.customer_name.value))"

Toexposeacontainerviagorouter ,forexample,oneoftheDockercontainershostsanadminwebappinterface,use routes tochooseaportandprefix.TheexternalURLis [prefix]-[package.name].[system-domain] .Inthiscase,theURLis https://admin-docker-bosh3.sys.example.com ,where sys.example.com isthePCFsystemdomain. routes isalist,somultiplecontainerscanbeexposed.


https://docs.cloudfoundry.org/concepts/architecture/router.html

-name:docker-bosh3type:docker-boshdocker_images:-"cfplatformeng/database"-"cfplatformeng/admin_ui"routes:-prefix:adminport:8080cpu:5memory:4096ephemeral_disk:4096instances:1manifest:|containers:-name:databaseimage:"cfplatformeng/database"bind_ports:-"5432:5432"-name:admin_uiimage:"cfplatformeng/admin_ui"bind_ports:-"8080:8080"

CustomFormsandPropertiesYoucanpasscustompropertiestoallappsdeployedbyyourtilebyaddingthetothepropertiessectionof tile.yml :

properties:-name:authortype:stringlabel:Authorvalue:TileNinja

Ifyouwantthepropertiestobeconfigurablebythetileinstaller,placethemonacustomforminstead:

forms:-name:custom-form1label:TestTiledescription:CustomPropertiesforTestTileproperties:-name:customer_nametype:stringlabel:FullName-name:street_addresstype:stringlabel:StreetAddressdescription:Addresstouseforjunkmail-name:citytype:stringlabel:City-name:zip_codetype:stringlabel:ZIP+4default:'90310'-name:countrytype:dropdown_selectlabel:Countryoptions:-name:country_uslabel:USdefault:true-name:country_elsewherelabel:Elsewhere-name:account-info-1label:AccountInfodescription:ExampleAccountInformationFormproperties:-name:usernametype:stringlabel:Username-name:passwordtype:secretlabel:Password

Propertiesdefinedineithersectionarepassedtoallpushedappsasenvironmentvariables(thenameoftheenvironmentvariableisthesameasthe


propertynamebutinALL_CAPS).Theycanalsobereferencedinotherpartsoftheconfigurationfilebyusing ((.properties.<property-name>))

insteadofa

hardcodedvalue.

AllpropertiessupportedbyOpsManagermaybeused.ThesyntaxisthesameasusedbyOpsManager,exceptthatforsimplicitypropertyblueprintsforformfieldsdonotneedtobedeclaredseparately.Instead,thedeclarationisincludedintheformitself.Foracompletelistofsupportedpropertytypesandsyntax,seetheOpsManagerProductTemplateReference.

Propertiesoftype secret havetheirvaluehiddenontheformsandobfuscatedintheinstallationlogs(allbutthefirsttwocharactersarereplacedby***** ).Buttheirvalueispassedtoyourappsinplaintextasallothervaluetypes.

AutomaticProvisioningofServicesTileGeneratorautomatestheprovisioningofservices.Anyapp(includingservicebrokersandDocker-basedapps)thatarebeingpushedintotheElasticRuntimecanautomaticallybeboundtoservicesthroughthe auto_services feature:

-name:app1type:appauto_services:-name:p-mysqlplan:100mb-dev-name:p-redis

Youcanspecifyanynumberofservicenames,optionallyspecifyingaspecificplan.Duringdeployment,thegeneratedtilecreatesaninstanceofeachserviceifonedoesnotalreadyexistandthenbindthatinstancetoyourpackage.

Serviceinstancesprovisionedthiswaysurviveupdates,butaredeletedwhenthetileisuninstalled.

Ifyoudonotspecifyaplan,TileGeneratorusesthefirstplanlistedfortheserviceinthebrokercatalog.Itisagoodideatoalwaysspecifyaserviceplan.Ifyouchangetheplanbetweenversionsofyourtile,TileGeneratorattemptstoupdatetheplanwhilepreservingtheservice(thusnotcausingdatalossduringupgrade).Iftheservicedoesnotsupportplanchanges,thiscausestheupgradetofail.

configurable_persistence isreallyjustaspecialcaseof auto_services ,lettingtheuserchoosebetweensomestandardbrokers.

DeclaringProductDependenciesWhenyourproducthasdependenciesonothers,youcanhaveOpsManagerenforcethatdependencybydeclaringitinyour tile.yml fileasfollows:

requires_product_versions:-name:p-mysqlversion:'~>1.7'

IftherequiredproductisnotpresentinthePCFinstallation,OpsManagerdisplaysamessagesaying <your-tile>requires'p-mysql'version'~>1.7'asadependency

andrefusestoinstallyourtileuntilthatdependencyissatisfied.

Whenusingautomaticprovisioningofservicesasdescribedabove,itisoftenappropriatetoaddthoseproductsasadependency.TileGeneratorcannotdothisautomaticallyasitcan’talwaysdeterminewhichproductprovidestherequestedservice.

OrgsandSpacesBydefault,TileGeneratorcreatesasingleneworgandspaceforanypackagesthatinstallintotheElasticRuntime,usingthenameofthetileandappending -org and -space ,respectively.Thedefaultmemoryquotaforanewlycreatedorgis1024(1G).Youcanchangeanyofthesedefaultsbyspecifyingthefollowingpropertiesin tile.yml :

org:test-orgorg_quota:4096space:test-space

Note:Thenameisthenameoftheprovidedservice,notthebroker.Inmanycasesthesearenotthesame,andasinglebrokermayevenoffermultipleservices.Use cfservice-access toseetheservicesandplansofferedbyinstalledservicebrokers.


SecurityIfyourcfpackagesneedoutboundaccess(includingaccesstootherpackageswithinthesametile),youneedtoapplyanappropriatesecuritygroup.Thefollowingoptionremovesallconstraintsonoutboundtraffic:

apply_open_security_group:true

StemcellsTileGeneratordefaultstoarecentstemcellsupportedbyOpsManager.Inmostcasesthedefaultisfine,becausethestemcellisonlyusedtoexecuteCFcommandlinesand/ortheDockerdaemon.Butifyouhavespecificstemcellrequirements,youcanoverridethedefaultsinyour tile.yml filebyincludinga stemcell-criteria sectionandreplacingtheappopriatevalues:

stemcell_criteria:os:'ubuntu-trusty'version:'3146.5'#NOTE:Youmustquotetheversiontoforcethetypetobestring

CustomErrandsTileGeneratorsuppliesstandarderrandstodeployanddeleteCFtypepackages.Youcanreplaceoraugmentthoseerrandsbyspecifyingerrandshellcommandsinyourtile.ymlfile.Hereisanexampleofacustomdeployerrandtoinstallabuildpackonlyifanewerversionofthatsamebuildpackisnotalreadypresent:

packages:-name:my-buildpacktype:buildpackbuildpack_order:0#Gotoheadoflistpath:my_buildpack.zipdeploy:|cpmy_buildpack.zipmy_buildpack-v{{context.version}}.zipexisting=`cfbuildpacks|grep'^my_buildpack'ìf[-z"$existing"];thencfcreate-buildpackmy_buildpackmy_buildpack-v{{context.version}}.zip0elsesemver=ècho"$existing"|sed's/.*my_buildpack-v$.*$\.zip/\1/'ìfis_newer"{{context.version}}""$semver";thencfupdate-buildpackmy_buildpack-pmy_buildpack-v{{context.version}}.zipelseecho"Newerversion($semver)ofmy_buildpackisalreadypresent"ficfupdate-buildpackmy_buildpack-i0fidelete:|#Intentionalno-op,asothersmayhaveadependencyonthis

deploy and delete completelyreplacethestandarderrandcommandsforthepackageinwhichyouincludethem.Ifyouwanttokeepthestandardcommands,butaddadditionalcommandstoexecutebeforeorafterthestandarderrand,use pre_deploy , post_deploy , pre_delete ,and/or post_delete

instead.

VersioningTileGeneratorusessemverversioning .Bydefault, tilebuild generatesthenextpatchrelease.Majorandminorreleasescanbegeneratedbyexplicitlyspecifying tilebuild

majoror tilebuildminor .Ortooverridetheversionnumbercompletely,specifyavalidsemverversiononthebuildcommand,e.g.

tilebuild3.4.5 .

No-opcontentmigrationrulesaregeneratedforeverypriorreleasetothecurrentrelease,sothatOpsManagerallowstileupgradesfromanyversiontoanynewerversion.Thisdependsontheexistenceofthefile tile-history.yml .Inapinch,ifyouneedtobeabletoupgradefromarandomoldversiontoanewone,youcaneditthatfile,ordo:

tilebuild<old-version>tilebuild<new-version>


http://semver.org/

Thenewtilethensupportsupgradesfrom old-version .

UpgradesBydefault,TileGeneratorproducesallcodenecessarytodoablue/green,zero-downtimedeploymentofalltilecomponentswheninstallinganewerversionoveranolderone.Formosttileversionsthisisallthatisneeded.

OpsManagerhassupportforperformingupgradeactions,likedatabasemigrations,duringatileupgrade,butthiscapabilityisnotyetexposedthroughtilegenerator.

Example

$tilebuildname:tibco-bwceicon:icon.pnglabel:TIBCOBusinessWorksContainerEditiondescription:BusinessWorkseditionthatsupportsdeployingtoCloudFoundryversion:0.0.2

boshinit-release--dir=cfboshgenerate-packagecf_cliboshgenerate-packagebwce_buildpackboshgenerate-jobinstall_bwce_buildpackboshgenerate-jobremove_bwce_buildpackboshcreate-release--final--tarball=cf_incubator--version0.0.2

tilegeneratereleasetilegeneratemetadatatilegenerateerrandinstall_bwce_buildpacktilegenerateerrandremove_bwce_buildpacktilegeneratecontent-migrations

createdtiletibco-bwce-0.0.2.pivotal

Thistileincludesasinglelargebuildpackandtakeslessthan15secondstobuildincludingtheCFCLIdownloadandtheBOSHreleasegeneration.

SupportedCommands

tileinit[<tile-name>]tilebuild[patch|minor|major|<version>]

Creditssparameswaran suppliedmostoftheactualtemplatecontent,originallybuiltaspartofcf-platform-eng/bosh-generic-sb-release

frodenas contributedmostoftheDockercontentthroughcloudfoundry-community/docker-boshrelease

joshuamckenty suggestedthejinjatemplateapproachheemployedinopencontrol


https://github.com/sparameswaran

https://github.com/cf-platform-eng/bosh-generic-sb-release.git

https://github.com/frodenas

https://github.com/cloudfoundry-community/docker-boshrelease.git

https://github.com/joshuamckenty

https://github.com/opencontrol

pcfCommandLineUtilityPagelastupdated:

The pcf utilityprovidesacommandlineinterfacetoPivotalCloudFoundryforthepurposeofdeployingandtestingtiles.ItsprimaryreasonforexistenceistoenableOpsManageraccessfromCIpipelines,butdevelopersalsofinditconvenienttousethisCLIratherthantheOpsmanagerGUI.

The pcf utilityalsoallowsyoutotestyourtile’sBOSHerrandsdirectlyfromyourCLI,withoutgoingthroughOpsManagerandBOSH.Thisgreatlyreducesthetimeittakestodeploy/testeachiterationofyoursoftwarecomponents.

InstallationThe pcf utilitycomesbundledwiththeTileGeneratortool.Toinstallthe pcf utility,followtheTileGeneratorinstallationinstructions.

AuthenticationThe pcf utilitylooksforafilecalled metadata inthecurrentdirectory.ThisfileisexpectedtoprovidetheURLandcredentialstoconnecttoOpsManager,inthefollowingformat:

---opsmgr:url:https://opsmgr.example.comusername:adminpassword:<redacted>

ThereasonforthisfilenamingisbecausethisishowConcoursepassescredentialsofa“claimed”PCFpoolresourcetotheCIpipelinescripts.Forinteractiveuse,thismeansthatyouwillhavetocreatea metadata fileinthedirectorywhereyourunthe pcf command.

CommandsThe pcf utilityimplementsmanydifferentcommands.Toseeavailablecommands:

$pcf--helpUsage:pcf[OPTIONS]COMMAND[ARGS]...

Options:--helpShowthismessageandexit.

Commands:apply-changescf-infochangesconfiguredelete-unused-productsimportinstallis-availableis-installedlogsproductssettingstargettest-erranduninstall

CheckingOpsManagerSettings

Pivotalrecommendsthatyoudonotcreatethisfileinsideyourgitorotherversioncontrolsystemrepository,asyoudonotwanttoaccidentallycommitthesecredentialstoversioncontrol.


ToseewhichproductsarecurrentlyavailableandinstalledinOpsManager:

$pcfproducts-p-bosh1.7.0.0(installed)-cf1.7.0-build.258(installed)-test-tile0.3.95

Totestifaspecificproductisavailableorinstalledfromwithinascript:

$pcfis-availabletest-tile&&echo"Producttest-tileisavailable"$pcfis-installedtest-tile&&echo"Producttest-tileisinstalled"

Youcanretrievethesettingsforaspecificproduct(thiswillgiveyoualotofjson):

$pcfsettingstest-tile{"network_reference":"669e213111ab5aa1008a","guid":"test-tile-be3e50cf26c530acca6e","jobs":[{"instance":{"identifier":"instances"},"identifier":"compilation","guid":"compilation-066a85d82fbcd936f9d7","installation_name":"compilation","vm_credentials":{"password":<redacted>,"salt":<redacted>,"identity":"vcap"}},{"guid":"deploy-all-b83a7cb7be00ebfd26d6","vm_credentials":{...

DeployingTilesAfteryoursoftwareworksandcorrectlydeploysusing test-errand ,youcangothroughtherealOpsManagerdeploymentprocessfromtheCLI,asyouwouldnormallydothroughtheOpsManagerGUI.

Importyour.pivotalfileintoOpsManager:

$pcfimportsample/product/test-tile-0.0.2.pivotal

Installtheuploadedversionofyourproduct:

$pcfinstalltest-tile0.0.2

WhereyouwouldnormallyconfigurethetilesettingsintheGUI,the configure commandletsyoupassinanyuser-specifiedpropertiesasa.ymlfile.ThiscommandalsosetsthestemcellforthetiletothesameoneusedbyyourElasticRuntime,toavoidtheneedtouploadatile-specificstemcell.

$pcfconfiguretest-tilesample/missing-properties.yml-Usingstemcellbosh-vsphere-esxi-ubuntu-trusty-go_agentversion3215

Thepropertyfilelookslikethis:


---customer_name:Jimmy'sJohnnysstreet_address:CartawayAlleycity:NewJerseycountry:USusername:SpongeBobpassword:{'secret':Square'Pants}app2:persistence_store_type:none#InPCF1.8+,BOSH-job-specificconfigurationissupported:jobs:a_job:#Jobresourceconfiguration:resource_config:persistent_disk:size_mb:"10240"#Job-specificpropertyconfiguration:job_property:property_value

Youmustdefineany secret typepropertyvalueasahash,incurlybrackets.Specifyingasimplestringvalueforafieldofthistyperesultsina500SystemError

beingreturnedfrom pcfconfigure .The secret typepropertyvaluescancontainspecialcharacters.

Toseewhatchangesarereadytobeapplied:

$pcfchangesinstall:test-tile-207b165fcb7dc8b2597bdelete:

Toapplythesechanges:

$pcfapply-changes=====2016-04-2118:45:05UTCRunning"bosh-initdeploy/var/tempest/workspaces/default/deployments/bosh.yml"Deploymentmanifest:'/var/tempest/workspaces/default/deployments/bosh.yml'Deploymentstate:'/var/tempest/workspaces/default/deployments/bosh-state.json'

StartedvalidatingValidatingrelease'bosh'...Finished(00:00:08)Validatingrelease'bosh-vsphere-cpi'...Finished(00:00:00)Validatingrelease'uaa'...Finished(00:00:06)Validatingcpirelease...Finished(00:00:00)Validatingdeploymentmanifest...Finished(00:00:00)

pcfapply-changes automaticallytailsthelogsfortheinstallationprocessitstarted.Ifthisgetsabortedforanyreason,youcanalwaystailthelogsofthemostrecentinstallation:

$pcflogs

RemovingTilesTouninstallatile:

$pcfuninstalltest-tile

Ifyouaccumulatealotofuninstalledtilesoroldversions,youcancleanupOpsManager’savailableproducts(anddiskspace):

$pcfdelete-unused-products

AccessingElasticRuntimeToseedetailsabouttheElasticRuntimeofyourPCFenvironment:


$pcfcf-info-admin_password:<redacted>-admin_username:admin-apps_domain:cfapps-04.example.com-system_domain:run-04.example.com-system_services_password:<redacted>-system_services_username:system_services

Totargetyour cf commandlineatthisPCFenvironment:

$pcftargetSettingapiendpointtoapi.example.com...OK

APIendpoint:https://api.example.com(APIversion:2.52.0)User:adminOrg:my-orgSpace:my-spaceAPIendpoint:https://api.example.comAuthenticating...OK

...


ConcoursePagelastupdated:

ThistopicexplainshowtouseConcourse continuousintegration(CI)tohelpdevelopandintegrateappsforPivotalCloudFoundry(PCF).

OverviewPCFisafastmovingplatformasweareconstantlyextendingandenhancingit.WhenyouintegrateyoursoftwarewithPCF,youshouldmakesurethatyourintegrationcontinuestoworkwitheverynewreleaseoftheplatform.OnewaytoensurethatistosetupaCIpipelineforyourtileagainstaPCFdeploymentthatisconstantlyupdatedwiththelatestAlphareleaseoftheplatform.

OurtoolofchoiceforsettingupCIisconcourse .Whileyouareofcoursefreetousewhateversystemyouarefamiliarwith,ourtoolsanddocumentationarebuilttomakeconcourseCIaseasyaspossible.

SetUpaConcourseServerYouwillneedaconcourseservertohostyourpipeline.Ifyoupartnerwithus,wehaveserversthatcanhostyourpipeline,andS3storagethatcanbeusedtotransferartifactstoandfromyourservers.Ifyouchoosetosetupyourown,instructionscanbefoundhere:

Settingupconcourse

CreateaConcoursePipelineforYourTileAtypicalCIpipelineforatileconsistsofthefollowingjobs:

Buildthetile

DeployittoPCF

Runasetofdeploymentteststoverifythatitdeployedandworkscorrectly

RemoveitfromPCF

Youdescribethispipelineina pipeline.yml filethatisthenuploadedtotheconcourseserver.TileGeneratorcontainsasamplepipelinethatyoucancloneforyourowntile.Weareworkingonautomatingtheprocessofgeneratingapipelinetemplateforyou.

SetUpPCFforYourCIPipelinePivotalpartnerswhohaveushosttheirpipelinehaveaccesstoapoolofPCFinstancesthataremanagedbyusandareregularlyupdatedwiththelatest(pre-)releaseversionsofPCF.Ifyousetupyourownconcourseserver,youwillhavetotargetyourpipelineataPCFinstanceyouhavesetup.

Concoursehasaresourcetypetomanageapoolofresourcesthataresharedbetweenpipelines,whichiswhatweusetoserializePCFaccessbetweenthepartnerpipelinesthatrunonourconcourseserver.


http://concourse.ci

http://concourse.ci/

https://concourse-ci.org/setup-and-operations.html

PivotalCloudFoundryServicesSDKPagelastupdated:

DynamicProvisioning,Metrics,andBackupsThePivotalCloudFoundry(PCF)ServicesSDKisdesignedtohelpyoubuildenterprise-readyserviceofferingsfortheMarketplace.TheSDKincludesthefollowingcomponents:

TheOnDemandServiceBroker enablesdynamicprovisioningofyourserviceusingBOSH2.0.

ServiceMetricsforPCF integratesyourserviceintothePCFLoggingandMetricssystem,empoweringplatformoperatorstogainimmediateinsightintosystemhealthbasedonliveservicemetrics.

ServiceBackupsforPCF runsregularbackupsforyourservice,triggeringanduploadingbackupartifactstoarangeofdestinations,includingS3andAzure.

ActivePivotalpartnersandcustomerscanusethePCFServicesSDKbyagreeingtothePivotalSDKEULAwhendownloadingtheproductsonhttps://network.pivotal.io/ .


https://docs.pivotal.io/on-demand-service-broker

https://docs.pivotal.io/service-metrics

https://docs.pivotal.io/service-backup/


PublishandUpdatePagelastupdated:

ThistopicprovidesresourcestohelpyoupublishandupdateyourservicetileforPivotalCloudFoundry(PCF).

PublishYourTileThePivotalPartnerSoftwareProductReleaseCycleexplainshowPivotalworkswithpartnerstoreleasePCFproducts,fromtheprivatealphaandclosedbetaphases,togeneralavailabilityandpublicationonPivotalNetwork .

Afteryou’vepackagedyourproduct’sBOSHreleases,stemcell,metadata,andothertilecomponentsintoasinglezippeddownloadfile,postittoPivotalNetworkinoneoftwoways:

UsethePivotalNetworkAPIcommand POST /api/v2/products/:product_slug/product_files .

UsethePivotalNetworkproductuploadform.

UpdateYourTileMosttileupdatesoriginatewiththetiledeveloper,butnewreleasesofPCFcanalsonecessitatetilechangestomaintaincompatibilitywiththecurrentversionoftheplatform.

TileGeneratorautomatestileversioningandupgrades.Formoreinformation,seeVersioningintheTileGeneratordocumentation.

TileUpgradesexplainshowtowriteandincludeaJavaScriptfilethatautomatestileupgradesbymigratingpropertynamesandvaluesfromonetileversiontoanother.

WhenchangestoPCFrequiretilechanges,Pivotaldistributesinstructionstoallofitspartners:

PivotalCloudFoundryv2.2PartnersReleaseNotice






https://network.pivotal.io/docs/api#public/docs/api/v2/product_files.md

http://docs.pivotal.io/tiledev/2-2/release-notes.html




TileDocumentationPagelastupdated:

ThistopicexplainshowtodocumentyourservicetileforPivotalCloudFoundry(PCF).

OverviewWhenaPCFservicetilelaunchesonPivotalNetwork ,Pivotalpublishescorrespondingdocumentationathttps://docs.pivotal.io underPartnerServicesforPivotalCloudFoundry.

ThisdocumentationisformattedinMarkdown ,storedinaGitHubrepositorythatPivotalcreates,andispublishedwiththebookbinder platform.

PartnerDocumentationTemplateThePCFPartnerDocumentationTemplate isaGitHubrepositorythatyoucanclonetocreatedocumentationforyourservicetilethatfollowsPivotal’sformatandworkswithitsdocumentationpublishingplatform,bookbinder .

Documentationcontentresidesinthe /docs-content folderoftherepository,asskeletonpageswithembeddedpromptsforcontentthatyoushouldfillin,approximatelyfollowingthecontentdescriptionsbelow.

SeetherepositoryREADME.md forhowtousethetemplatewithbookbindertodevelopyourdocumentation.

DocumentationContentWhilethespecificsofyourdocumentationwillvarydependingontheproduct,wehaveprovidedabasicblueprintbelow.Atminimum,documentationshouldinclude#1(Overview)and#2(Installing/Configuring).

Foragoodexampleofapartnerservicedocument,seetheJFrogArtifactorydocumentation .

Ifyouhavequestionsorwanttocollaborateondraftingthedocumentation,feelfreetohoponourSlackchannel#pcf-docs.We’realwayshappytohelp!

Index/LandingPageGeneraloverviewofPartnerProduct.Whatdoesitdo?Whatareitsfeatures?

KeyFeatures

Featureone

Featuretwo

Featurethree

PartnerServiceBroker

AServiceBrokerallowsCloudFoundryapplicationstobindtoservicesandconsumetheserviceseasilyfromAppManagerUIorcommandline.ThePartnerServiceBrokerwillenableyoutouseoneormorePartneraccountsandisdeployedasaJavaApplicationonCloudFoundry.TheBrokerexposesthePartnerserviceontheCloudFoundryMarketplaceandallowsuserstodirectlycreateaserviceinstanceandbindittotheirapplicationseitherfromthePivotalAppsManagerConsoleorfromthecommandline.

ThePivotalCloudFoundry(PCF)TileforPartnerinstallsthePartnerServiceBrokerasanapplicationandregistersitasaServiceBrokeronCloudFoundryandexposesitsserviceplansontheMarketplace.ThismakestheinstallationandsubsequentuseofPartneronyourCloudFoundryapplicationssimpleandeasy.

Ifatriallicenseavailable,customersinterestedinusingPartnercanobtaina60dayfreetriallicensefromeditlinkhere.


https://network.pivotal.io

https://docs.pivotal.io

https://daringfireball.net/projects/markdown/

https://github.com/pivotal-cf/bookbinder

https://github.com/pivotal-cf/docs-partners-template

https://github.com/pivotal-cf/bookbinder

https://github.com/pivotal-cf/docs-partners-template/blob/master/README.md

https://docs.pivotal.io/jfrog/index.html

ProductSnapshot

CurrentPartnerTileforPivotalCloudFoundryDetails:

Version:

ReleaseDate:

Softwarecomponentsversions:Partnerproductversion

CompatibleOpsManagerVersion(s):1.5.x,1.6.x

CompatibleElasticRuntimeVersion(s):1.4.x,1.5.x,1.6.x

Requirements

(orPrerequisites,PackagingDependenciesforOfflineBuildpacks,etc.)

Provideanygeneralorspecificrequirementshere.Ageneralrequirementmightbesomethinglike,“AnAppDynamicsaccount.”Aspecificrequirementmightbesomethinglike,“PackagingDependenciesforOfflineBuildpacks.”

Limitations

Anyknownlimitations.

Pleaseprovideanybugs,featurerequests,orquestionstothePivotalCloudFoundryFeedbacklist.

Installing/ConfiguringtheTileThistopicprovidesinstructionsforhowtoinstallandconfigurethetile.TypicallythisincludesproceduresforhowtodownloadthetilefromPivotalNetwork,installitonOpsManager,configurethetile,anddoanyrequiredthird-partyconfiguration.Screenshotsshouldbeprovidedwherenecessary.Consultthefollowingformat:

InstallUsingthePivotalOpsManagerDownloadtheproductfilefromPivotalNetwork.

UploadtheproductfiletoyourOpsManagerinstallation.

ClickAddnexttotheuploadedproductdescriptionintheOpsManagerAvailableProductsviewtoaddthisproducttoyourstagingarea.

Clickthenewlyaddedtiletoreviewanyconfigurableoptions.

ClickApplyChangestoinstalltheservice.

UpgradingtotheLatestVersion

Ifthereareanyspecificinstructionsforupgradingthetile,youcanincludethosehere.Iftheproceduresarecomplicated,createanewUpgradingtopic.

ConfiguringthePartnerTile

(addsnapshotsforeachstepwhenpossibleoradddetailsasrequired)

LoginintoPivotalOpsManager

ClickImportaProductandimportthePartnerTile

SelectthePartneroption

ClickAddonthePartnerTile

SelectthePartnerTile

ConfigurethePartnerTile

Applyyourchanges.

OncompletionofPartnerTileinstall,checkServicesMarketplaceinAppsManager


ViewPartnerServicePlans

BindthePartnerServicetoanApplication

Checktheserviceordashboardforthepartnerformoredata…

OtherConfigurations/Third-PartyConfigurations

ProvideinformationforspecificconfigurationslikeconfiguringforHTTPproxy,ordoinganynecessaryconfigurationsonathird-partyserviceportal.

UsingtheTileThistopicprovidesinstructionsforhowtousethetile.Typicallythisincludesproceduresforhowtoperformthedifferentfunctionsofferedbytheservice.Screenshotsshouldbeprovidedwherenecessary.YoucanalsoincludeinformationaboutArchitecturehereifnecessary.

TroubleshootingThistopicprovidestroubleshootinginformationforknownerrors,followingtheSymptom/Explanationformatusedhere:https://docs.pivotal.io/p-identity/okta/troubleshooting.html

ReleaseNotesIncludethereleasenotesasthefinaltopic,followingtheformatinthedocs-partners-template .


https://docs.pivotal.io/p-identity/okta/troubleshooting.html

https://github.com/pivotal-cf/docs-partners-template/blob/master/docs-content/release-notes.html.md.erb

PartnerSoftwareProductReleaseCyclePagelastupdated:

ThistopicdescribesthefourphasesofproductreleasetoPivotalCloudFoundry(PCF).

Phase1:AlphaAproductbeginsdevelopmentintheAlphaphase.Theproductundergoesconstantchurnandrefactoring,andmaynotbefeature-complete.

CustomersdonothaveexposuretoaproductduringAlpha,andtherearenoqualityrequirementsinthisphase.Instead,developersusethisstageforinternaltesting.

Phase2:ClosedBetaDuringClosedBeta,alimitedpoolofusersgainsaccessandprovidesfeedbacktoaproduct.Thisfeedbackdrivesfurtherdevelopment.AstatusofClosed(Private)Betainformsusersthattheproductmaybeunstableandshouldnotbeusedinproduction.

AproductshouldremaininClosedBetawhile:

Changesmaybreakproductfunctionorcauselossofdata.

Usersmayexperiencemajorbugs.

Usersmayneedtodeleteandreinstalltilesratherthanupgradingthem.

DevelopersmakeproductsinClosedBetaavailabletospecificgroupsorindividualcustomersonPivotalNetwork .

RequirementsToenterClosedBeta,aproductmustmeetthefollowingrequirements:

TheproductmustrunproperlyonatleastoneIaaS,sothatcustomerscaninstallandtryitout.SupportedinfrastructuresareAWS,vSphereandOpenStack.

Customersmustbeabletoinstalltheproducterror-freethroughatileinPivotalOpsManager,anddeletetheproducttherewithoutanytracesremaining.

Theproducttilemusttargetthelatestreleasedstemcellversion,aslistedonPivotalNetwork .

Thereleasenotesmustmakeclearthefollowingconstraints:

Potentialdatalossandlackofsupportmakethebetaversionoftheproductunsuitableforuseinproduction.Userswillneedtodeletetheoldtileandinstallanewoneinordertomovetothenextversionoftheproduct.Noupgradepathexists.

Theproductmustfulfillitspromisedfeatureset,andperformasdesired.

PivotalalsorecommendsthatanyClosedBetaproductincludeaneasywayforuserstoprovidefeedbacktotheproductdeveloper.

StepstoReleaseThefollowingstepscreateanewClosedBetareleaseforyourproduct:

1. LogintoPivotalNetwork .

2. Createanewreleaseforyourproductandpopulatealloftherequiredfields.

3. CheckthatthereleaseversionstatesBETA.

4. Clearlystateinthereleasedescriptionthattheproductcannotbeupgraded,andthatusersmaysufferdataloss.

5. EmailyourPivotalcontacttorequestproductvalidationandClosedBetarelease.Pleaseprovidebasicinstructionsonhowtovalidatethenewfeatureset.Pivotalwillverifythatthereleasemeetsallrequirements,thenmakeitaccessibletoinvitedcustomers.



https://network.pivotal.io/products/stemcells


Phase3:PublicBetaYourproductwillbemadeavailabletothegeneralpublicinPublicBeta.Thewiderpoolofusersincreasespublicawarenessandfeedbackandfacilitatesmarketingandadvertising.Asdevelopmentcontinues,youmaypublishaseriesofproductversionsinPublic(Open)Beta.

YourproductisagoodcandidateforthePublicBetastageif:

Youhavehighconfidencethatfurtherdevelopmentwillnotbreaktheproductorincurdatalossforusers.

Thetilecanbeupgraded.

Youstillwantuserfeedbacktodiscoverminorbugsandevaluateexistingfeatures.

Theproductdoesnotcontainthefullsetoffeaturesintendedforthefinalrelease.

Youfeelcomfortablesupportingthistileforcustomers.

ProductsinPublicBetaareavailableonPivotalNetwork toanyuserwithafreePivotalNetworkaccount.

RequirementsProductsinPublicBetamustmeetthefollowingrequirements:

TheproductmeetsallrequirementsforClosedBeta.

Thetilecanbeupgradedtosubsequentversionswithoutrequiringthecustomertouninstallthepreviousversion.

Theproductsupportsupgradepathsfromanyminorversionorpatchtothenextminorversionandanypatches.

Tileversionupgradesresultinnodataorconfigurationloss,andmaintainservicefunctionalityandavailability.

Whereappropriate,PCFintegrationsworkproperly,including:

RegisteredroutesUAAServicebrokers

YoucanrespondtodiscoveryofasecurityflawontheCommonVulnerabilitiesandExposures(CVE)list withinareasonabletimeframe.Securityflawsincludevulnerabilitiesinyourstemcellorwithinoneofthecomponentsofyourtile.

StepstoRelease1. LogintoPivotalNetwork .


3. CheckthatthereleaseversionstatesBETA.

4. EmailyourPivotalcontacttorequestproductvalidationandPublicBetarelease.Pleaseprovidebasicinstructionsonhowtovalidatethenewfeatureset.Pivotalwillalsovalidatetheupgradescenarioanddatapersistence.Afterverifyingthatthereleasemeetsallrequirements,Pivotalwillmakeitvisibletocustomers.

Phase4:GeneralAvailabilityAproductqualifiesforGeneralAvailabilitywhen:

Itisproduction-ready.

Youcanchargemoneyforthisproductandprovidesupportguaranteestoyourcustomers.

Theproduct’sfullsetoffeaturesmeetsthestandardsofqualitythatyouwishtouphold.

Requirements

Note:PivotalattemptstorespondtoallcriticalCVEswithin48hours.



https://cve.mitre.org/cve/index.html


ProductsmustmeetthefollowingrequirementsforGeneralAvailability:

TheproductmeetsallrequirementsforPublicBeta.

Youconsidertheproductproduction-ready,andyouhaveadequateunitandfunctionalteststoensurehighquality.

Youcanprovidecustomersupport.

Yourbusinessteamcan“Gotomarket.”

Theproductcanscalevertically,byincreasingtheamountofRAMorCPU.Verticalscalingimprovesperformanceanddoesnotresultindataloss.

Ifappropriate,theproductcanscalehorizontallyforhighavailability.

Scaled-outnodes(applicationVMs)functioncorrectly.Removinganodedoesnotresultindowntime.

Ifappropriate,theproductsupportszerodowntimedeployment.

Productinstallationdoesnotrequireaninternetconnection,afterinitialproductdownload.

StepstoRelease1. LogintoPivotalNetwork .


3. EmailyourPivotalcontacttorequestproductvalidationandGeneralAvailabilityrelease.Pleaseprovidebasicinstructionsonhowtovalidatethenewfeatureset.Pivotalwillalsovalidatetheupgradescenarioanddatapersistence.



UpgradingTilesPagelastupdated:

Thistopicdiscussesproducttilemigrations,whichreferstochangingthenameandvaluesofpropertieswhenacustomerupgradestileversions.TileauthorssupplyaJavaScriptfiletotriggerchainingmigrations.Chainingmigrationsallowsformultiplemigrationstorunsequentially.

UpdateValuesorPropertyNamesUsingJavaScriptToupdateaproducttile,tileauthorsmustcompletethefollowingsteps:

1. Inasingle .js file,writeJavaScriptfunctionswhichreturnahashofthetile’sproperties.

2. Namethefileintheformat TIMESTAMP_NAME.js .TIMESTAMPmustbeintheform“YYYYMMDDHHMM”toindicatewhentheauthorcreatedthemigration.NAMEisahuman-readablenameforthemigration,forexample, 201606150900_example-product.js .

3. Copythe TIMESTAMP_NAME.js filetothePRODUCT/migrations/v1directory.

ExampleJavaScriptMigrationFileThefunctionsbelowdisplayanexamplemigrationfile:

exports.migrate=function(input){//Appendtexttoastring

input.properties['.web_server.example_string']['value']+='!';

//Deleteproperty'legacy_property'that'sremovedinnewtileversiondeleteinput.properties['.properties.legacy_property'];

//Renameproperty'example_port'to'example_port_renamed',//retainingthepreviousvalue.input.properties['.properties.example_port_renamed']=input.properties['.properties.example_port'];deleteinput.properties['.properties.example_port'];

//Appendtexttoastringlistinput.properties['.properties.example_string_list']['value'].push('new-string-append-by-migration');

returninput;};

ThepropertiesobjectpassedtoyouranonymousJavaScriptmigrationfunctionsarecomposedofpropertiesatthejob-levelandproduct-level.ReviewthepropertynamesintheexamplemetadatafileinTutorialTileV3 formoreinformationaboutjob-levelandproduct-levelproperties.Thetileauthormustupdatemigrationstomatchthecorrespondingproductmetadatafile.

Eachproperty’skeyinthepropertiesobjectisitspropertyreferencefromthemetadatafile.Propertyreferencesuseoneofthefollowingforms:

.properties.{property_name} forproduct-levelproperties

.{job_name}.{property_name} forjob-levelproperties

.properties.{property_name}.options.{option_name} or .{job_name}.{property_name}.options.{option_name} forselectoroptionproperties

Theobjectaccessedthroughthepropertyreferencecontainsavaluekeywhosestructureisspecifictothetypeoftheproperty.Objectsmaybeastring,anarray,orahash.Reviewthereferencebelowforthestructureofeachtypeofproperty.

Note:InordertouseJSmigrations,ensureyouareusingOpsManager1.7orlater.

Note:Changingthevalueof single_az_only forjobslaunchedbyyourtilecancausedatalossforcustomerswhoupgradetoOpsManagerv1.7versionsolderthanv1.7.20,orv1.8versionsolderthanv1.8.12.ContactPivotalSupport forhelpavoidingthis.


http://support.pivotal.io/

https://github.com/pivotal-cf-experimental/ops-manager-example/releases/tag/tutorial-v3

JavaScriptMigrationsAPIInsideaJavaScriptmigrationfunction,thesystemprovidesthefollowingfunctionsforyourcode:

console.log(string)Arguments:stringReturnvalue:noneDescription:PrintsthestringtotheRailslogExample:console.log(“HelloWorld”);

getCurrentProductVersion()Arguments:noneReturnvalue:string(example:1.7.1.0)Description:ReturnstheversionoftheproductthatiscurrentlyinstalledExample:console.log(getCurrentProductVersion());

generateGuid()Arguments:noneReturnvalue:string(example:115f9ced-3167-4c7c-959b-d52c07f32cbf)Description:Returnsagloballyuniqueidentifier(GUID)thatcanbeusedastheuniqueidentifierforeachelementofaCollectionsproperty.WhenupdatingaCollectionpropertyblueprint,youasthemigrationauthorareresponsibleforupdatingtheGUIDofeachnewcollectionelementthatyoucreate.Notes:Thisfunctioncanbecalledamaximumof100timesper`.js`file.Ifyouneedmorethan100GUIDs,breakyourmigrationintotwo`.js`files.Example:console.log(“Here'saGUID:”+generateGuid())

abortMigration(string)Arguments:stringcontainingerrormessageReturnvalue:none(neverreturns)Description:Causesthemigrationtofailimmediately.Rollsbackallmigrationsinthecurrentchain,i.e,nochangeswillbecommitted.Example:if(something>5){abortMigration("Can'tupgradetilewhenthevalueofsomethingismorethan5")}

PropertyType ValueStructure Example

single-valueproperties

Singlevalue,buttype-specific

properties['.properties.my-prop'].value = 'my-string'; properties['.properties.other-prop'].value = true

dropdown Arrayofoptions properties['.properties.my-prop'].value = ['option1', 'option2']

rsa_cert_credentials

Object properties['.properties.my-prop'].value = {'private_key_pem' => 'a-private-key', 'cert_pem'=> 'a-cert-pem'}

rsa_pkey_credentials

Object properties['.properties.my-prop'].value = {'private_key_pem' => 'a-private-key'}

salted_credentials Object

properties['.properties.my-prop'].value = {'identity' => 'an-identity', 'salt' => 'mortons','password' => 'books'}

simple_credentials

Object properties['.properties.my-prop'].value = {'identity' => 'an-identity', 'password' =>'secret'}

collections Arrayofobjects properties['.properties.my-prop'].value = [{name: {value: 'foo'}, record_id: {value: 1}},{name: {value: 'bar'}, record_id: {value: 2}}]

selectors

SelectedvalueString properties['.properties.my-prop'].value = 'selected option label'

selectors

{selectoroptionname.propertyname}

Valueobjectspecifictopropertytype

properties['.properties.selector.option1.prop1'].value = 'foo'properties['.properties.selector.option1.prop2'].value = 2properties['.properties.selector.option2.prop3'].value = ['bar', 'baz']

Singlevaluepropertiesrefertopropertieswhosetypeareanyofthefollowing:boolean,ca_certificate,domain,dropdown_select,email,http_url,integer,ip_address,ip_ranges,ldap_url,multi_select_options,network_address,network_address_list,port,smtp_authentication,string,string_list,text,uuid.

RefertotheexamplepropertiesbelowwhenwritingyourowntilemigrationJSfile:


{ properties: { '.properties.example_boolean': { value: false } , '.properties.example_ca_certificate': { value: 'simple-typed-value'}, '.properties.example_domain': { value: 'simple-typed-value'} , '.properties.example_dropdown_select': { value: 'simple-typed-value'}, '.properties.example_email': { value: 'simple-typed-value'}, '.properties.example_http_url': { value: 'simple-typed-value'}, '.properties.example_integer': { value: 111}, '.properties.example_ip_address': { value: 'simple-typed-value'}, '.properties.example_ip_ranges': { value: 'simple-typed-value'}, '.properties.example_ldap_url': { value: 'simple-typed-value'}, '.properties.example_multi_select_options': { value: ['simple-typed-value']}, '.properties.example_network_address': { value: 'simple-typed-value'}, '.properties.example_network_address_list': { value: 'simple-typed-value'}, '.properties.example_port': { value: 22}, '.properties.example_smtp_authentication': { value: 'simple-typed-value'}, '.properties.example_string': { value: 'simple-typed-value'}, '.properties.example_string_list': { value: 'simple-typed-value'}, '.properties.example_text': { value: 'simple-typed-value'}, '.properties.example_uuid': { value: 'simple-typed-value'}, '.properties.example_rsa_cert_credentials': { value: {'private_key_pem': 'a-private-key', 'cert_pem':'a-cert-pem'}, }, '.properties.example_rsa_pkey_credentials': { value: {'private_key_pem':'a-private-key'}, }, '.properties.example_salted_credentials': { value: {'identity':'an-identity', 'salt':'mortons', 'password':'books'}, }, '.properties.example_simple_credentials': { value: {'identity':'an-identity', 'password':'secret'}, }, '.properties.example_collection': [ {name: {value: 'foo'}, record_id: {value: 1}}, {name: {value: 'bar'}, record_id: {value: 2}} ], '.properties.example_selector': {value: 'option1'}, '.properties.selector.option1.prop1': {value: 'foo'}, '.properties.selector.option1.prop2': {value: 2}, '.properties.selector.option2.prop3': {value: 'bar,baz'} }}

ExamplesDemonstratingChainingMigrationsMigrationchainingallowsformultiplemigrationstorunsequentiallywhenanupgradeisperformedthatskipsanintermediateversion.Forexample,supposeyouhavethreeversionsofyourproduct:1.6.0,1.7.0,and1.7.1.The1.6.0productcontains1.6metadata,soitdoesnotcontainanyJavaScriptmigrations.

Note:IfyourproductusesOpsManager1.6orearliermetadata,youneedtowriteatransmogrifiercontentmigrationforcustomersusingyourproducton1.6,andaJavaScriptmigrationforthoseonOpsManager1.7orlater.ReviewthetransmogrifierexampleintheTileTutorialV1 .


https://github.com/pivotal-cf-experimental/ops-manager-example/releases/tag/tutorial-v1

Thefollowingcustomerupgradescenariosillustratechainingmigrationsinmoredetail,andusetheexampleproductversionsdescribedabove.

ScenarioA:Upgradingfrom1.6.0->1.7.0->1.7.1Inthisscenario,thecustomerstartswiththe1.6.0productinstalled.AfterupgradingtoOpsManager1.7orhigher,theydecidetoupgradetheproductto1.7.0.Thiscausesthe migration201606010000_a.js torun.Severalweekslater,thecustomerdecidestoupgradefrom1.7.0to1.7.1.Nowthe201607010000_b.js migrationruns.Eventhoughthe1.7.1productincludesbothmigrations,OpsManagerdoesnotre-run 201606010000_a.js ,becauseit

maintainsarecordofmigrations.

ScenarioB:UpgradingDirectlyfrom1.6.0->1.7.1Inthisscenario,thecustomeralsostartswith1.6.0installed,buttheydecidetoupgradedirectlyto1.7.1,skippingthe1.7.0version.Bothmigrationsruninlexicographicalorder.


ScenarioC:Installing1.7.0,ThenUpgradingto1.7.1Inthisscenario,thecustomerstartswithnothinginstalled.Theyperformacleaninstallofversion1.7.0oftheproduct.Oninstallof1.7.0,nomigrationsrunbecausemigrationsonlyrunonupgrades.Later,thecustomerdecidestoupgradeto1.7.1oftheproduct.Because1.7.1containsbothmigrations,andbecausenomigrationshaverunonthissystem,onlythesecondmigration 201607010000_b.js runs.Thesystemrecordedthefactthat1.7.0includes201606010000_a.js ,sothatmigrationdoesnotrun.

ScenarioD:Installing1.7.1Inthisscenario,thecustomerperformsacleaninstallof1.7.1,withnopreviousversionsoftheproductinstalled.Sincemigrationsareonlytriggeredbyupgradeevents,nomigrationsrun.

Note:Donotomitamigrationfromalaterversionofyourtile.Thisbreaksthe“chaining”natureofmigrations.Usingtheexampleabove,ifyou


releasea1.7.1tilewithoutthe 201606010000_a.js migration,thesystemcouldnotdetectthat 201606010000_b.js isthesamemigrationthatwaspresentinthecleaninstallinScenarioC.


ReferencesPagelastupdated:

ThistopiccollectsAPI,configurationproperty,andotherreferencesforbuildingPivotalCloudFoundry(PCF)tiles.

TroubleshootingSoonerorlateryouwillrunintoproblemsthatrequirediggingalittlebitdeeper.Herearesomegreatresourcesonhowtobesttroubleshootmorecomplexissues:

TroubleshootingPCF

TroubleshootingApplications

AdvancedTroubleshootingwithBOSH

APIServiceBrokerAPIv2.10 liststherequests,responses,andstatuscodesrequiredforaservicebroker.

CatalogMetadata liststhemetadatafieldsthataservicebrokermustpublishtocreatelistingsintheServicesMarketplace.

Subcommands fromtheOn-DemandServicesSDKdocumentationliststhesubcommandsthatODBserviceadaptermustrespondto.

ConfigurationPropertiesProductTemplateReferencecatalogshowtop-levelproperties,formproperties,propertyblueprints,configurableproperties,andjobtypesaredefinedintileinstaller .yml files,suchasthosegeneratedbytheTileInstallerorhand-codedlegacytiles.

PropertyBlueprintReferencecompilesanotherlistofaccessorsandvaluesforconfigurationpropertiesinthe property_blueprints sectionofatileinstaller .yml file.

ReferencingPropertiesexplainshowtospecifythelocationsoftileconfigurationpropertiesinatileinstaller .yml file.

CommandLineToolsCloudFoundryCLIReferenceGuide catalogsthecfCLI.

pcfCommandLineUtilitycatalogsthe pcf utility,whichyoucanusetobypassOpsManager.

TheFlyCLI catalogsthe fly command-lineinterfacetoConcourse.

PartnersReleaseNoticesPivotalCloudFoundryv2.2PartnersReleaseNotice





http://docs.pivotal.io/pivotalcf/customizing/troubleshooting.html

http://docs.pivotal.io/pivotalcf/devguide/deploy-apps/troubleshoot-app-health.html

http://docs.pivotal.io/pivotalcf/customizing/trouble-advanced.html

http://docs.pivotal.io/pivotalcf/1-8/services/api.html

https://docs.pivotal.io/pivotalcf/services/catalog-metadata.html#services-metadata-fields

https://docs.pivotal.io/on-demand-service-broker/creating.html#sub-commands

http://cli.cloudfoundry.org/en-US/cf/

http://concourse.ci/fly-cli.html





DevelopmentWorkflowReferencePagelastupdated:

ThisdocumentreferencestopicsthatfollowPivotal’srecommendedtiledevelopmentworkflow.

DevelopmentWorkflowThefollowingtopicscanhelpyoulearnthenecessarybackgroundinformationtopublishandmaintainafinishedtileproduct:


TileBasicsdescribeshowPCF,servicebrokers,andtilesworktogether,andhowtilesarestructured.

TypesofIntergrationsgivesahigh-levelviewofastagedtiledevelopmentprocessthatiteratesthroughincreasinglevelsofintegration:

User-ProvidedServiceBrokeredServiceManagedServiceOn-DemandService

DevelopmentEnvironmentsdescribeshowtosetupdevelopmentenvironmentsfordifferentstagesandlevelsinthetiledevelopmentprocess.

DevelopmentToolsdescribesthreetoolsthatstreamlinethetiledevelopmentprocess:TileGenerator,thepcfCommandLineutility,andConcoursecontinuousintegration(CI).

TypesofIntegrationstakesyouthroughthestagedtiledevelopmentprocess,explainingthecomponentsandstepsrequiredforeachlevelofserviceintegration:user-provided,brokered,managed,andon-demand.

TileDocumentationexplainshowtodocumentyourtileaspartofPCFdocumentation .

PublishandUpdateexplainshowtopublishyourtileonPivotalNetwork (PivNet)andpackageupgradeinformationintoyournewversions.

ReferenceprovideslanguagereferencesfortileelementssuchastheServiceBrokerAPIandthePropertieslistfortileconfiguration.

ContactUslistscontactstolearnmoreaboutthePivotalISVPartnerProgramorrequestourassistancewithyourintegrationproject,andexplainswhereyoucancontributetothisdocumentation.


https://docs.pivotal.io/tiledev/1-12/

http://docs.pivotal.io


ProductTemplateReferencePagelastupdated:

Thisdocumentdefinestheseparatepiecesofaproducttemplate.ForthepurposeofexplanationweusethePCFexampletile ,afunctionaltileprovidedbytheOpsManagerengineeringteamthatdeploystheNGINXwebserver.

Theproducttemplate,a .yml fileinthetile’s metadata subdirectory,includesorpointstothefollowing:

Metadata:highlevelinformationaboutyourtile

Dependencies:howtospecifyproductdependencies

PropertyBlueprints:thebuildingblocksofrepresentingvalues

FormTypes:exposingpropertyblueprintsintogeneratedforms

Jobs

TopLevelPropertiesThefollowingisanexampleofthepropertiesthatappearatthetopofaproducttemplate.Followingthisexamplearedefinitionsofeachproperty.

--- name: example-product product_version: <%= version.inspect %> minimum_version_for_upgrade: "1.7.0" metadata_version: "1.11" label: 'Ops Manager: Example Product' description: An example product to demonstrate Ops Manager product-author features rank: 1 service_broker: false # Default value stemcell_criteria: os: ubuntu-trusty version: <%= stemcell_version.inspect %>

enable_patch_security_updates: true releases: - name: example-release file: <%= release_file_name.inspect %> version: <%= release_file_name.match(/êxample-release-(.*)\.tgz$/)[1].inspect %>

variables: - name: credhub-password type: password

post_deploy_errands: - name: example-errand

pre_delete_errands: - name: example-errand

nameString.Required.Theinternalnameoftheproduct.Youmustkeepthenameofyourproductconsistentformigrationstofunctionproperly.Changingthenameindicatestheinstallationofacompletelydifferentproduct.

product_versionString.Required.Theversionoftheproduct.AtpresentyoucanonlyimportthisversionintoOpsManageronce.Ifyouintendtoimportthesameproduct/version,youmustdeletetheexistingonefromthe /metadata folderanddeletetheinstallationfilesfromOpsManager’sdisk.Theversionnumberisimportantformigrations.

minimum_version_for_upgradeString.Required.Youmustsetaminimumversionforupgradingtoyourcurrentproductversion.Thisexampleshowsacurrentproductversionofv1.7


https://github.com/pivotal-cf-experimental/ops-manager-example

thatonlyupgradesfromav1.6.xversionofthesameproduct:

-product_version:1.7.0.0minimum_version_for_upgrade:1.6.0.0

metadata_versionString.Required.Theversionedstructureoftheproducttemplate(thefileyouareediting).Changingtheversionnumbercanunlocknewproperties,andalsobreakpropertiesthatchangedfrompreviousversions.ThemetadataversiondoesnotalwayscorrelatetoOpsManagerversionnumberanddependsonwhat,orif,newmetadatapropertieswereintroduced.

labelString.Optional.ThelabelthatappearsintheproducttilewhenitdisplaysintheOpsManagerDashboard.

descriptionString.Optional.Adescriptionoftheproduct.ThisisnotcurrentlyusedbutmaybedisplayedinafutureversionofOpsManager.

rankInteger.Required.Theorderinwhichaproducttileappearsonthedashboard.TheOpsManagerDirectoralwaysappearsatrank100.ForyourproducttoappeartotherightofOpsManagerDirector(preferable),youmustsetthisvaluetoanintegerlessthan100.Pivotalrecommendsthatyousetitto1.OpsManagersortstilesalphabeticallyifalltileshavethesamerank.Thisisaknownweakpoint.

stemcell_criteriaHash.Required.Foralistofstemcells,includingOSandversion,seetheBOSHhub .YoudonotspecifywhichIaaStheStemcelltargets.ThiskeepsyourproducttemplateIaaSagnosticsothatoneproducttemplatecanbedeployedonanyIaaS.Atthetimeofthiswriting,noneoftheBOSHstemcellsrequireaCloudProviderInterface(CPI).ThisisexpectedtochangeinafuturereleaseofBOSH.

enable_patch_security_updates allowsyoutoautomaticallyusethelatestpatchedversionofastemcell.Thisisbydefaultsetto true .Forproductsusingstaticcompilations,youcandisablethisfeature.Ifyousetthepropertyto false ,yourproductdoesnotreceivesecuritypatchesthroughautomaticstemcellupdates.

stemcell_criteria os: ubuntu-trusty version: <%= stemcell_version.inspect %> enable_patch_security_updates: true

Thisfeatureincreasessecuritybyautomaticallyusingthelatestpatchedversionofastemcell.However,operatorsmayexperiencelongerthanexpectedupgradetimes.Formoreinformation,seeUnderstandingFloatingStemcells .

releasesArrayofHashes.Required.Thelistofreleasescontainedinyourproduct’sreleasesdirectory.Theversionofthereleasemustbeexactlythesameastheversioncontainedintherelease(BOSHreleasesareversionedandsignedbyBOSH).

Eachreleaserequiresthefollowingkeys:

name

file

version


https://bosh.io/

http://docs.pivotal.io/pivotalcf/customizing/understanding-stemcells.html

variablesArrayofHashes.Optional.Alistofvariables,thataregeneratedafteradeploysucceeds.Youcanreferencevariablesinamanifestsnippetusingtriple-parenthesesexpressions.

Eachvariablerequiresa name anda type .

post_deploy_errandsArrayofHashes.Optional.Alistoferrandsthatrunafteradeploysucceeds.

Setthe run_post_deploy_errand_default: propertyto on or off tosetthedefaultfortheerrand’srunruleselectorinOpsManager.SeeLifecycleErrands.Ifthispropertyisnotsupplied,theselectordefaultsto On .

pre_delete_errandsArrayofHashes.Optional.Alistoferrandsthatrunbeforeadeploymentisdeleted.

Setthe run_pre_delete_errand_default: propertyto on or off tosetthedefaultfortheerrand’srunruleselectorinOpsManager.SeeLifecycleErrands.Ifthispropertyisnotsupplied,theselectordefaultsto On .

icon_imageBase64Image.Required.ThisistheiconthatdisplaysonthetileintheOpsManagerInstallationDashboard.

FormPropertiesThefollowingisanexampleofthepropertiesthatappearinthe form_types sectionofaproducttemplate.Theseformsappearonthelefthandside,aslinks,afterauserclicksonthetileitself.

Asshowninalatersection,formpropertiesreference property_blueprints forthedefinitionofthetypeofdata(URL,IPaddress,list,etc.)beingsaved.Formpropertiesarethemselvesreferencedinthemanifestsectionofthe job_types section,whichwillalsobeexplainedlaterinthisdocument.TheeventualpurposeofthesepropertiesistohydrateaBOSHmanifest,whichOpsManagergeneratesontheuser’sbehalf.

Followingthisexamplearedefinitionsofeachproperty.


form_types:-name:example-formlabel:ConfigurablePropertiesdescription:Allthepropertiesthatyoucanconfigure!markdown:|##Iammarkdown,hearme_roar_.

![Alttext](http://placekitten.com/g/400/200)

Thingstodo:

1.Learn[markdown](https://daringfireball.net/projects/markdown/).1....1.Profit!property_inputs:-reference:.web_server.example_stringlabel:Examplestringdescription:'Configureapropertyoftypestring'-reference:.web_server.example_string_with_placeholderlabel:ExamplestringcontainingPlaceholdertextdescription:'Optionalfield.Configurationnotnecessary'placeholder:'Ghosttext.Spooky!'-reference:.web_server.example_migrated_integerlabel:Exampleintegerdescription:'Configureapropertyoftypeinteger'-reference:.web_server.example_booleanlabel:Examplebooleandescription:'Configureapropertyoftypeboolean'-reference:.web_server.example_dropdownlabel:Exampledropdowndescription:'Configureapropertyoftypedropdown'-reference:.web_server.example_domainlabel:Exampledomaindescription:'Configureapropertyoftypedomain'-reference:.web_server.example_wildcard_domainlabel:Examplewildcard_domaindescription:'Configureapropertyoftypewildcard_domain'-reference:.web_server.example_string_listlabel:Examplestring_listdescription:'Configureapropertyoftypestring_list'-reference:.web_server.example_textlabel:Exampletextdescription:'Configureapropertyoftypetext(settingto"magicvalue"causesthewebserverjobinstancecounttogoto0)'-reference:.web_server.example_ldap_urllabel:Exampleldap_urldescription:'Configureapropertyoftypeldap_url'-reference:.web_server.example_emaillabel:Exampleemaildescription:'Configureapropertyoftypeemail'-reference:.web_server.example_http_urllabel:Examplehttp_urldescription:'Configureapropertyoftypehttp_url'-reference:.web_server.example_ip_addresslabel:Exampleip_addressdescription:'Configureapropertyoftypeip_address'-reference:.web_server.example_ip_rangeslabel:Exampleip_rangesdescription:'Configureapropertyoftypeip_ranges'-reference:.web_server.example_multi_select_optionslabel:Examplemulti_select_optionsdescription:'Configureapropertyoftypemulti_select_options'-reference:.web_server.example_network_address_listlabel:Examplenetwork_address_listdescription:'Configureapropertyoftypenetwork_address_list(thispropertywasmarkedwithfreeze_on_deploy,andsowillnotbeeditableafterchangesarefirstapplied)'-reference:.web_server.example_network_addresslabel:Examplenetwork_addressdescription:'Configureapropertyoftypenetwork_address'-reference:.web_server.example_portlabel:Exampleportdescription:'Configureapropertyoftypeport'-reference:.web_server.example_smtp_authenticationlabel:Examplesmtp_authenticationdescription:'Configureapropertyoftypesmtp_authentication'-reference:.web_server.client_certificatelabel:Examplecertificatedescription:'Configureacertificate'

name


String.Required.Theinternalnameoftheform.

labelString.Required.Thelabeloftheformasitappearsasalinkonthelefthandsideofeachform.

descriptionString.Optional.Thedescriptionoftheform.Appearsatthetopoftheformasaheader.

markdownMarkdown.Optional.Provideablockofmarkdowntodisplayatthetopoftheform.Includesimagesupport.Youcanusethispropertytodocumentthetileandprovideexplanationsorreferences.

property_inputsArrayofHashes.Required.Referencestopropertiesdefinedintheproperty_blueprintssectionoftheproducttemplate.

placeholderString.Optional.Specifyplaceholdertextforafield.Thetextappearsinlightgraytoshowanexamplevaluefortheuser.Thetextdisappearswhentheusertypesinthefieldandreappearsiftheuserleavesthefieldempty.

The placeholder attributedisplaysforthefollowingformtypes:

string

integer

domain

wildcard_domain

string_list

text

ldap_url

email

http_url

ip_address

ip_ranges

network_address_list

network_address

port

Simplevs.ComplexInputs(SelectorsandCollections)Mostpropertiesaresimplevaluessuchasstrings,integers,URLaddresses,orIPaddresses.Othersarecomplex,suchasselectorsorcollections.

Selectorsareameansofgivingtheuserachoiceofasetofinputs.Collectionsareameansofgivingtheusertheabilitytoenteranarrayofvaluestocreateahash.

Selectorsappearasfollows:


Collectionsappearasfollows:

PropertyBlueprintsThefollowingisanexampleofthe property_blueprints thatappearinaproducttemplate.TheseblueprintsdefineanythingthatwilleventuallyendupintheBOSHmanifestgeneratedbyOpsManager.

Notethatoneoftheseblueprintsreferencesamigratedvalue,whichcamefromtheExampleProductv1.6usingmigrations.


property_blueprints:-name:example_selectortype:selectorconfigurable:truedefault:Pizzafreeze_on_deploy:trueoption_templates:-name:pizza_optionselect_value:Pizzanamed_manifests:-name:my_snippetmanifest:|pizza_toppings:pepperoni:((.properties.example_selector.pizza_option.pepperoni.value))pineapple:((.properties.example_selector.pizza_option.pineapple.value))other:((.properties.example_selector.pizza_option.other_toppings.value))-name:provides_sectionmanifest:|as:'pizza_link_web_server_job'-name:consumes_sectionmanifest:|from:'pizza_link_web_server_job'property_blueprints:-name:pepperonitype:booleanconfigurable:truefreeze_on_deploy:true-name:pineappletype:booleanconfigurable:truedefault:true-name:other_toppingstype:stringconfigurable:trueoptional:trueconstraints:-must_match_regex:'\A[^!@#$%^&*()]*\z'error_message:'Thisnamecannotcontainspecialcharacters.'-name:filet_mignon_optionselect_value:FiletMignonnamed_manifests:-name:my_snippetmanifest:|rarity:((.properties.example_selector.filet_mignon_option.rarity_dropdown.value))review:((.properties.example_selector.filet_mignon_option.review.value))secret_sauce:((.properties.example_selector.filet_mignon_option.secret_sauce.value))-name:provides_sectionmanifest:|as:'filet_mignon_link_web_server_job'-name:consumes_sectionmanifest:|from:'filet_mignon_link_web_server_job'property_blueprints:-name:rarity_dropdowntype:dropdown_selectconfigurable:truedefault:rareoptions:-name:rarelabel:'Rare'-name:mediumlabel:'Medium'-name:well-donelabel:'Welldone'

configurableNopropertywillbeviewableinaformifunless configurable issetto true .Ratherthangivingtheusertheabilitytoenteravalue,thevalueisgeneratedbyOpsManager.

must_match_regexRegularExpression.Optional.Createavalidatorthatrunsontheformsaveevent.Iftheuserinputdoesnotmatchthe must_match_regex constraint,theformdisplaysthespecified error_message .Multiple must_match_regex constraintsforasinglepropertyblueprintareevaluatedintheorderlisted.


ConfigurablePropertiesManyofthesepropertiesarestrings,butcanbeusedwithvalidatorsinordertocheckthattheusertypedinthecorrectformatforaURL,IP,address,domain,etc.

stringAstring.

integerAninteger.

booleanAboolean.Viewedasacheckbox.

dropdown_selectAlistofoptions.TheuserchoosesoneviewedasanHTMLselectbox.

multi_select_optionsAlistofoptions.Theuserchooseszeroormore,viewedasHTMLcheckboxes.

domainAsecond,third,fourth,etcleveldomain.

wildcard_domainAdomainwithawildcardinfrontofit.Example: *.domain.com

textAstring.AppearsasanHTMLtextarea.

ldap_urlAURLprefacedby ldap:// .

emailAnemailaddress.

ip_rangesArangeofIPaddresses,withdashesandcommasallowed.Example: 1.1.1.1-1.1.1.4,2.2.2.1-2.2.2.4


portAnintegerrepresentinganetworkport.

network_addressAsingleIPaddressordomain.Example: 1.1.1.1

network_address_listAlistofIPaddressesordomains.Example: 1.1.1.1,example.com,2.2.2.2

GeneratedProperties(canalsobeconfigurable)Thefollowingpropertiesareconfigurable,butcanalsobegeneratedbyOpsManagerifconfigurableisfalseortheconfigurablekeyisomitted.Theexceptionsaretheuuidandsaltedcredentialsproperties,whichareneverconfigurable.

rsa_cert_credentialsAnRSAcertificate.

rsa_pkey_credentialsAnRSAprivatekey.

salted_credentialsUsernameandpasswordcreatedusinganon-reversiblehashalgorithm.

simple_credentialsUsernameandpassword.

secretArandomstringorpassword.

uuidAuniversaluniqueidentifier.

ComplexProperties(SelectorsandCollections)Theselectorandcollectionsinputsarereferencedbytheirselectorandcollectionpropertyblueprints.Thesearemorecomplicatedthansimplepropertiesinthattheycontainmanifestsnippets,whicharefurtherreferencedinothermanifestsnippets.Wewilllearnaboutmanifestsnippetsinthenextsection.


JobTypesThefollowingisanexampleofthe job_types sectionthatappearsinaproducttemplate.ThissectiondefinesthejobsthatendupinaBOSHmanifest.ThosejobsaredefinedinyourBOSHrelease.Jobsrequiremanydifferentsettingsinordertofunctionproperly,andthatisthecruxofwhatOpsManagerdoesforyou:itasksauserforvaluestothosesettingsandgeneratesamanifestbasedonwhatwasentered.

OpsManagerdoesnotrequireproductauthorstoprovide vm_credentials inthe property_blueprints foreach job_type .Thisisbecause vm_credentials aregeneratedautomatically,andyoucanfindtheminthereleasemanifest.

job_types:-name:web_serverresource_label:WebServertemplates:-name:web_serverrelease:example-release-name:time_loggerrelease:example-releaserelease:example-releasestatic_ip:1dynamic_ip:0max_in_flight:1single_az_only:trueinstance_definition:name:instancestype:integerconfigurable:truedefault:1constraints:max:1zero_if:property_reference:'.web_server.example_text'property_value:'magicvalue'resource_definitions:-name:ramtype:integerconfigurable:truedefault:1024-name:ephemeral_disktype:integerconfigurable:truedefault:2048-name:persistent_disktype:integerconfigurable:truedefault:1024constraints:min:1024-name:cputype:integerconfigurable:truedefault:1property_blueprints:-name:static_ipstype:ip_rangesconfigurable:trueoptional:true-name:generated_rsa_cert_credentialstype:rsa_cert_credentials-name:generated_rsa_pkey_credentialstype:rsa_pkey_credentials-name:generated_salted_credentialstype:salted_credentials-name:generated_simple_credentialstype:simple_credentials-name:generated_secrettype:secret-name:generated_uuidtype:uuid-name:example_string_with_placeholdertype:stringconfigurable:trueoptional:trueplaceholder:'Configureme!'-name:example_stringtype:stringconfigurable:truedefault:'Helloworld'constraints:-must_match_regex:'^[^!@#$%^&*()]*$'error_message:'Thisnamecannotcontaincapitaldigits.'-must_match_regex:'^[^0-9]*$'


error_message:'Thisnamecannotcontaindigits.'-name:example_migrated_integertype:integerconfigurable:truedefault:1-name:example_booleantype:booleanconfigurable:truedefault:true-name:example_dropdowntype:dropdown_selectconfigurable:truedefault:kiwioptions:-name:kiwilabel:'labelforkiwi'-name:limelabel:'labelforlime'-name:avocadolabel:'labelforavocado'-name:example_domaintype:domainconfigurable:truedefault:www.example.com-name:example_wildcard_domaintype:wildcard_domainconfigurable:truedefault:'example.com'-name:example_string_listtype:string_listconfigurable:truedefault:'a,list,of,strings'-name:example_texttype:textconfigurable:truedefault:'some_text'-name:example_ldap_urltype:ldap_urlconfigurable:truedefault:'ldap://example.com'-name:example_emailtype:emailconfigurable:truedefault:[email protected]:example_http_urltype:http_urlconfigurable:truedefault:'http://www.example.com'-name:example_ip_addresstype:ip_addressconfigurable:truedefault:'192.168.0.1'-name:example_ip_rangestype:ip_rangesconfigurable:truedefault:'1.1.1.1-1.1.1.4,2.2.2.1-2.2.2.4'-name:example_multi_select_optionstype:multi_select_optionsconfigurable:truedefault:['earth','jupiter']options:-name:mercurylabel:'labelformercury'-name:venuslabel:'labelforvenus'-name:earthlabel:'labelforearth'-name:marslabel:'labelformars'-name:jupiterlabel:'labelforjupiter'-name:saturnlabel:'labelforsaturn'-name:uranuslabel:'labelforuranus'-name:neptunelabel:'labelforneptune'-name:example_network_address_listtype:network_address_listconfigurable:truedefault:'1.1.1.1,example.com,foo.bar.example.com'-name:example_network_addresstype:network_addressconfigurable:truedefault:'1.1.1.1'


default:'1.1.1.1'-name:example_porttype:portconfigurable:truedefault:1111-name:example_smtp_authenticationtype:smtp_authenticationconfigurable:truedefault:plain-name:client_certificatetype:ca_certificateconfigurable:trueoptional:truemanifest:|generated:root_rsa_certificate:(($ops_manager.ca_certificate))rsa_cert_credentials:public_key_pem:((generated_rsa_cert_credentials.public_key_pem))cert_and_private_key_pems:((generated_rsa_cert_credentials.cert_and_private_key_pems))rsa_pkey_credentials:public_key_pem:((generated_rsa_pkey_credentials.public_key_pem))private_key_pem:((generated_rsa_pkey_credentials.private_key_pem))public_key_openssh:((generated_rsa_pkey_credentials.public_key_openssh))public_key_fingerprint:((generated_rsa_pkey_credentials.public_key_fingerprint))salted_credentials:sha512_hashed_password:((generated_salted_credentials.sha512_hashed_password))identity:((generated_salted_credentials.identity))salt:((generated_salted_credentials.salt))password:((generated_salted_credentials.password))simple_credentials:identity:((generated_simple_credentials.identity))password:((generated_simple_credentials.password))secret:((generated_secret.value))uuid:((generated_uuid.value))configured:string:((example_string.value))integer:((example_migrated_integer.value))...record_collection:((.properties.example_collection.value||[]))selector:((.properties.example_selector.selected_option.parsed_manifest(my_snippet)))ops_manager_provided_accessors:name:((name))ram:((ram))ephemeral_disk:((ephemeral_disk))persistent_disk:((persistent_disk))instances:((instances))availability_zone:((availability_zone))first_ip:((first_ip))ips:((ips))ips_by_availability_zone:((ips_by_availability_zone))bosh_job_partition_stats:((bosh_job_partition_stats))

nameString.Required.ThenameofthejobasitwillbecreatedintheOpsManagergeneratedBOSHmanifest.

resource_labelString.Required.Thelabelofthejobasitwillappearintheresourcespageofthetile.

templatesArrayofHashes.Required.Eachelementhasthefollowingfields:

name

Thenameofthejobtemplatetouse.Required.

release


Thenameofthereleasethetemplateisfrom.Required.

consumes

AYAMLstringdefiningBOSHlinks thisjobconsumes.Optional.

provides

AYAMLstringdefiningBOSHlinks thisjobprovides.Optional.

ThisisaBOSHfeature(creatingjobsfromdifferentreleases).SeetheBOSHdocumentation formoreinformation.

releaseString.Required.ThenameoftheBOSHreleasecontainedinyourproductarchive(.pivotalfile).

static_ipBoolean.Required.SetswhethertheBOSHjobshouldhaveastaticordynamicIP.StaticIPsaresetbytheuser,andreserved,whileDynamicIPsaresetbyBOSH.Bothare,ineffect,static,inthattheyshouldnotchangebetweendeployments.

dynamic_ipBoolean.Required.Settheoppositeof static_ip .Thiswilleventuallybeeliminatedasapropertyasitisobviouslyredundantandunnecessary.

single_az_onlyBoolean.Required.Youcangiveuserscontrolofbalancingjobsacrossavailabilityzones(AZs)bysetting single_az_only to false .TolimitajobtoasingleAZ,setthisto true .

max_in_flightInteger.Required.ABOSHsettingthatcontrolsthenumberofinstancesofthisjobthatBOSHwilldeployinparallel.

resource_definitionsArrayofHashes.Required.Asetofresourcesettingsforthejobalongwithmaxandminconstraints,defaults,andwhetherornottheusercanconfigure(change)thesetting.Theresourcesthatcanbesetare:

ram

ephemeral_disk

persistent_disk

cpu

warning:Ifyouchangethe single_az_only setting,yourVMsmayswitchAZs.Thischangecancauseanorphaneddisk.

Note:Ifyousetthe default propertyfor persistent_disk to 0 ,userscannoteditthisvalueandtheResourceConfigpageinOpsManangerdisplaysNoneunderthepersistentdiskfield.




https://bosh.io/

instance_definitionHash.Required.Thenumberofdefaultinstancesforajobalongwithmax,min,odd,andtheabilitytodecreasesizingafterdeployconstraints.

IfyourproductusesanexternalservicethatperformsthesamejobasaserviceinElasticRuntime,youcanreduceresourceusagebysettingtheinstancecountofajobto 0 withthe zero_if property.Forexample,yourproductusesAmazonRelationalDatabaseService(RDS)insteadofMySQL,whichisthedefaultsystemdatabaseforElasticRuntime.Set property

referenceto .properties.system.database and propertyvalue to magicvalue tochangetheinstance

countsofallMySQLjobsto 0 .

manifestTextsnippet,prefacedbypipesymbol: | .Optional.OpsManagergeneratesaBOSHmanifestthatdefinespropertiesforeachjobthatthemanifestdeploys.SomeofthesepropertiesarenotsetuntiltheuserclicksApplyChanges,becausetheuserconfigurestheminthetileorbecauseOpsManagerhastogeneratethem.

Toincludethesepropertiesinamanifestsnippet,use“double-parens”syntax,whichconsistsofavariablenamesurroundedbytwosetsofparentheses:

manifest:|pizza_toppings:peppers:((.properties.example_selector.pizza_option.peppers.value))

WhenOpsManagerparsesaproducttemplateandBOSHparsesamanifest,theybothfillinpropertiesdesignatedbydouble-parenssyntax.Somepropertyvaluesinaproducttemplate,suchasCredHubcredentials,mustbefilledinbyBOSHontheBOSHDirectorVM,ratherthanbyOpsManager.ToincludetheseBOSHdeploy-timepropertiesinamanifestsnippet,use“triple-parens”notation:

manifest:|credhub:concatenated_password:prefix-(((credhub-password)))-suffixpassword:(((credhub-password)))

OpsManagerstripstheouterparenthesesfromtheseexpressionsandincludestheresultingdouble-parensexpressionsinthemanifestitgenerates,forBOSHtoevaluateatdeploytime.

SelectorManifestSnippetsSelectorsnippetsareevaluatedtwice.Asyousawinthe property_blueprint ,theselectorhasamanifestsnippetforbothsetsofinputsthattheusermightchoose.Onlyoneofthesesetsisevaluatedandinsertedintothejob’smanifest.

OpsManagerProvidedSnippetsThefollowingdouble-parensaccessorsretrieveyourjobproperties:

name: (( name ))

ips: (( ips ))

ram: (( ram ))

ephemeral_disk: (( ephemeral_disk ))

persistent_disk: (( persistent_disk ))

ips_by_availability_zone: (( ips_by_availability_zone )) (deprecated)

instances: (( instances ))

availability_zone: (( availability_zone )) (deprecated)

bosh_job_partition_stats: (( bosh_job_partition_stats )) (deprecated)

first_ip: (( first_ip )) (deprecated)

first_network_deprecated: (( first_network_deprecated )) (deprecated)

subnet_cidrs: (( subnet_cidrs ))


Thefollowingisalistofalltypedvalueswiththeaccessor“value”:

collection

ldap_url

domain

wildcard_domain

ip_ranges

ip_address

email

port

integer

string

boolean

text

smtp_authentication

network_address


string_list

ca_certificate

multi_select_options

dropdown_select

vm_type_dropdown

disk_type_dropdown

uuid

service_network_az_multi_select

service_network_az_single_select

secret

Thefollowinglistshowstypedvalueswithmultipleaccessors:

simple_credentials:identity,password

rsa_cert_credentials:private_key_pem,cert_pem,public_key_pem,cert_and_private_key_pems

rsa_pkey_credentials:private_key_pem,public_key_pem,public_key_openssh,public_key_fingerprint

salted_credentials:salt,identity,password

selector:value,selected_option,nestedcontext

Inaddition,OpsManagersupportsaccessorsthatareglobaltotheentireinstallationratherthanjobspecific.

$ops_manager.ca_certificate:TheinternalSSLCAcertificateusedtosignallSSLcertificatesgeneratedbythisOpsManagerinstance,suchaswhentheuserclicksaGenerateSelf-SignedRSACertificatelink

$ops_manager.trusted_certificates

$ops_manager.http_proxy

$ops_manager.https_proxy

$ops_manager.no_proxy

$director.deployment_ip

$director.hostname

$director.username

$director.password

$director.ntp_servers

$director.ca_public_key

$director.tld

$director.bosh_metrics_forwarder_client_name

$director.bosh_metrics_forwarder_client_secret


$self.uaa_client_name

$self.uaa_client_secret

$self.service_network

$self.stemcell_version

..PRODUCT-NAME.properties

..PRODUCT-NAME.deployment_name


PropertyReferencePagelastupdated:

ThistopicexplainshowPCFTilesdescribeproperties.

Double-ParenthesesExpressionsTheproducttemplate .yml fileinatile’s metadata subdirectorydefineshowthetileinterfacecollectsconfigurablepropertiesfromtheuser,andhowOpsManagerincorporatesthesepropertiesintothedeploymentmanifestthatitcreates.

Theproducttemplatecontains manifest snippetsinboththe form_types sectionthatdefinesthetileinterface,andthe job_types sectiondescribingthejobsthatthemanifestdeploys.Withinthesesnippets,youcanusespecialexpressionstoincludepropertyvaluesthatareotherwisenotknownaheadoftime,suchasconfigurablepropertiesorsystemproperties:

Double-parenthesesexpressionsdesignatepropertyvaluesthatOpsManagerfillsinwhenitgeneratesthedeploymentmanifest,aftertheuserclicksApplyChanges.ThesevaluesincludeconfigurablepropertiesandpropertiessuppliedbyOpsManager.

Triple-parenthesesexpressionsdesignatepropertyvaluesthatBOSHsupplieswhenitdeploysinstancesofthetileservice,suchasCredHubcredentials.

ReferencingPropertiesEvaluatingapropertycanberepresentedbypiecingtwosegmentstogether:

Thelocationoftheproperty

Whatinformationfromthepropertyyouarelookingtoaccess,oraccessors

Together,thedouble-parenthesesexpressioncanbewrittenas:

((LOCATION_OF_PROPERTY.ACCESSOR))

Themethodofreferencingthelocationofthepropertyvaries.Hereisacompletelistofwaystoreferenceapropertywithsomehelptexttoindicatethesituation.

.properties.top_level_propertyReferstothepropertyblueprintwhosenameis“top_level_property”foundinthegloballistofpropertiesofthesameproduct

.job_one.job_level_propertyReferstothepropertyblueprintwhosenameis“job_level_property”foundinthelistofpropertiesofthejob“job_one”ofthesameproduct

job_level_propertyReferstothepropertyblueprintwhosenameis“top_level_property”foundinthesameproductandjobwhosemanifestiscurrentlybeingevaluated

..other_product.properties.top_level_propertyReferstothepropertyblueprintwhosenameis“top_level_property”foundinthegloballistofpropertiesoftheproduct“other_product”

..other_product.job_two.job_level_propertyReferstothepropertyblueprintwhosenameis“job_level_property”foundinthelistofpropertiesofthejob“job_one”oftheproduct“other_product”

Accessorsvarybetweenpropertyblueprinttypes.SeethePropertyBlueprintReferenceforavailablepropertiesandtheiraccessors.

Thefollowingexampleusesthepropertyblueprinttype string withitsoneaccessor, value .Avaliddouble-parenthesesexpressiontoaccessthevalueofthisproperty(assumingitistop-level,andhasthename example-string )wouldlooklike:

((.properties.example-string.value))

OpsManagerallowsemptyarraysindouble-parenthesesexpressions.Forexample:

((.properties.example-string.value||[]))

Note:OpsManager1.12andlatersupportusingemptyarraysindouble-parenthesessyntax.


DollarContextsOutsideofproperties,youcanalsoretrieveinformationaboutvariousconfigurationdetailsofyourproductandOpsManager.

$ops_manager:usedbyanyproducttoobtaininformationaboutspecificOpsManager

$director:usedbyanyproducttoobtaininformationabouttheDirector

$self:usedbyyourownproducttoobtaininformationaboutyourproduct’sconfiguration

$ops_manager

ca_certificate ProvidestherootCAcertthatisusedtosigntheDirectorVM

trusted_certificates ProvidesalistofcertsthatareappliedbytheDirectortoallVMs

http_proxy ProvidesthecommaseparatedvaluesthatareenteredifOpsManagertrafficisdirectedtoanHTTPProxy

https_proxy ProvidesthecommaseparatedvaluesthatareenteredifOpsManagertrafficisdirectedtoanHTTPSProxy

no_proxy Providesathecommaseparatedvaluesthatshouldnotgothroughaproxy

$director

deployment_ip ProvidestheIPaddressthattheBOSHDirectorisdeployedon

username ProvidestheusernamefortheDirectorVM

password ProvidesthepasswordfortheDirectorVM

ntp_servers ProvidesalistofntpserversthataredeployedbytheDirector

ca_public_key ProvidesthepublickeythatisusedtosigntheDirectorVM

hostname ProvidesthehostnamefortheDirectorVM

tld Returnsthestring bosh asthetop-leveldomain(TLD)oftheBOSHDirector

bosh_metrics_forwarder_client_name ProvidestheBOSHMetricsForwarderclientname

bosh_metrics_forwarder_client_secret ProvidestheBOSHMetricsForwarderclientsecret

$self

uaa_client_name ProvidestheUAAclientnamecreatedforyourProducttocommunicatewiththeBOSHDirector

uaa_client_secret ProvidestheUAAclientsecretcreatedforyourProducttocommunicatewiththeBOSHDirector

service_network Providesthenameoftheservicenetworkthathasbeenassignedtoyourproduct

stemcell_version Providesthestemcellversionthatisbeingusedbyyourproduct

PropertyBlueprintReference

string

Holdsasinglestringvalue

Accessors:

value Returnsthestringvalue

Producttemplateexample:

Note:Supportforthe $director.username and $director.password accessorswillberemovedinfutureversionsofOpsManager.


-name:example_stringtype:stringconfigurable:truedefault:'Helloworld'constraints:-must_match_regex:'\A[^!@#$%^&*()]*\z'error_message:'Thisnamecannotcontainspecialcharacters.'-must_match_regex:'\A[^0-9]*\z'error_message:'Thisnamecannotcontaindigits.'

boolean

Holdsasinglebooleanvalue

Accessors:

value Returnsthebooleanvalue

Example:

-name:example_booleantype:booleanconfigurable:truedefault:false

collection

Collectionsrepresenttheabilitytoholdmulti-propertyentries.Each“record”willcontainvaluesfortheconfiguredsetofpropertyblueprints.

Accessors:

valueAnarrayofhasheswhosekeyarethepropertyname.Example: [{album: 'my-album', artist: 'some-artist', explicit: true, genre: 'rock'}]

Example:

-name:example_collectiontype:collectionconfigurable:trueproperty_blueprints:-name:albumtype:stringfreeze_on_deploy:true-name:artisttype:stringfreeze_on_deploy:true-name:explicittype:boolean-name:genretype:dropdown_selectconfigurable:trueoptional:trueoptions:-name:rocklabel:'Rock'-name:countrylabel:'Country'-name:edmlabel:'BeepBoopPSH'default:-album:ChristmasCarolsartist:OpsManateeexplicit:truegenre:edm

Selector


Providestheabilitytoswitchbetweengroupsofproperties.

Selectorsareuniqueinthewaythatpropertyinformationisaccessed.OpsManagerprovidesaccessorsavailableatthetop-levelselectorproperty,accessorsforretrievingaspecificpropertyinanoptiongroup,andtheabilitytoprovidemanifestsnippetsforaselectoroptiongroup.

Eachselectorgroupmayprovidemanifestsnippets.ThisisbecauseOpsManagerdoesnotsupportconditionallyaddingmanifestsnippets.Therefore,it’sdifficulttobeabletowritemanifestsectionsforaselector.Amanifestsnippetshouldbepresentwithinalloptiongroups,andcan

AccessorsonSelectorProperty:

value Returnsastringofthecurrentlyselectedoptiongroup.Example:“FiletMignon”

selected_optionScopestheaccessortothecurrentlyselectedoptiongroup.Doesnotreturnmeaningfulinformationalone.MustbechainedwithanaccessoravailabletoaSelectorOptionGroup.

SPECIFIC_SELECTOR_OPTION_GROUPScopestheaccessortoaspecificselectoroptiongroup.Doesnotreturnmeaningfulinformationalone.Mustbefollowedwiththenameandaccessorofaspecificpropertyintheoptiongroup.

Example, value :

.properties.example_selector.filet_mignon_option.review.value

AccessorsonSelectorOptionGroup:

parsed_manifest(manifest_snippet_name) Returnsahashofthespecificmanifestsnippet

Example, selected_option :

.properties.example_selector.selected_option.parsed_manifest(my_snippet)

Here, my_snippet correspondstothenameofanentrywithineachoption_template’snamed_manifestssection.

Example,optiongroup:


-name:example_selectortype:selectorconfigurable:truedefault:Pizzafreeze_on_deploy:trueoption_templates:-name:pizza_optionselect_value:Pizzanamed_manifests:-name:my_snippetmanifest:|pizza_toppings:pepperoni:((.properties.example_selector.pizza_option.pepperoni.value))pineapple:((.properties.example_selector.pizza_option.pineapple.value))other:((.properties.example_selector.pizza_option.other_toppings.value))property_blueprints:-name:pepperonitype:booleanconfigurable:truefreeze_on_deploy:true-name:other_toppingstype:stringconfigurable:trueoptional:trueconstraints:-must_match_regex:'\A[^!@#$%^&*()]*\z'error_message:'Thisnamecannotcontainspecialcharacters.'-name:filet_mignon_optionselect_value:FiletMignonnamed_manifests:-name:my_snippetmanifest:|rarity:((.properties.example_selector.filet_mignon_option.rarity_dropdown.value))review:((.properties.example_selector.filet_mignon_option.review.value))secret_sauce:((.properties.example_selector.filet_mignon_option.secret_sauce.value))property_blueprints:-name:rarity_dropdowntype:dropdown_selectconfigurable:truedefault:rareoptions:-name:rarelabel:'Rare'-name:mediumlabel:'Medium'-name:well-donelabel:'Welldone'-name:secret_saucetype:secretconfigurable:trueoptional:true

ldap_url

EnsurestheinputtedstringmatchesaURLoftheLDAPprotocol

Accessors:

value Returnsastring

Example:

-name:example_ldap_urltype:ldap_urlconfigurable:truedefault:'ldap://example.com'

domain

Ensuresthestringvalueisadomain

Accessors:



Example:

-name:example_domaintype:domainconfigurable:truedefault:'example.com'

wildcard_domain

Ensuresthestringvalueisadomainprefixedwith“*.”

Accessors:


to_wildcard Returnsastringofthevalueprefixedwith“*.”ifnotpresent

Example:

-name:example_wildcard_domaintype:wildcard_domainconfigurable:truedefault:'*.example.com'

ip_ranges

HoldsanarrayofstringsandensurethevaluesareIPranges

Accessors:

value Returnsastringcontainingacomma-separatedlistofIPranges

parsed_ip_ranges ReturnsanarrayofstringsforeachIPrange

Example:

-name:example_ip_rangestype:ip_rangesconfigurable:truedefault:'1.1.1.1-1.1.14,2.2.2.1-2.2.2.4'

ip_address

EnsuresthestringvalueisanIPaddress

Accessors:


Example:

-name:example_ip_addresstype:ip_addressconfigurable:truedefault:'192.168.0.1'

email

Ensuresthestringvalueisformattedasanemailaddress


Accessors:


Example:

-name:example_stringtype:emailconfigurable:truedefault:'[email protected]'

port

Holdsasingleintegervalue

Accessors:

value Returnsaninteger

Example:

-name:example_porttype:portconfigurable:truedefault:3000

integer

Holdsasingleintegervalue

Accessors:

value Returnsaninteger

Example:

-name:example_integertype:integerconfigurable:truedefault:100

text


Accessors:


Example:

-name:example_texttype:textconfigurable:truedefault:|ExampleText

smtp_authentication


Holdsstringwithapossiblevalueofplain,login,orcram_md5

Accessors:

value Returnsastringwithpossiblevalueof plain , login , cram_md5

Example:

-name:example_smtp_authenticationtype:smtp_authenticationconfigurable:truedefault:plain

network_name

Ensurethestringisanetworkname

Accessors:


Example:

-name:example_network_nametype:network_nameconfigurable:truedefault:'ExampleNetwork'

network_address

Ensurethestringisanetworkaddress

Accessors:


Example:

-name:example_network_addresstype:network_addressconfigurable:truedefault:'localhost'


Holdsanarrayofnewaddresses

Accessors:

value Returnsastringcontainingacommaseparatedlistofnetworkaddresses

parsed_network_addresses Returnsanarrayofstringsforeachnetworkaddress

Example:

-name:example_network_address_listtype:network_address_listconfigurable:truedefault:'localhost,1.1.1.1'


string_list

Holdsanarrayofstrings

Accessors:


parsed_strings Returnsanarrayofstringsforeachstringentry

parsed_regexReturnsastringcontainingaregexoftheformat“^(string1|string2|string3)$”wherethevalueofthispropertyis“string1,string2,string3”

Example:

-name:example_string_listtype:string_listconfigurable:truedefault:'foo,bar,baz'

ca_certificate

Holdsastringvalue

Accessors:


Example:

-name:example_ca_certificatetype:ca-certificateconfigurable:truedefault:|--BEGINFAKECERT----ENDFAKECERT--

multi_select_options

Holdsanarrayofselectedstringvalues

Accessors:

value Returnsanarrayofstringsfortheselectedoptions

Example:

-name:example_multi_select_optionstype:multi_select_optionsconfigurable:truedefault:['earth','mercury']options:-name:mercurylabel:'labelformercury'-name:venuslabel:'labelforvenus'-name:earthlabel:'labelforearth'

dropdown_select

Holdsanarrayofstringsselectedstringvalues

Accessors:



Example:

-name:example_dropdowntype:dropdown_selectconfigurable:truedefault:kiwioptions:-name:kiwilabel:'labelforkiwi'-name:limelabel:'labelforlime'-name:avocadolabel:'labelforavocado'

vm_type_dropdown

Holdssinglestringvalueselectedfromallowedvm_types

Accessors:


Example:

-name:example_vm_type_dropdowntype:vm_type_dropdownconfigurable:true

disk_type_dropdown

Holdssinglestringvalueselectedfromalloweddisk_types

Accessors:


Example:

-name:example_disk_type_dropdowntype:disk_type_dropdownconfigurable:true

uuid

Holdsastringuuidvalue

Accessors:


Example:

-name:example_uuidtype:uuidconfigurable:true

service_network_az_multi_select

Holdsanarraysofstringvalueselectedfromallowedazs


Accessors:

value Returnsanarrayofstringsfortheselectedoptions

Example:

-name:example_service_network_az_multi_selecttype:service_network_az_multi_selectconfigurable:true

service_network_az_single_select

Holdsasinglestringvalueselectedfromallowedazs

Accessors:


Example:

-name:example_service_network_az_single_selecttype:service_network_az_single_selectconfigurable:true

secret


Accessors:


Example:

-name:example_secrettype:secretconfigurable:true


ContactUsPagelastupdated:

TolearnmoreaboutthePivotalISVPartnerProgram,ortorequestourassistancewithyourintegrationproject,pleasecontactusatoneofthefollowingaddresses:

ProgramManager:MarinaJoseph

BusinessDevelopment:NimaBadiey

PlatformEngineering:GuidoWestenberg

ContributionsThesourcecodeforthissiteisinapublicGitHubrepository .

Wegreatlyappreciatecontributionstothecontentintheformofpullrequests,aswellasGitHubissueswithcorrections,comments,orsuggestions.





https://github.com/pivotal-cf/docs-book-tiledev

Documents

PCF Tile Developer Guide v1 - Pivotal Software...workshop is free for all Pivotal partners. Pivotal recommends any interested partner to register for Partner Days . If you are not