PCF Tile Developer Guide v2.0

PCF v2.0 Partners Release Notice

Page last updated:

This topic describes the changes that Pivotal Cloud Foundry (PCF) v2.0 introduces which may be relevant to partner service tiles.

Colocated Errands

Tile authors can configure the errands defined in their product tile to run on existing virtual machines (VMs) in a deployment. Colocated errands run faster than traditional errands and use fewer resources, including disk and IP space.

See Tile Errands for more information.

Runtime Configs

Tile authors can include runtime_configs as a top-level key in tile metadata to define global deployment configurations. Named runtime config settings apply to all VMs in a deployment.

Ops Manager v2.0.0 supports defining any number of runtime configs in an existing tile. Tile authors can also create a tile that only includes a runtime config and does not define any job types or errands.

See Managing Runtime Configs for more information.

On-Demand Disk and VM Type Defaults

On-demand service tiles have a configuration pane for each service plan. Operators use drop-down menus on the plan configuration pane to set the VM type and persistent disk type for each instance of that plan.

Ops Manager v2.0.0 allows tile authors to specify the default values for VM types and persistent disk types in their tile’s plan configuration pane.

See Configuring Disk and VM Type Defaults for On-Demand Service Tiles for more information.


Ops Manager v2.0.0 introduces BOSH DNS as a runtime config colocated on every VM in a deployment. Since BOSH DNS is a beta feature in PCF v2.0, operators can opt out of the feature in this release.

Tile authors can use the new $director.dns_release_present accessor in tile metadata to expose the disable_dns_release setting on the BOSH Director. If an operator chooses to opt out of BOSH DNS, disable_dns_release is set to true.

See Property Reference for more information.

Network Name Accessors

Ops Manager v2.0.0 adds new accessors to return network information, including the network name for a product and the top-level domain (TLD) of the BOSH Director. Ops Manager uses these values when constructing BOSH DNS aliases.

The following manifest snippet returns the names of the networks where the products are installed:

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

See the network_name section in Property Blueprint Reference for more information.

The following manifest snippet returns the BOSH Director TLD:

bosh_tld: (( $director.tld ))

The snippet above returns the string bosh.

See Dollar Contexts in the Property Blueprint Reference topic for more information.

BOSH Metrics Server UAA Credentials

PCF now forwards BOSH health metrics generated for all VMs in a deployment to the Loggregator Firehose by default.

To support this feature, Ops Manager v2.0.0 colocates the new BOSH Metrics Server on the BOSH Director and includes a UAA client with the correct authorities and scopes.

To access BOSH Metrics Server UAA credentials, tile authors can use the following two accessors:

  • (( $director.bosh_metrics_forwarder_client_name )) returns the name of the client.
  • (( $director.bosh_metrics_forwarder_client_secret )) returns the value of the auto-generated client secret.

Named Manifests for Collection

Breaking Change: The current_record property is now reserved. You can no longer create a new property named current_record.

Tile authors can specify a property for collection within the named_manifest section of tile metadata. Use the current_record property within a collection record to refer to other properties in the same record. For example:

  - name: collection-job
    type: collection
    configurable: true
      - name: blueprint-name
        type: string
    - name: example-manifest
      manifest: |
        name:  (( current_record.blueprint-name.value ))

See the named_manifest section of the Product Template Reference topic for more information.

Pivotal Application Service Tile Property Changes

Note: Elastic Runtime has been renamed Pivotal Application Service.

Properties in the Pivotal Application Service (PAS) tile have changed. Tile developers must change any (( )) calls accordingly if their tiles access PAS property values.

The following tables list the properties that Pivotal removed, added, renamed, and retyped between PAS v1.12 and v2.0:

Removed Properties
Added Properties
Renamed Properties
v1.12 Namev2.0 Name
Properties Moved to CredHub
PAS 1.12 NameCredHub Name

Product Dependency Syntax

Tile authors can specify product version dependencies in tile metadata using ~>. Ops Manager interprets this operator based on the context in the metadata. For example:

- name: cf
  version: "~> 1.8"
- name: example-product
  version: "~> 1.12.1"

If the version number contains only two segments, Ops Manager interprets ~> as >=. In the example above, this includes all versions of cf later than 1.8.

If the version number contains more than two segments, Ops Manager evaluates ~> for the final segment. In the example above, this includes only versions 1.12.x of example-product.

Consul Version Requirement

To ensure compatibility with PCF v2.0, tiles using consul must update to consul agent v174 or later. This change supports the effort to transition from consul to BOSH DNS for service discovery.

Syslog Formatting Requirement

Pivotal requires that PCF v2.0 compatible service tile components emit syslog messages according to the standard documented in Log Format for PCF Components.

To ensure compatibility with PCF v2.0, tiles must use BOSH links to retrieve IP addresses and credentials from other components.

  • For credentials, BOSH links allows your service to receive credentials without the security risk of them being exposed in the BOSH deployment manifest.
  • For IP addresses, BOSH links allows your service to receive IP addresses assigned by BOSH instead of Ops Manager. This enables PCF users to do more automation with Ops Manger-generated manifests because IP address management (IPAM) will not be done by Ops Manager, removing the potential conflict from changes made through automation.
  1. If you use tile-generator to build your tile, update to the latest version and rebuild.
  2. If you define BOSH jobs in your tile, use dynamic_ips: 1 and static_ips: 0 for each job. This uses BOSH for IPAM instead of Ops Manager.

    Note: Despite the property name dynamic, BOSH keeps your job at the same IP address unless that is not possible, such as when the operator changes the IP address range and that IP address is no longer available.

  3. If a BOSH release in your tile needs the IP address of another component, consume its BOSH link.
  4. If other components need the IP address of your BOSH job, provide a BOSH link.
  5. The following properties are not present in PCF v2.0:

      If your tile uses any of these properties, you can get them from a BOSH link provided by its respective job. See the following table:
      Property BOSH Link
      .cf.doppler.shared_secret_credentials No longer needed nats nats consul_common

      For implementation details, refer to the with-link examples in our pcf-examples repository and the Tile Generator documentation. For more background and context on BOSH links, see BOSH Links: Why and How and the official BOSH links documentation.

UAA Endpoint Changes

If your tile uses the /oauth/token and /check_token endpoints of the UAA API, you must ensure you are using HTTP POST with body instead of HTTP GET requests. Using HTTP GET is no longer supported as it presents a security risk due to the access logs recording query parameters and exposing the UAA token.

BOSH Releases: Use SHA-2 Hash

You must ensure that your tile signs its components using SHA-2, as SHA-1 has been proven insecure. Follow these steps:

  1. If you use tile-generator to build your tile, update to the latest version and rebuild.
  2. If you create a BOSH release for your tile, use the --sha2 flag of the bosh create-release command.
  3. If you include third-party BOSH releases in your tile, update those to newer versions that are signed with SHA-2 hash.
Create a pull request or raise an issue on the source for this page in GitHub