PCF Tile Developers Guide v1.12

PCF v1.7 Partners Release Notice

Note: In April 2016, prior to the release of Pivotal Cloud Foundry (PCF) 1.7, a version of this notice was emailed to PCF partners.

As you may be aware, a feature release of Ops Manager and Elastic Runtime is approaching for Pivotal Cloud Foundry (1.7). We’re currently targeting the middle of April to make the release available for customers, and we would like to make sure your products are all compatible with the changes that these releases will introduce. Below we’re going to list out some analysis and actions for you to perform with your product(s). Going through all of these “chores” in a timely manner will ensure that we are healthy for the release.

There are several changes to how Services integrate with Ops Manager. Broadly, these changes are necessary for your product to take advantage of Ops Manager features being released with 1.7. In one specific case, changes are required in your migrations in order to be upgradeable within 1.7 or greater Ops Manager.

Product Template Changes

  • The double parens value of “Singleton Jobs” has been removed from Ops Manager in 1.7. As part of your product’s integration work required for 1.7, there is a new property to peg instances to a single AZ. You will need to ensure that any product release you wish to be able to upgrade to within Ops Manager 1.7 or greater contain a migration from any singleton job(s) to the new boolean property single_az_only: true | false. This impacts products that want to go to the 1.7 metadata schema in Ops Manager to take advantage of multi-AZ. They will need to replace singleton jobs with the new double parens value. Note that you don’t need a migration for this - OM will do that for you. See the Job Types section of the Product Template Reference topic for details.

    WARNING: Changing the value ofsingle_az_only can cause data loss for customers who upgrade to Ops Manager v1.7 versions older than v1.7.19. Contact Pivotal Support for help avoiding this.

  • Ops Manager 1.7 ships with a new multi-AZ functionality that results in multiple networks. There is no longer a default network, and Ops Manager will not look for one. Check your tile and BOSH release, if you have one, to make sure there are no network: default property settings.

    Note: Pivotal recommends partners follow instructions about troubleshooting IP values for network properties to make the necessary updates to their tile for use with Ops Manager 1.7.

  • With 1.7 Ops Manager, Product Templates will allow the ability to “float” their stemcell references against a major stemcell version. This will allow minor / patch stemcell updates to take place without the need for a re-publishing your product with a new direct reference. All products will use floating stemcell references by default, and you will need to opt-out of that if you want to tie your tile to a specific stemcell minor / patch version.

  • Each minor release of Ops Manager will start with a 1st number stemcell, and throughout the course of the release, as patches are applied, they will increment a second number, e.g. 1234.1, 1234.2, etc. Your tile will be able to reference the first digit and highest-numbered minor version of the stemcell, and all subsequent minor versions will be respected by your tile unless you reference a specific stemcell to be tied to (in the product template), as you might in the case of statically compiled packages. If you wish to opt out of floating stemcell references, you need to introduce a key value pair (enable_patch_security_updates: false) to the stemcells section of the product template (such as a case in which your product tile release requires a specific version of a stemcell). This will default to true even if the key value pair is not present. See the Top Level Properties section of the Product Template Reference topic for details.

Troubleshoot IP Values for Network Properties in Ops Man 1.7


Job templates inside of BOSH releases occasionally require the IP of the VM on which they run. VMs can have multiple IPs because they might be multi-homed or have virtual IPs, such as an AWS EIP.


Pivotal recommends specifying the IP for spec.networks in your manifest from the IP of the first network interface that has a default gateway attached to it. This approach solves the problem of finding the correct IP for multiple networks because you cannot have multiple interfaces associated with a gateway. Use the following code in your template ERBs to return the appropriate value.

def discover_external_ip
    networks = spec.networks.marshal_dump

    _, network = networks.find do |_name, network_spec|

    if !network
        _, network = networks.first

    if !network
        raise "Could not determine IP via network spec: #{networks}"

    job_ip = network.ip

For a production example of the implementation of this technique in cf-release, see the following commit:


Some BOSH releases that were designed to be deployed with Ops Manager supplied “default” for the value of the network property in a deployment, based on the incorrect assumption that there would only be one network for a deployment. Below are several examples from past template ERB files that supplied job IP values. These approaches worked for Ops Manager 1.6 and prior versions, but they will fail in a deployment with multiple networks on Ops Manager 1.7:

    <% job_ip = spec.networks.default.ip %>
    <% job_ip = spec.networks.first.ip %>
    <% job_ip = spec.networks.send(spec.networks.methods(false).first).ip %>

Migration Changes

  • Going forward, you will need to write Javascript migrations for any releases you wish to upgrade to within Ops Manager 1.7. Products with the older-style migrations will still import and operate correctly within 1.7 upon Ops Manager upgrade. Ops Manager 1.7 introduces a new Javascript-based syntax for tile migrations (The phrase “tile migration” refers to changing the name or value of a property in your product tile when a user upgrades your tile). Migrations will now be performed by author-supplied Javascript functions that take in a tile and return a hash of your tile’s properties. Moreover, migrations will be “chaining,” i.e., a user upgrading from version A to C of your product will trigger migration A→B and then B→C. We recommend that, within the 1.7 release timeframe, you produce and release a patch release of your current product that includes a Javascript migration as well as the existing older syntax in order to account for upgrades within either 1.6 or 1.7 Ops Manager. Both migration styles can be used in the same tile release. See the Migrating Tile Versions topic for JavaScript-based migration instructions.

    Note: This is only necessary for your next release after 1.7 Ops Manager is released.

  • To stop a migration from happening you have two options. One is you can exit from the Javascript migration based on certain conditions, and the other is to name the minimum upgrade version in your metadata using the key: minimum_version_for_upgrade.

New Feature Integration

  • Your product should be validated to correctly function with the new BOSH-deployed-certificates functionality enabled in Ops Manager / Elastic Runtime.
  • As part of making sure that that your tile is working, it is recommended that you make sure you’re integrating with Elastic Runtime and Ops Manager 1.7 in your CI. Plug 1.7 alpha builds of Ops Manager / Elastic Runtime into your CI / integration testing. You may find it useful to leverage the work that the PCF Release Engineering team has done to update automation tooling to be compatible with Ops Manager 1.7. The best way to access and set up that tooling is via the latest published Ops Manager gem (0.34.6).
Create a pull request or raise an issue on the source for this page in GitHub