PCF Tile Developer Guide v2Note: PCF Tile Developer Guide v2.0 is not designed for use with the...

PCFTileDeveloperGuide

v2.0

Published:8April2019

©2019PivotalSoftware,Inc.AllRightsReserved.

236

1112141920242628293031323438394042444648525359606273778081828588949596

110121

TableofContents

TableofContentsPCFTileDeveloperGuidePCFv2.0PartnersReleaseNoticeTileBasicsHowPCFandPCFServicesWorkHowTilesWorkConfiguringDiskandVMTypeDefaultsforOn-DemandServiceTilesManagingRuntimeConfigsTestingTilesTypesofIntegrationUser-ProvidedServiceBrokeredServiceServiceBrokersManagedServiceBOSHReleasesErrandsOn-DemandServiceBuildpacksCredHubCreatingNewVariablesinCredHubMigratingExistingCredentialstoCredHubFetchingVariableNamesandValuesSecuringServiceCredentialswithRuntimeCredHubEmbeddedAgentsLogs,Metrics,andNozzlesDevelopmentToolsDevelopmentEnvironmentsTileGeneratorpcfCommandLineUtilityContinuousIntegrationTestingPivotalCloudFoundryServicesSDKPublishandUpdateTileDocumentationPartnerSoftwareProductReleaseCycleUpgradingTilesReferencesDevelopmentWorkflowReferenceProductTemplateReferencePropertyReferenceContactUs

©CopyrightPivotalSoftwareInc,2013-2019 2 2.0


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:PCFTileDeveloperGuidev2.0isnotdesignedforusewiththecurrentversionsofOpsManager.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.


PCFv2.0PartnersReleaseNoticePagelastupdated:

ThistopicdescribesthechangesthatPivotalCloudFoundry(PCF)v2.0introduceswhichmayberelevanttopartnerservicetiles.

ColocatedErrandsTileauthorscanconfiguretheerrandsdefinedintheirproducttiletorunonexistingvirtualmachines(VMs)inadeployment.Colocatederrandsrunfasterthantraditionalerrandsandusefewerresources,includingdiskandIPspace.

SeeTileErrandsformoreinformation.

RuntimeConfigsTileauthorscaninclude runtime_configs asatop-levelkeyintilemetadatatodefineglobaldeploymentconfigurations.NamedruntimeconfigsettingsapplytoallVMsinadeployment.

OpsManagerv2.0.0supportsdefininganynumberofruntimeconfigsinanexistingtile.Tileauthorscanalsocreateatilethatonlyincludesaruntimeconfiganddoesnotdefineanyjobtypesorerrands.

SeeManagingRuntimeConfigsformoreinformation.

On-DemandDiskandVMTypeDefaultsOn-demandservicetileshaveaconfigurationpaneforeachserviceplan.Operatorsusedrop-downmenusontheplanconfigurationpanetosettheVMtypeandpersistentdisktypeforeachinstanceofthatplan.

OpsManagerv2.0.0allowstileauthorstospecifythedefaultvaluesforVMtypesandpersistentdisktypesintheirtile’splanconfigurationpane.

SeeConfiguringDiskandVMTypeDefaultsforOn-DemandServiceTilesformoreinformation.

BOSHDNSOpsManagerv2.0.0introducesBOSHDNSasaruntimeconfigcolocatedoneveryVMinadeployment.SinceBOSHDNSisabetafeatureinPCFv2.0,operatorscanoptoutofthefeatureinthisrelease.

Tileauthorscanusethenew $director.dns_release_present accessorintilemetadatatoexposethe disable_dns_release settingontheBOSHDirector.IfanoperatorchoosestooptoutofBOSHDNS, disable_dns_release issetto true .

SeePropertyReferenceformoreinformation.

NetworkNameAccessorsOpsManagerv2.0.0addsnewaccessorstoreturnnetworkinformation,includingthenetworknameforaproductandthetop-leveldomain(TLD)oftheBOSHDirector.OpsManagerusesthesevalueswhenconstructingBOSHDNSaliases.

Thefollowingmanifestsnippetreturnsthenamesofthenetworkswheretheproductsareinstalled:

my_network_name:((.network_name))other_network_name:((..other_product.network_name))

Seethe network_name sectioninPropertyBlueprintReferenceformoreinformation.

ThefollowingmanifestsnippetreturnstheBOSHDirectorTLD:


bosh_tld:(($director.tld))

Thesnippetabovereturnsthestring bosh .

SeeDollarContextsinthePropertyBlueprintReferencetopicformoreinformation.

BOSHMetricsServerUAACredentialsPCFnowforwardsBOSHhealthmetricsgeneratedforallVMsinadeploymenttotheLoggregatorFirehosebydefault.

Tosupportthisfeature,OpsManagerv2.0.0colocatesthenewBOSHMetricsServerontheBOSHDirectorandincludesaUAAclientwiththecorrectauthoritiesandscopes.

ToaccessBOSHMetricsServerUAAcredentials,tileauthorscanusethefollowingtwoaccessors:

(( $director.bosh_metrics_forwarder_client_name )) returnsthenameoftheclient.

(( $director.bosh_metrics_forwarder_client_secret )) returnsthevalueoftheauto-generatedclientsecret.

NamedManifestsforCollection

Tileauthorscanspecifyapropertyforcollectionwithinthe named_manifest sectionoftilemetadata.Usethe current_record propertywithinacollectionrecordtorefertootherpropertiesinthesamerecord.Forexample:

-name:collection-jobtype:collectionconfigurable:trueproperty_blueprints:-name:blueprint-nametype:stringnamed_manifests:-name:example-manifestmanifest:|name:((current_record.blueprint-name.value))

Seethe named_manifest sectionoftheProductTemplateReferencetopicformoreinformation.

PivotalApplicationServiceTilePropertyChanges

PropertiesinthePivotalApplicationService(PAS)tilehavechanged.Tiledevelopersmustchangeany ((..cf.PROPERTY.NAME)) callsaccordinglyiftheirtilesaccessPASpropertyvalues.

ThefollowingtableslistthepropertiesthatPivotalremoved,added,renamed,andretypedbetweenPASv1.12andv2.0:

RemovedProperties

.diego_cell.dns_servers

.doppler.shared_secret_credentials

.properties.networking_point_of_entry

.properties.secure_diego_communication

AddedProperties

.properties.cf_networking_enable_space_developer_self_service

.properties.container_networking_interface_plugin

BreakingChange:The current_record propertyisnowreserved.Youcannolongercreateanewpropertynamed current_record .

Note:ElasticRuntimehasbeenrenamedPivotalApplicationService.


.properties.credhub_database

.properties.credhub_database.external.host

.properties.credhub_database.external.password

.properties.credhub_database.external.port

.properties.credhub_database.external.tls_ca

.properties.credhub_database.external.username

.properties.credhub_database_name

.properties.credhub_key_encryption_passwords

.properties.credhub_tls

.properties.haproxy_client_certificate

.properties.routing_custom_ca_certificates

.properties.secure_service_instance_credentials

.properties.syslog_rule

.uaa.cc_service_key_credentials

.uaa.container_networking_interface_client_credentials

.uaa.services_credhub_credentials

RenamedProperties

v1.12Name v2.0Name

.diego_cell.garden_network_mtu.properties.container_networking_interface_plugin.silk.network_mtu

.properties.container_networking_log_traffic.properties.container_networking_interface_plugin.silk.enable_log_traffic

.properties.container_networking_log_traffic.enable.iptables_accepted_udp_logs_per_sec

.properties.container_networking_interface_plugin.silk.iptables_accepted_udp_logs_per_sec

.properties.container_networking_log_traffic.enable.iptables_denied_logs_per_sec

.properties.container_networking_interface_plugin.silk.iptables_denied_logs_per_sec

.properties.container_networking_network_cidr.properties.container_networking_interface_plugin.silk.network_cidr

.properties.container_networking_vtep_port.properties.container_networking_interface_plugin.silk.vtep_port

.properties.router_forward_client_cert .properties.routing_tls_termination

.properties.routing_frontend_idle_timeout .router.frontend_idle_timeout

.push-apps-manager.accent_color .properties.push_apps_manager_accent_color

.push-apps-manager.company_name .properties.push_apps_manager_company_name

.push-apps-manager.currency_lookup .properties.push_apps_manager_currency_lookup

.push-apps-manager.display_plan_prices .properties.push_apps_manager_display_plan_prices

.push-apps-manager.enable_invitations .properties.push_apps_manager_enable_invitations

.push-apps-manager.favicon .properties.push_apps_manager_favicon

.push-apps-manager.footer_links .properties.push_apps_manager_footer_links

.push-apps-manager.footer_text .properties.push_apps_manager_footer_text

.push-apps-manager.global_wrapper_bg_color .properties.push_apps_manager_global_wrapper_bg_color

.push-apps-manager.global_wrapper_footer_content .properties.push_apps_manager_global_wrapper_footer_content

.push-apps-manager.global_wrapper_header_content .properties.push_apps_manager_global_wrapper_header_content

.push-apps-manager.global_wrapper_text_color .properties.push_apps_manager_global_wrapper_text_color

.push-apps-manager.logo .properties.push_apps_manager_logo

.push-apps-manager.marketplace_name .properties.push_apps_manager_marketplace_name

.push-apps-manager.nav_links .properties.push_apps_manager_nav_links

.push-apps-manager.product_name .properties.push_apps_manager_product_name

.push-apps-manager.square_logo .properties.push_apps_manager_square_logo


PropertiesMovedtoCredHub

PAS1.12Name CredHubName

.autoscaling.broker_credentials deploy-autoscaling-broker-credentials

.autoscaling.encryption_key deploy-autoscaling-encryption-key

.backup-prepare.backup_encryption_key backup-prepare-backup-encryption-key

.diego_database.bbs_encryption_passphrase diego-db-bbs-encryption-passphrase

.nats.credentials nats-credentials

.nfs_server.blobstore_secret nfs-server-blobstore-secret

.notifications.encryption_key deploy-notifications-encryption-key

.properties.consul_encrypt_key consul-encryption-key

.push-pivotal-account.encryption_key push-pivotal-account-encryption-key

.push-usage-service.secret_token push-usage-service-secret-token

.router.route_services_secret router-route-services-secret

ProductDependencySyntaxTileauthorscanspecifyproductversiondependenciesintilemetadatausing ~> .OpsManagerinterpretsthisoperatorbasedonthecontextinthemetadata.Forexample:

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

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

Iftheversionnumbercontainsmorethantwosegments,OpsManagerevaluates ~> forthefinalsegment.Intheexampleabove,thisincludesonlyversions 1.12.x of example-product .

ConsulVersionRequirementToensurecompatibilitywithPCFv2.0,tilesusingconsulmustupdatetoconsulagentv174orlater.ThischangesupportstheefforttotransitionfromconsultoBOSHDNSforservicediscovery.

SyslogFormattingRequirementPivotalrequiresthatPCFv2.0compatibleservicetilecomponentsemitsyslogmessagesaccordingtothestandarddocumentedinLogFormatforPCFComponents.

RequirementtoUseBOSHLinksforCredentialsandIPAddressesToensurecompatibilitywithPCFv2.0,tilesmustuseBOSHlinkstoretrieveIPaddressesandcredentialsfromothercomponents.

Forcredentials,BOSHlinksallowsyourservicetoreceivecredentialswithoutthesecurityriskofthembeingexposedintheBOSHdeploymentmanifest.

ForIPaddresses,BOSHlinksallowsyourservicetoreceiveIPaddressesassignedbyBOSHinsteadofOpsManager.ThisenablesPCFuserstodomoreautomationwithOpsManger-generatedmanifestsbecauseIPaddressmanagement(IPAM)willnotbedonebyOpsManager,removingthepotentialconflictfromchangesmadethroughautomation.

ProcedureforUsingBOSHLinks


1. Ifyouusetile-generatortobuildyourtile,updatetothelatestversionandrebuild.

2. IfyoudefineBOSHjobsinyourtile,use dynamic_ips: 1 and static_ips: 0 foreachjob.ThisusesBOSHforIPAMinsteadofOpsManager.

3. IfaBOSHreleaseinyourtileneedstheIPaddressofanothercomponent,consumeitsBOSHlink.

4. IfothercomponentsneedtheIPaddressofyourBOSHjob,provideaBOSHlink.

5. ThefollowingpropertiesarenotpresentinPCFv2.0:

..cf.doppler.shared_secret_credentials

..cf.nats.credentials.identity

..cf.nats.credentials.password

..cf.properties.consul_encrypt_key

Ifyourtileusesanyoftheseproperties,youcangetthemfromaBOSHlinkprovidedbyitsrespectivejob.Seethefollowingtable:

Property BOSHLink

.cf.doppler.shared_secret_credentials Nolongerneeded

..cf.nats.credentials.identity nats

..cf.nats.credentials.password nats

..cf.properties.consul_encrypt_key consul_common

Forimplementationdetails,refertothewith-linkexamplesinourpcf-examplesrepository andtheTileGeneratordocumentation .FormorebackgroundandcontextonBOSHlinks,seeBOSHLinks:WhyandHow andtheofficialBOSHlinksdocumentation .

UAAEndpointChangesIfyourtileusesthe /oauth/token and /check_token endpointsoftheUAAAPI,youmustensureyouareusingHTTPPOSTwithbodyinsteadofHTTPGETrequests.UsingHTTPGETisnolongersupportedasitpresentsasecurityriskduetotheaccesslogsrecordingqueryparametersandexposingtheUAAtoken.

BOSHReleases:UseSHA-2HashYoumustensurethatyourtilesignsitscomponentsusingSHA-2,asSHA-1hasbeenproveninsecure.Followthesesteps:

1. Ifyouusetile-generatortobuildyourtile,updatetothelatestversionandrebuild.

2. IfyoucreateaBOSHreleaseforyourtile,usethe --sha2 flagofthe bosh create-release command.

3. Ifyouincludethird-partyBOSHreleasesinyourtile,updatethosetonewerversionsthataresignedwithSHA-2hash.

Note:Despitethepropertynamedynamic,BOSHkeepsyourjobatthesameIPaddressunlessthatisnotpossible,suchaswhentheoperatorchangestheIPaddressrangeandthatIPaddressisnolongeravailable.


https://github.com/cloudfoundry/loggregator/releases/tag/v87

https://github.com/cloudfoundry/nats-release/blob/master/jobs/nats/spec

https://github.com/cloudfoundry/nats-release/blob/master/jobs/nats/spec

https://github.com/cloudfoundry/loggregator/releases/tag/v87

https://github.com/cf-platform-eng/pcf-examples

http://docs.pivotal.io/tiledev/tile-generator.html

https://gist.github.com/Amit-PivotalLabs/c39528248b8cdc4ba8e347f8aa68abb6

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

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 ,underboththeFormPropertiesandPropertyBlueprintssectionsofthetopic.

TileAppearance

IntheOpsManagerInstallationDashboard,yourservicetilebearsanidentifyinglabel,description,andlogoicon.Specifytheseatthetopofyour tile.yml

configurationfileas 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:


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.

DeleteaRuntimeConfigTileauthorscanremoveanexistingruntimeconfigfromatilebyremovingthereferencefromthemetadata.Whentheoperatorupgradesthetile,OpsManagerdetectsthemissingreferenceanddeletestheruntimeconfig.

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/2-0/#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.

EnhancingtheBOSHReleaseAfterthebasicBOSHreleaseisinplace,additionalfeaturesforlogginghelpoperatorsruntheservice.Forlogginginformation,seesyslog-migration-release .


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

https://github.com/pivotal-cf/syslog-migration-release

LogswrittenundertheexpectedBOSHlocation /var/vcap/sys/log areforwardedtotheconfiguredsyslogserverbytherelease.Integratingsyslogforwardingintoatileshouldnotrequirecodechanges;itonlyrequiresincludingthereleaseandconfigurationformsinthe tile.yml .Foranexample,seepcf-examples/tile-for-bosh-with-syslog .


https://github.com/cf-platform-eng/pcf-examples/tree/master/tile-for-bosh-with-syslog

ErrandsPagelastupdated:

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

FormoreinformationaboutBOSHerrands,seeBOSHdocumentation ,andformoreinformationabouterrandsinPivotalCloudFoundry(PCF),seeManagingErrandsinOpsManager .

InOpsManager2.0andlater,tileauthorscanchoosetocolocateerrandsonexistingVMs.Whenerrandsarenotcolocated,BOSHdeploysanewVMforeacherranddefinedinthetilemetadata.ColocatederrandscanrunalongsideotherjobsorerrandsonexistingVMsinanoperator’sdeployment.

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

Tosavedeploymenttime,operatorscanseterrandrunrulesthatdictatewhetherornoterrandsrun.Tileauthorscansetdefaultsfortheserunrules.

DefineaColocatedErrand

InsteadofdeployinganewVMforeacherrand,colocatederrandsrunonanexistingVM.ErrandscanrunalongsideotherjobsonaVM,andmultipleerrandscanbecolocatedonthesameVM.Colocatederrandsrunfasterthantraditionalerrandsandusefewerresources,includingdiskandIPspace.

Toconfigureacolocatederrand,definethefollowingpropertiesinthe pre_delete_errands and post_deploy_errands sectionsofthetilemetadata:

Property Description

name: MY-ERRANDProvidethenameoftheerrandjob.Theexamplemanifestinthefollowingsectionusesexample_colocated_errand .

colocated: trueSetthisvalueto true toenablecolocatederrands.Ifyoudonotsetthisvalue,OpsManagerignoresallothererrandattributesinthissection.

run_default: on

(Optional)Youcansettherunrulesto on , off ,or when-changed .SeeErrandRunRulesformoreinformation.

Ifyoudonotdefinethisproperty,OpsManagersetstherundefaultto on .TheoperatorcanoverridethissettingusingtheOpsManagerAPIorthetile’sErrandConfigtab.

instances: []

(Optional)ProvideanarraythattellsBOSHwheretoruntheerrand.Usethenameofaninstancegroup,suchas web_server ,orasingleinstance,suchas web_server/first .

Ifyoudonotdefinethispropertyoryouprovideanemptyarray,theerrandrunsoneveryinstanceofthejobintheoperator’sdeployment.

label: ERRAND-LABELDefinetheerrandnametobeshowninthetile’sErrandConfigpageandaboveApplyChanges.Theexamplemanifestinthefollowingsectionuses colocated errand on web_server .

description: TEXT (Optional)Provideadescriptionfortheerrandthatappearsinthetile’sErrandConfigpage.

Afterdefiningtheerrandinthesectionsabove,addtheerrandtothejobpropertiesinthe job_types section.

ColocatedErrandExampleManifestThefollowingexampleshowscolocated post_deploy_errands and pre_delete_errands sectionsinthetilemetadata:

Note:OpsManager2.0andlatersupportscolocatederrands.


https://bosh.io/docs/errands

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

post_deploy_errands:-name:example-errandcolocated:false-name:example_colocated_errandcolocated:truerun_default:oninstances:-web_server/firstlabel:colocatederrandonweb_serverdescription:Thiserranddoeslittlemorethanprintamessageinordertoprovecolocatederrandswork.

pre_delete_errands:-name:example-errand

Thefollowingexampleshowsthecolocatederrandsreferencedwithinthe job_type :

job_types:-name:web_serverresource_label:WebServertemplates:-name:web_serverrelease:example-releaseprovides:|web_server_info:((.properties.example_selector.selected_option.parsed_manifest(provides_section)))consumes:|web_server_info:((.properties.example_selector.selected_option.parsed_manifest(consumes_section)))-name:time_loggerrelease:example-release-name:example_colocated_errandrelease:example-releaserelease:example-releasestatic_ip:1dynamic_ip:0max_in_flight:1

BackwardCompatibilityforColocatedErrandsColocatederrandsupportisavailableinOpsManager2.0andlater.Ifyourtileusescolocatederrands,usetheinstructionsinthissectiontoensureyourtileisalsocompatiblewithOpsManager1.12andearlier.

WhenyourtilenolongerrequiresOpsManager1.12support,configureyourerrandsaseithercolocatedornon-colocated.FutureversionsofOpsManagerwillnotsupporttheworkarounddescribedinthissection.

Thefollowingexamplemanifestshowsan example_colocated_errand configuredasacolocatederrandinOpsManager2.0andasaninstancegrouperrandinOpsManager1.12:

post_deploy_errands:-name:example_colocated_errandcolocated:truerun_default:oninstances:-web_server/firstlabel:colocatederrandonweb_serverdescription:Thiserranddoeslittlemorethanprintamessageinordertoprovecolocatederrandswork....job_types:-name:example_colocated_erranddescription:Theverybestillustrativeerrandthatprintsalltheproperties,includingsecrets.templates:-name:dummyrelease:dummyerrand:true...-name:web_serverresource_label:WebServertemplates:-name:example_colocated_errandrelease:example-release

Tomakeyourtilecompatiblewithbothcolocatedandnon-colocatederrands,performthefollowingsteps:

1. ConfigureyourcolocatederrandforOpsManager2.0,asshownintheColocatedErrandExampleManifest.OpsManagerversions1.12andearlierignorethispropertyinthemanifest.


2. Inthe job_types section,definethesameerrandinthe web_server instancegroup,asshownintheexampleabove.OpsManager1.12andearlierrunstheerrandoneveryVMinthe web_server instancegroup.Ifyouwanttheerrandtorunonlyonce,configuretheerrandtorunonaninstancegroupwithonlyoneinstance.

3. Configuretheinstancegroupthatcorrespondstoyourerrand:

Set instance_definition.configurable: falseSet instance_definition.default: 0Configureatleastonenon-errandjobintheinstancegroup.OpsManagerrequireseachinstancegrouptocontainatleastonejob.

4. OpsManager1.12andearlierdisplaysthefollowingwarning,butrunstheerrandonthespecifiedinstancegroup:

Warning:Ambiguousrequest:therequestederrandname'example_colocated_errand'matchesbothajobnameandanerrandinstancegroup

Post-DeployErrandsPost-deployerrandsrunafteraproductinstalls,butbeforeOpsManagermakesitavailableforuse.

Typicalpost-installerrandsincludesmokeoracceptancetests,databaseinitializationordatabasemigration,andservicebrokerregistration.

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

Forexample,RedishasaBrokerRegistrarpost-deployerrandthattheElasticRuntimetileusestoregisteritsservicebrokerwiththeCloudControllerandpublishitsserviceplans.

IfanoperatorchoosesOffinthedrop-downmenuforElasticRuntime’sBrokerRegistrarerrandbeforeinstallation,ElasticRuntime’sservicebrokerisnotregisteredwiththeCloudControlleranditsserviceplansarenotmadepublic.

Note:Theexamplemanifestaboveusesthe dummy jobfromtheDummyBOSHrelease .Youcanuseanyno-opjob.


https://github.com/pivotal-cf-experimental/dummy-boshrelease/tree/master/jobs

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

https://docs.pivotal.io/svc-sdk/odb/


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:

BOSHCredHubisasecurecredentialmanagementcomponentthatrunsontheBOSHVMtominimizethesurfaceareawherecredentialscanbecompromised.ThistopicprovidesresourcesforconfiguringservicetilestostoretheirinternalcredentialsinBOSHCredHub,insteadofencodingtheminproducttemplateandjobtemplatefiles.

CredentialsthatservicetilesstoreinBOSHCredHubfortheirowninternalusearedistinctfromsecureserviceinstancecredentialsthatPivotalApplicationService(PAS)storesinruntimeCredHubtoenablePASappstosecurelyaccessservices.

BothBOSHCredHubandruntimeCredHubareinstancesoftheCredHubcredentialmanagementcomponent.SeetheCredHubdocumentation formoreinformation.

OverviewManyPCFcomponentsusecredentialstoauthenticateconnections,andPCFinstallationsoftenhavehundredsofactivecredentials.Securecredentialmanagementisessentialtopreventdataandsecuritybreaches.

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

SeeFetchingVariableNamesandValuesforhowtofetchvariablenamesandvaluesusingtheCredHubAPI.

CredHubCredentialTypesCredHubstoresandretrievesthefollowingtypesofcredentials:

value —singlestringvalue

json —arbitraryJSONobject

user -username

password —passwordstring

certificate —objectcontainingcertificateauthority(CA),certificate,andprivatekey

ssh —objectcontainingSSHpublickeyandprivatekey

rsa —objectcontainingRSApublickeyandprivatekey

Formoreinformation,readCredHubCredentialTypes .

ForBOSHvariabletypes,readBOSHVariableTypes .

CreatingNewVariablesTouseCredHubinyourdeployment,youmustcreatenewvariablesandstoretheminCredHub.Bydefault,variablenamespacesarewrittentopreventcollisionacrossdeployments,butyoucantypevariablenamespreciselyifyouwish.

Formoreinformation,readCreatingNewVariablesinCredHub.

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

Formoreinformation,readMigratingExistingCredentialstoCredHub.


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

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

https://bosh.io/docs/variable-types.html

FetchingVariableNamesandValuesAPIendpointsareavailabletohelpyoufindvariablenamesandvaluesforproductsknowntotheOpsManagerDirector.

Formoreinformation,readFetchingVariableNamesandValues.

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.YoucanreadaboutBOSHlinksinthev1.11ReleaseNotice .Alternatively,ifyouwanttouseanexactname,prefixingthevariablewithaforwardslash(/)willcausetheDirectortousetheexactnameyoutype.Anexampleofapreciselytypedvariablefollows.

((/EXAMPLE-PASSWORD))


https://docs.pivotal.io/tiledev/1-11/release-notes.html#bosh-links

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


SecuringServiceCredentialswithRuntimeCredHubPagelastupdated:

ThistopicdescribeshowtodevelopyourPivotalCloudFoundry(PCF)servicetiletosupportsecureserviceinstance(SSI)credentialsusingruntimeCredHub .

BackgroundWhendevelopersbindanapptoaserviceinstance,thebindingtypicallyincludesbindingcredentialsrequiredtoaccesstheservice.

InPCFv2.0andlater,servicebrokerscanstorebindingcredentialsasSSIcredentialsinruntimeCredHubandappscanretrievethesecredentialsfromCredHub.Thissecuresserviceinstancecredentialmanagementbyavoidingthefollowing:

Leakingenvironmentvariablestologs,whichincreasesriskofdisclosure.

Sendingcredentialsbetweencomponents,whichincreasesriskofdisclosure.

Requiringuserstorotatecredentialsthroughtheenvironment,whichrequirescontainerrecreation.

TostorebindingcredentialsinruntimeCredHub,yourservicetileneedstosupportthefollowing:

DiscoverthelocationofruntimeCredHub.

ProvidethisCredHublocationtothebrokerapp.TheservicebrokerusestheprovidedlocationtostorebindingcredentialsinCredHub.

EnableoperatorstoselecttheSSIcredentialsoptioninthetileUI.

DifferencebetweenSSIandInternalServiceCredentialsSSIcredentials,whichletappsaccessservicesthroughserviceinstances,aredistinctfromthecredentialsthatservicetilesstoreinBOSHCredHubfortheirowninternaluse.

WhenaserviceusesSSIcredentials,itsservicebrokerstoresthebindingcredentialsinruntimeCredHub.Then,whenPASbindsanapptoaninstanceoftheservice,thebrokerretrievesthecredentialsfromruntimeCredHubanddeliversthemtotheCloudController(CC)toenabletheapptoaccesstheservice.

TheseSSIcredentialsaredifferentfromcredentialsthatthetileusesinternally,forexample,togivetheservicebrokeraccesstoaninternaldatabase.PASgeneratestheinternaltilecredentialsforaservicewhentheserviceisfirstinstalledandstorestheminBOSHCredHub,notruntimeCredHub.

FormoreinformationontheCredHubcredentialmanagementcomponent,seetheCredHubdocumentation topic.

ThesectionsbelowdescribeanexampleimplementationofhowtoaddSSIcredentialsfunctionalitytoaservicetile.

Step1:ModifyYourBOSHReleaseTouseruntimeCredHub,yourservicetileneedstoretrievethelocationoftheCredHubserver,whichispublishedinthePivotalApplicationService(PAS)tile,throughaBOSHlink.

UpdateSpecFileandTemplatesThelocationofruntimeCredHubisstoredinthe credhub.internal_url and credhub.port propertiesofthePAStile.ToenableyourservicetiletoretrievetheseCredHub-providedproperties,adda consumes: sectionwiththeBOSHlinkfromthePAStiletothespecfileoftheBOSHjobthatwillusethemandeditthejob’stemplatestoaccessthevaluesinthelink:

consumes:-{name:credhub,type:credhub}

Note:BOSHLinksletmultiplejobssharedeployment-timeconfigurationproperties.ThishelpstoavoidredundantconfigurationsinBOSHreleasesanddeploymentmanifests.FormoreinformationaboutBOSHLinks,seeBOSHLinks .


http://docs.pivotal.io/pivotalcf/2-0/credhub/#runtime

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

http://docs.pivotal.io/tiledev/1-11/release-notes.html#bosh-links

ForinformationaboutusingBOSHLinksinthespecfileandtemplatesofajobandconsumingsharedpropertiesprovidedbyotherjobs,seeLinksinSpecFiles andLinksinTemplates .

SavetheRuntimeCredHubLocationTousetheruntimeCredHublocationretrievedfromthePAStile,youmustwritea post_deploy tileerrandthatsavesthevalueoutinsomewayandenablestheservicebrokertoaccessit.

Dependingonhowyourtiledeploystheservicebrokerapp,theserviceinstanceerrandcansavetheCredHublocationindifferentways.IfthetilepushesthebrokerasaCloudFoundryapp,theerrandcanstorethelocationinanenvironmentvariablesuchas CREDHUB_URL fortheservicebrokertocall.IfBOSHdeploystheservicebrokeroutsideofofPAS,theerrandcouldwritetheCredHublocationouttoatemplatedconfigurationfilethattheservicebrokerreads.

UpdateDeploymentManifestIntheBOSHreleaseforyourtile,editthedeploymentmanifest .yml filesothatitcontainstheBOSHlinktoCredHub:

-name:brokerrelease:my-broker-releaseconsumes:credhub:from:credhubdeployment:cf-XXXXXXXXX

FormoreinformationaboutusingBOSHlinksindeploymentmanifests,seeLinksinManifests

Step2:EnableYourTiletoFindRuntimeCredHubToenableyourservicetiletodiscoverruntimeCredHub,edityourproducttemplatesothatitconsumesthelocationofCredHub.Seethefollowingexample:

job_types:-name:JOB-NAMEresource_label:LABEL-NAMEtemplates:-name:TEMPLATE-NAMErelease:RELEASE-NAMEconsumes:|credhub:{from:credhub,deployment:"((..cf.deployment_name))"}

YoucanalsousetheaddressfromtheBOSHlinktoverifythattheCredHubserverisavailableatthataddressduringtileinstallation.Seethefollowingexample:

properties:aliases:(([email protected])):-'*.credhub.((..cf.credhub.network)).((..cf.deployment_name)).bosh'

Intheexample,theruntimeCredHubinstancecanbeaccessedat credhub.service.cf.internal .Ifyourbrokerrunsasanapp,youcanresolvethisaddresswithBOSHDNS.IfyourbrokerrunsonaVMwithaConsulagent,youcanresolvetheaddresswithConsul.Alternatively,fromaVM,youcanresolvetheaddresswith [email protected] .ThiscommandusesthePASBOSHDNSservertodolookup.

Step3:ProvideOperatorswiththeChoicetoUseCredHubToprovideoperatorswiththechoicetoselecttheSSIcredentialsoption,edityourproducttemplate.Seethefollowingexample:


http://docs.pivotal.io/tiledev/1-11/release-notes.html#bosh-links-spec

http://docs.pivotal.io/tiledev/1-11/release-notes.html#bosh-links-template

http://docs.pivotal.io/tiledev/1-11/release-notes.html#bosh-links-manifest

form_types:-name:FORM-NAMElabel:LABEL-NAMEdescription:DESCRIPTIONproperty_inputs:-reference:.JOB-NAME.secure_credentialslabel:Secureserviceinstancecredentialsdescription:"Whenchecked,serviceinstancecredentialsarestoredinCredHub.EnableonlywheninstallingwithPCFv2.0orlaterandthisfeatureisalsoenabledinthePAStile."

property_blueprints:-name:hidden_credhub_selectortype:selectorconfigurable:falsedefault:"default"option_templates:-name:default_optionselect_value:"default"named_manifests:-name:consumes_section_credhub_disabledmanifest:|credhub:nil-name:consumes_section_credhub_enabledmanifest:|credhub:{from:credhub,deployment:"((..cf.deployment_name))"}

job_types:-name:JOB-NAMEresource_label:LABEL-NAMEtemplates:-name:TEMPLATE-NAMErelease:RELEASE-NAMEconsumes:|"((secure_credentials.value?.properties.hidden_credhub_selector.selected_option.parsed_manifest(consumes_section_credhub_enabled):.properties.hidden_credhub_selector.selected_option.parsed_manifest(consumes_section_credhub_disabled)))"errand:trueresource_definitions:...property_blueprints:...-name:secure_credentialstype:booleanconfigurable:truedefault:false

Step4:StoreBindingCredentialsinRuntimeCredHubWhentheCCreceivesarequesttobindaserviceinstancetoanapp,itforwardstherequesttotheservicebroker.Theservicebrokerthenreturnsthebindingcredentialsthatallowaccesstotheservice.

ToenableyourservicebrokertostorebindingcredentialsinruntimeCredHubandmakethemSSIcredentials,dothefollowing:

1. Inyourservicebrokercode,locatewhereyourbrokerhandlesbindingrequestsfromtheCC.

2. AddcodethatauthenticatesyourservicebrokertoCredHubusingOAuth2tokensfromUAA.EachcalltotheCredHubAPImustincludeanauthorizationheader.FormoreinformationaboutCredHubauthentication,seetheAuthentication sectionoftheCredHubAPIdocumentation.

3. UpdateyourcodetostoreyourbindingcredentialsinCredHubusingtheCredHubAPIendpointforsettingthejson credentialtypewithauser-providedvalue.SeethefollowingexampleforhowtoformatyourAPIcall:

curl"https://CREDHUB.INTERNAL_URL:CREDHUB.PORT/api/v1/data"\-XPUT\-d'{"name":"/c/CLIENT-IDENTIFIER/SERVICE-IDENTIFIER/BINDING-GUID/CREDENTIAL-NAME","type":"json","value":{"uri":"SERVICE-URL","username":"USERNAME","password":"PASSWORD"}}'\-H'Content-type:application/json'

Where:

CREDHUB.INTERNAL_URL and CREDHUB.PORT aretheaddressandportofCredHub.CLIENT-IDENTIFIER isavalueprovidedbytheservicebrokertouniquelyidentifythebroker.


https://credhub-api.cfapps.io/#authentication

SERVICE-IDENTIFIER isthenameoftheserviceofferingasshownintheservicescatalog.BINDING-GUID istheGUIDcreatedbytheCCandpassedtotheservicebrokerintheservicebindingrequest.CREDENTIAL-NAME isavalueprovidedbytheservicebrokertonamethecredential.SERVICE-URL istheURLofyourservice.USERNAME and PASSWORD areyourbindingcredentials.

Forfurtherreference,seetheSetCredentials sectionoftheCredHubAPIdocumentation.

4. ModifyyourservicebrokersothatitreturnsareferencetothestoredcredentialsinresponsetothebindingrequestfromtheCC.Returnthecredentialsasasinglekey credhub-ref withitsvalueformattedas /c/CLIENT-IDENTIFIER/SERVICE-IDENTIFIER/BINDING-GUID/CREDENTIAL-NAME .Forexample,thebindingresponsemightlooklikethefollowing:

{"credentials":{"credhub-ref":"/c/example-service-broker/example-service/faa677f5-25cd-4f1e-8921-14a9d5ab48b8/credentials"}}

Note:JavaVirtualMachine(JVM)appscanuseSpringCredHub toaccesstheCredHubAPI.


https://credhub-api.cfapps.io/#set-credentials

https://projects.spring.io/spring-credhub

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.ButifyoufollowedtherecommendedstepsinBuildingYourFirstTile youwillnotneedanactualfullPCFenvironmentuntilthelaterphasesofyourdevelopment.

SettingupBOSH-LiteInstallBOSH-Lite

SettingupPCFDevTryPCFonyourLocalWorkstation

PWSorOtherSupportedCFInfrastructurePivotalWebServices(PWS)isahighly-available,production-scalePCFenvironmenthostedbyPivotal.YoucanuseittodevelopandrunPCFapps,butaPWSaccountdoesnotgiveaccesstoOpsManageranditsInstallationDashboard,whichiswherePCFoperatorsinstallandconfiguretiles.

SetUpYourPWSAccountandDownloadthecfCLI explainshowtogetstartedwithPivotalWebServices(PWS).

PCFwithOpsManager

SharedPCFDevelopmentEnvironmentsforPivotalPartnersPivotaloperatesandmanagesanumberofsharedPCFdevelopmentenvironments,calledPivotalIntegrationEnvironments(PIEs),forPivotalTechnicalPartnershipProgram(PTPP)programmemberstodeveloptheirtileson.

TouseyourassignedPIEenvironment:

1. LogintothePivotalTileDashboard usingthecredentialsthatyouuseforPivotalPartnersSlack .

2. Clickthe pie-xx environmentassignedtoyou.

3. LogintoOpsManagerwiththegivenOpsManagerURLandcredentials.

4. LogintoAppsManagerorthecfCLIwiththeCloudFoundryinformationprovidedonthesamepage.

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

https://tile-dashboard.cfapps.io/

https://pivotalpartners.slack.com/

IfyouarenotinthePTPPorcannotaccessPivotalPartnersSlack,[email protected].

InstallYourOwnPCFEnvironmentIfyouneedanisolatedordedicatedPCFdevelopmentenvironment,oryouneedtoworkoffline,youcaninstallyourownenvironmentthatincludesPivotal’sOpsManager:

InstallingPivotalCloudFoundry

OperatingPivotalCloudFoundry

UpgradingPivotalCloudFoundry

ThePTPPprogramdoesnottroubleshootpartnerinstallationsofPCFdevelopmentenvironments.



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. InstalltheTileGeneratorbydoingoneofthefollowing:

DownloadtheTileGeneratorbinaryforyourplatformfromGitHub ,andthenmakeitexecutableandavailablebyrunningthefollowingcommands:

chmod+xTILE-BINARYmvTILE-BINARY/usr/local/bin/tile

Where:TILE-BINARY isthenameofthetilebinaryfile.

Forexample:

chmod+xtile_darwin-64bitmvtile_darwin-64bit/usr/local/bin/tile

UsePython2andVirtualenv .PivotalrecommendsusingaVirtualenvenvironmenttoavoidconflictswithotherPythonpackages.

Avirtualenvisadirectorycontainingdependenciesforaproject.Whenavirtualenvironmentisactive,packagesinstallintothevirtualenvinsteadofthesystem-widePythoninstallation.

Tousethismethodrunthefollowingcommands:

virtualenv-ppython2tile-generator-envsourcetile-generator-env/bin/activatepipinstalltile-generator

Thisputsthe tile and pcf commandsinyour PATH whenthevirtualenvisactive.Todeactivatethevirtualenv,runthecommand deactivate .

2. InstalltheBOSHCLI .

3. Fromwithintherootdirectoryoftheprojectforwhichyouwanttocreateatile,initializethedirectoryasatilerepositorybyrunningthefollowingcommands:

cdYOUR-PROD-DIRECTORYtileinit

4. Editthegenerated tile.yml filetodefineyourtile.

5. Buildyourtilebyrunning:

tilebuild

ThegeneratorfirstcreatesaBOSHreleaseinthe release subdirectory,thenwrapsthatreleaseintoaPivotaltile,inthe product subdirectory.Ifrequiredfortheinstallation,itautomaticallypullsdownthelatestreleaseversionoftheCloudFoundryCLI.

TileGeneratorisalsoavailablepre-installedinaDockerimageonDockerHub .Thisimagecontainsthetile-generator tile and pcf commands,thenecessaryPythondependenciesandtheBOSHCLI.

YoucanusethisinConcoursepipelinesbyspecifyingitasthebaseimageforyourtasks:

Note:ToupgradeTileGenerator,run pipinstalltile-generator--upgrade withthevirtualenvactivated.

Note:Pivotalrecommendsthatyouuseagitrepository.


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

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

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

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

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

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

Or,youcanderiveyourownDockerimagesfromthisonebyusingitasthebaseimageinyourDockerfile:

FROMcfplatformeng/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 manifest

instead.

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 :



-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,addthefollowingsectionatthetoplevelofyour tile.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

...


ContinuousIntegrationTestingPagelastupdated:

ThistopicexplainshowtousetheTileDashboard continuousintegration(CI)systemanditsunderlyingConcourse platformtohelpdevelopandintegratesoftwareservicesforPivotalCloudFoundry(PCF).

TileDashboardCIWithyourtileinourTileDashboardcontinuousintegrationtestingsystem,weallwin.YoustayontopofchangestoPCFthatmayrequirechangesinyourtile.Ourfieldrepresentativesgainaclearunderstandingofyourtile’scompatibilityacrossPCFversions,underlyingIaaS,anddifferentflavorsofenvironments.ThisalsorelievesyoufrommaintainingyourownCIsystem,keepingupwithlatestPCFversions,etc.Further,theTileDashboardCIispartofourEnterpriseReadinesscriteria ,whichisusedtoinformthefieldofthequalityandcapabilitiesofyourtile,soitisimportanttogetyourtileperformingwell.

TileDashboardStepsTileDashboardrunsyourtilethroughaseriesofsteps,whichinclude:

DownloadyourtilefromPivNetandcheckhashintegrity.

Scanyourtileforknownissuesorpotentialproblems,like:

Useofdeprecatedproperties.Useofpropertieswhosevalues/meaningshavechanged.Useoffeaturesthatarenolongersupported.

Configure,install,test,anduninstallyourtileinseveralPCFenvironments:

ApatchreleaseofeverysupportedERT/PASminorversion.EverysupportedIaaS.Environmentswithextraconfiguration(e.g.,multipleavailabilityzones,IPsec).

TileDashboardreportstheresultsofeachstep.Theresultsreportforeachstepincludesageneralpass/failstatus,theexecutionlog,andoutput.Ifatestfailedforareasonunrelatedtoatile(e.g.,anetworkglitch),youcanretrythestepfromTileDashboard.

WhatPivotalNeedsfromYouTointegrateyourtilewithTileDashboard CI,Pivotalneedsyoutouploadorsendthefollowing:

Yourpre-releasetile

Yourtile’sconfigurationparameters

Oneormoretestconfigurations

Anybackingservicesthatthetilerequires

Theserequirementsarediscussedbelow.

UploadedTile

Ifthisisyourfirsttile,MarinaorJakecanuploadpre-releasesofyourproduct.TileDashboardwillthenpickupthosepre-releasesandrunthemthroughCI.

Afterthefirstreleaseofyourtile,theadminforyourtilecancontinuetouploadnewpre-releasesforfutureversionstonetwork.pivotal.io.

TileConfigurationParameters

Toautomatetheinstallationofyourtile,weneedtheconfigurationparameterstheoperatorwouldenterintoOpsManagerforms.TileDashboardincludesaninterfaceforyoutoenterthisconfigurationdirectlyforproperties,intheformatusedbytheomtool .Clickonyourtile’sslug,thenclickthe


https://tile-dashboard.cfapps.io/static/index.html#/environments

http://concourse.ci

https://docs.google.com/presentation/d/1Z05EuIB11cLejldShVTffprzBulZxiL8MTVxrfPbvT0

https://tile-dashboard.cfapps.io/static/index.html#/environments

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

“Configure”linknearthetopofthescreen,andyoucanenterthefollowinginformation:

Properties:Configureyourtile’sproperties,ifnecessary,usingtheJSONproductpropertiesformatusedbyom .(Note:thisisthesameformatusedbytheOperationsManagerproductpropertiesAPI.)

UAAUsers:IncludealistofUAAuserstousefortestingyourtile.TheformatisaJSONarray,withthespecificformatdescribedontheconfigurationpage.

TestConfiguration

Afteryourtileisinstalled,TileDashboardwillrunanypost-deployerrandsyourtilehasdefined,includingtests.Ideallyyourtilewillincludeteststhatexerciseallofitsfunctionality.WehavesomeideasforexpandingtheTileDashboardtestingcapabilities;ifyou’reinterestedinotherwaysofdefiningtests,pleasereachouttousonPivotalPartnersSlack .

BackingServices

IfyourtilerequiresabackingserviceoutsideoftheexistingPCFenvironment(e.g.,yourtileisaservicebrokertoaSaaSoffering),youareresponsibleformaintainingthebackingserviceinanenvironmentthattheTileDashboardcanreach(i.e.,itmustbeinternet-facing).

ConcourseTheTileDashboardCIthatPivotalrunsforitstechnicalpartnershipprogrammembersusestheCItoolConcourse tomakesurethatpartnerproductscontinuetoworkwitheverynewreleaseoftheplatform.

Withmoreeffort,youcanalsofollowthepointersbelowtosetupyourownConcourseCIpipelinethatintegratesandtestsyourtileonyourowndeploymentofthelatestPCF.

WhileyouareofcoursealsofreetouseanyotherCIsystemyouarefamiliarwith,Pivotal’stoolsanddocumentationarebuilttomakeConcourseCIaseasyaspossible.

SetUpaConcourseServerYouneedaConcourseservertohostyourpipeline.

IfyoupartnerwithPivotal,theTileDashboardCIserverscanhostyourpipelineandprovideS3storagetoexchangeartifactswithyourownservers.

IfyouchoosetosetupyourownConcourseserver,seetheinstructionsConcourse:Setup&Operations .

CreateaConcoursePipelineforYourTileAtypicalCIpipelineforatileconsistsofthefollowingjobs:

Buildthetile

DeployittoPCF

Runasetofdeploymentteststoverifythatitdeployedandworkscorrectly

RemoveitfromPCF

Youdescribethispipelineina pipeline.yml filethatisthenuploadedtotheConcourseserver.TileGeneratorcontainsasamplepipelinethatyoucancloneforyourowntile.Weareworkingonautomatingtheprocessofgeneratingapipelinetemplateforyou.

SetUpPCFforYourCIPipelinePivotalpartnerswhohaveushosttheirpipelinehaveaccesstoapoolofPCFinstancesthataremanagedbyusandareregularlyupdatedwiththelatest(pre-)releaseversionsofPCF.Ifyousetupyourownconcourseserver,youwillhavetotargetyourpipelineataPCFinstanceyouhavesetup.

Concoursehasaresourcetypetomanageapoolofresourcesthataresharedbetweenpipelines,whichiswhatweusetoserializePCFaccessbetweenthepartnerpipelinesthatrunonourconcourseserver.


https://github.com/pivotal-cf/om/blob/master/docs/configure-product/README.md#configuring-the---product-properties

https://pivotalpartners.slack.com/

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.

Feedback

Pleaseprovideanybugs,featurerequests,orquestionstothePivotalCloudFoundryFeedbacklist.

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

InstallUsingthePivotalOpsManagerDownloadtheproductfilefromPivotalNetwork.

UploadtheproductfiletoyourOpsManagerinstallation.

ClickAddnexttotheuploadedproductdescriptionintheOpsManagerAvailableProductsviewtoaddthisproducttoyourstagingarea.

Clickthenewlyaddedtiletoreviewanyconfigurableoptions.

ClickApplyChangestoinstalltheservice.

UpgradingtotheLatestVersion

Ifthereareanyspecificinstructionsforupgradingthetile,youcanincludethosehere.Iftheproceduresarecomplicated,createanewUpgradingtopic.

ConfiguringthePartnerTile

Addsnapshotsforeachstepwhenpossibleoradddetailsasrequired.

LogintoPivotalOpsManager.

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’srecommendedtiledevelopmentworkflowinBuildingYourFirstTile .

DevelopmentWorkflowThefollowingtopicscanhelpyoulearnthenecessarybackgroundinformationtopublishandmaintainafinishedtileproduct:


TileBasicsdescribeshowPCF,servicebrokers,andtilesworktogether,andhowtilesarestructured.

TypesofIntergrationsgivesahigh-levelviewofastagedtiledevelopmentprocessthatiteratesthroughincreasinglevelsofintegration:

User-ProvidedServiceBrokeredServiceManagedServiceOn-DemandService

DevelopmentEnvironmentsdescribeshowtosetupdevelopmentenvironmentsfordifferentstagesandlevelsinthetiledevelopmentprocess.

DevelopmentToolsdescribesthreetoolsthatstreamlinethetiledevelopmentprocess:TileGenerator,thepcfCommandLineutility,andConcoursecontinuousintegration(CI).

TileDocumentationexplainshowtodocumentyourtileaspartofPCFdocumentation .

PublishandUpdateexplainshowtopublishyourtileonPivotalNetwork (PivNet)andpackageupgradeinformationintoyournewversions.

ReferenceprovideslanguagereferencesfortileelementssuchastheServiceBrokerAPIandthePropertieslistfortileconfiguration.

ContactUslistscontactstolearnmoreaboutthePivotalISVPartnerProgramorrequestourassistancewithyourintegrationproject,andexplainswhereyoucancontributetothisdocumentation.



https://docs.pivotal.io/tiledev/2-0/

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" pivnet_filename_regex: "/product-.*\.pivotal$" 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(/^example-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.0 minimum_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.

pivnet_filename_regexString.Optional.ThisregularexpressionallowsOpsManager’sPivotalNetworkintegrationtopullaspecificproductfile.Youmustdothiswhentherearemultipleproductswithinthesameproductslug.

service_brokerBoolean.Optional,default false .Set service_broker to true foron-demandservicebrokers.Setting service_broker to true doesthefollowing:

Enablestheservicenetworkselectorpropertytype

Requirestheoperatortoselectaservicenetworkduringtileconfiguration.Tileauthorscanreferencetheselectedservicenetworkwith(( $self.service_network )) .

IncludesaUAAclientfortheservicetouse.TileauthorscanreferencetheUAAclientcredentialswith (( $self.uaa_client_name )) and(( $self.uaa_client_secret )) .

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_criteriaos: ubuntu-trustyversion: <%= stemcell_version.inspect %>enable_patch_security_updates: true


https://bosh.io/

Thisfeatureincreasessecuritybyautomaticallyusingthelatestpatchedversionofastemcell.However,operatorsmayexperiencelongerthanexpectedupgradetimes.Formoreinformation,seeUnderstandingFloatingStemcells .

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

Eachreleaserequiresthefollowingkeys:

name

file

version

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.

FormPropertiesEachformtypeyouwriteiscomposedofformproperties.FormpropertiesrepresenttheoutlinetotheformfieldsthatappearintheOpsManagerUI.Thename ofeachformappearsontheleft-handsideasnavigationaltabs.

Formpropertiesreference property_blueprints .Propertyblueprintsdefineeachfield’sdatatype.Foracorrespondingexampletothe form_types examplebelow,seeproperty_blueprints.

Thefollowingisanexampleofthepropertiesthatappearinthe form_types sectionofaproducttemplate:


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

form_types: - name: example-form label: Configurable Properties description: All the properties that you can configure! markdown: | ## Example markdown text

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

Things to do:

1. Learn [markdown](https://daringfireball.net/projects/markdown/). 1. ... 1. Profit! property_inputs: - reference: .web_server.example_string label: Example string description: 'Configure a property of type string' - reference: .web_server.example_string_with_placeholder label: Example string containing Placeholder text description: 'Optional field. Configuration not necessary' placeholder: 'Ghost text. Spooky!' - reference: .web_server.example_migrated_integer label: Example integer description: 'Configure a property of type integer' - reference: .web_server.example_boolean label: Example boolean description: 'Configure a property of type boolean' - reference: .web_server.example_dropdown label: Example dropdown description: 'Configure a property of type dropdown' - reference: .web_server.example_domain label: Example domain description: 'Configure a property of type domain' - reference: .web_server.example_wildcard_domain label: Example wildcard_domain description: 'Configure a property of type wildcard_domain' - reference: .web_server.example_string_list label: Example string_list description: 'Configure a property of type string_list' - reference: .web_server.example_text label: Example text description: 'Configure a property of type text (setting to "magic value" causes the web server job instance count to go to 0)' - reference: .web_server.example_ldap_url label: Example ldap_url description: 'Configure a property of type ldap_url' - reference: .web_server.example_email label: Example email description: 'Configure a property of type email' - reference: .web_server.example_http_url label: Example http_url description: 'Configure a property of type http_url' - reference: .web_server.example_ip_address label: Example ip_address description: 'Configure a property of type ip_address' - reference: .web_server.example_ip_ranges label: Example ip_ranges description: 'Configure a property of type ip_ranges' - reference: .web_server.example_multi_select_options label: Example multi_select_options description: 'Configure a property of type multi_select_options' - reference: .web_server.example_network_address_list label: Example network_address_list description: 'Configure a property of type network_address_list (this property was marked with freeze_on_deploy, and so will not be editable after changes are first applied)' - reference: .web_server.example_network_address label: Example network_address description: 'Configure a property of type network_address' - reference: .web_server.example_port label: Example port description: 'Configure a property of type port' - reference: .web_server.example_smtp_authentication label: Example smtp_authentication description: 'Configure a property of type smtp_authentication' - reference: .web_server.client_certificate label: Example certificate description: 'Configure a certificate' verifiers: - name: Verifiers::WildcardDomainVerifier properties: domain: .web_server.example_wildcard_domain - name: Verifiers::StaticIpsVerifier properties: domain: .web_server.example_ip_address

nameString.Required.Theinternalnameoftheform.

labelString.Required.Thelabeloftheformasitappearsasalinkonthelefthandsideofeachform.

descriptionString.Optional.Thedescriptionoftheform.Appearsatthetopoftheformasaheader.

markdownMarkdown.Optional.Provideablockofmarkdowntodisplayatthetopoftheform.Includesimagesupport.Youcanusethispropertytodocumentthetileandprovideexplanationsorreferences.

property_inputsArrayofHashes.Required.Referencestopropertiesdefinedintheproperty_blueprintssectionoftheproducttemplate.

verifiersVerifiersreachoutandfindobjectsintheworld.Forexample,givenanIP,averifiercanpingtheIPtoseethatitresponds.

Verifiersareseparatefromvalidators,whichcheckwhetherastringisformattedproperly.Foranexampleofavalidator,seemust_match_regex.

Seethefollowingforalistofavailableverifiersyoucanuse:

BlobstoreVerifier

LDAPBindVerifier

MysqlDatabaseVerifier

SmtpAuthenticationVerifier


SsoUrlVerifier

StaticIpsVerifier

WildcardDomainVerifier

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.

Theexampleisreferencedbytheformpropertiesexampleabove.SeeFormProperties.


- name: web_server ... property_blueprints: - name: property_with_nil_value type: string - name: property_with_false_value type: boolean configurable: false default: false - name: property_with_true_value type: boolean configurable: false default: true - name: static_ips configurable: true optional: true - name: generated_secret type: secret - name: generated_uuid type: uuid - name: configured_secret type: secret configurable: true optional: true - name: configured_simple_credentials type: simple_credentials configurable: true optional: true - name: configured_rsa_cert_credentials type: rsa_cert_credentials configurable: true optional: true - name: example_string_with_placeholder type: string configurable: true optional: true placeholder: 'Configure me!' - name: example_string type: string configurable: true default: 'Hello world' constraints: - must_match_regex: '\A[^!@#$%^&*()]*\z' error_message: 'This name cannot contain special characters.' - must_match_regex: '\A[^0-9]*\z' error_message: 'This name cannot contain digits.' - name: example_migrated_integer type: integer configurable: true default: 1 - name: example_boolean type: boolean configurable: true default: true - name: example_dropdown type: dropdown_select configurable: true default: kiwi options: - name: kiwi label: 'label for kiwi' - name: lime label: 'label for lime' - name: avocado label: 'label for avocado' - name: example_domain type: domain configurable: true default: www.example.com - name: example_wildcard_domain type: wildcard_domain configurable: true default: 'example.com' - name: example_string_list type: string_list configurable: true default: 'a,list,of,strings' - name: example_text type: text configurable: true default: 'some_text' - name: example_ldap_url type: ldap_url configurable: true

configurableNopropertywillbeviewableinaformunless 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(AlsoConfigurable)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.

Note:StartinginPCFv2.1,OpsManagerignores static_ip and dynamic_ip keys.


job_types: - name: web_server resource_label: Web Server templates: - name: web_server release: example-release - name: time_logger release: example-release release: example-release static_ip: 1 dynamic_ip: 0 max_in_flight: 1 single_az_only: true: instance_definition: name: instances type: integer configurable: true default: 1 constraints: max: 1 zero_if: property_reference: '.web_server.example_text' property_value: 'magic value' resource_definitions: - name: ram type: integer configurable: true default: 1024 - name: ephemeral_disk type: integer configurable: true default: 2048 - name: persistent_disk type: integer configurable: true default: 1024 constraints: min: 1024 - name: cpu type: integer configurable: true default: 1 property_blueprints: - name: static_ips type: ip_ranges configurable: true optional: true - name: generated_rsa_cert_credentials type: rsa_cert_credentials - name: generated_rsa_pkey_credentials type: rsa_pkey_credentials - name: generated_salted_credentials type: salted_credentials - name: generated_simple_credentials type: simple_credentials - name: generated_secret type: secret - name: generated_uuid type: uuid - name: example_string_with_placeholder type: string configurable: true optional: true placeholder: 'Configure me!' - name: example_string type: string configurable: true default: 'Hello world' constraints: - must_match_regex: '^[^!@#$%^&*()]*$' error_message: 'This name cannot contain capital digits.' - must_match_regex: '^[^0-9]*$' error_message: 'This name cannot contain digits.' - name: example_migrated_integer type: integer configurable: true default: 1 - name: example_boolean type: boolean configurable: true default: true - name: example_dropdown type: dropdown_select configurable: true

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.

release




https://bosh.io/

String.Required.ThenameoftheBOSHreleasecontainedinyourproductarchive(.pivotalfile).

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

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 )))-suffix password: ((( credhub-password )))

warning:Ifyouchangethe single_az_only setting,yourVMsmayswitchAZs.Thischangecancauseanorphaneddisk.

Note:Ifyousetthe default propertyfor persistent_disk to 0 ,userscannoteditthisvalueandtheResourceConfigpageinOpsManangerdisplaysNoneunderthepersistentdiskfield.


OpsManagerstripstheouterparenthesesfromtheseexpressionsandincludestheresultingdouble-parensexpressionsinthemanifestitgenerates,forBOSHtoevaluateatdeploytime.

named_manifestSpecifyapropertyforcollectionwithinthe named_manifest sectionofthemetadata.SeetheSimplevs.ComplexInputssectionformoreinformationaboutcollections.

Thefollowingexampleusesanamedmanifestcalled for_routing thatbelongstothe certificate_collection job:

- name: certificate_collection type: collection configurable: true property_blueprints: - name: some_cert_name type: string - name: some_cert type: rsa_cert_credentials named_manifests: - name: for_routing manifest: | name: (( current_record.some_cert_name.value )) private_key: (( current_record.some_cert.private_key_pem )) public_key: (( current_record.some_cert.public_key_pem )) certificate: (( current_record.some_cert.cert_pem ))

Usethe current_record propertywithinacollectionrecordtorefertootherpropertiesinthesamerecord.Forexample,thepropertiesinthe for_routingnamedmanifestrefertothevaluesfor name , private_key , public_key ,and certificate withinthisrecordonly.

Afterdefininganamedmanifest,youcanreferenceitusingamanifestsnippetinthefollowingformat:

routing_certificates:((.properties.certificate_collection.parsed_manifest(for_routing)))

OpsManagerrendersthefollowingmanifestfromthisexample:

routing_certificates: - name: foo_cert private_key: PRIVATE-KEY public_key: PUBLIC-KEY certificate: CERTIFICATE - name: bar_cert private_key: PRIVATE-KEY public_key: PUBLIC-KEY certificate: CERTIFICATE

SelectorManifestSnippetsSelectorsnippetsareevaluatedtwice.Asyousawinthe property_blueprint ,theselectorhasamanifestsnippetforbothsetsofinputsthattheusermightchoose.Onlyoneofthesesetsisevaluatedandinsertedintothejob’smanifest.

OpsManagerProvidedSnippetsThefollowingdouble-parensaccessorsretrieveyourjobproperties:

name: (( name ))

ram: (( ram ))

ephemeral_disk: (( ephemeral_disk ))

persistent_disk: (( persistent_disk ))

Note:The current_record propertyisreserved.Youcannotcreateanewpropertynamed current_record .


instances: (( instances ))

availability_zone: (( availability_zone )) (deprecated)

bosh_job_partition_stats: (( bosh_job_partition_stats )) (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

Note:AsofPCFv2.1,IPaccessorsarenolongersupported.


$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||[]))


DollarContextsOutsideofproperties,youcanalsoretrieveinformationaboutvariousconfigurationdetailsofyourproductandOpsManager.

$ops_manager:usedbyanyproducttoobtaininformationaboutspecificOpsManager

$director:usedbyanyproducttoobtaininformationabouttheDirector

$self:usedbyyourownproducttoobtaininformationaboutyourproduct’sconfiguration

$ops_manager

ca_certificate ProvidestherootCAcertthatisusedtosigntheDirectorVM

trusted_certificates ProvidesalistofcertificatesthatareappliedbytheDirectortoallVMs

http_proxy ProvidesthecommaseparatedvaluesthatareenteredifOpsManagertrafficisdirectedtoanHTTPProxy

https_proxy ProvidesthecommaseparatedvaluesthatareenteredifOpsManagertrafficisdirectedtoanHTTPSProxy

no_proxy Providesthecommaseparatedvaluesthatshouldnotgothroughaproxy

$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

dns_release_present ExposestheDirectorconfigurationfor disable_dns_release

$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

PCF Tile Developer Guide v2Note: PCF Tile Developer Guide v2.0 is not designed for use with the...

Documents

Transcript of PCF Tile Developer Guide v2Note: PCF Tile Developer Guide v2.0 is not designed for use with the...