PCF v2.4 Partners Release Notice

Page last updated:

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

Ops Manager Uses CredHub v2.1

BOSH CredHub, the instance that manages credentials on the Ops Manager VM, now uses CredHub v2.1. For more information about where your credentials are stored, see BOSH CredHub.

CredHub v2.1 includes bug fixes, improved security, and new options for managing credential permissions. These updates are not directly visible to PCF operators, but CredHub v2.1 introduces breaking changes for tile and service authors. For more information, see CredHub v2.1 Backwards­ Incompatible API and Manifest Changes below.

Syslog Form Template Available for Tile Authors

Tile authors can insert a templatized Syslog form into their tiles by editing metadata.yml. The pane that the form creates is identical to the Syslog pane in Ops Manager and the BOSH Director tile. The form template is an opportunity to make tile users’ experience more consistent and secure.

For more information about modifying metadata.yml, see Property Template References.

PAS Uses cflinuxfs3 by Default

PAS v2.4 uses the cflinuxfs3 stack and related buildpacks by default on new installs. Buildpacks have the same name but use a different stack.

You can switch between cflinuxfs2 and cflinuxfs3 using the cf CLI (Cloud Foundry Command Line Interface). For more information, see Changing Stacks.

You can also set your default stack in the Cloud Controller pane of the PAS tile. For more information, see Cloud Controller.

The cflinuxfs3 stack was introduced in PAS v2.3. For more information, see cflinuxfs3 Stack and Compatible Buildpacks in the PAS v2.3 release notes.

For information about breaking changes caused by cflinuxfs3, see Tile Authors Must Manually Migrate Apps to cflinuxfs3 below.

Consul Server VMs Are Removed from PAS

Consul Server VMs are now removed from PAS, saving VM resources and reducing maintenance around managing a clustered component. For more information about breaking changes caused by consul server removal, see Tile Authors Must Remove consul_agent.

Uniquely Identify Metrics by Tile

As the value for deployment, metrics use cf-GUID, which corresponds to the BOSH deployment name of your PAS tile. With a GUID, you can uniquely identify your metrics by tile. In PAS v2.3 and earlier, metrics have a deployment value of cf.

This feature is enabled by default in new deployments of PAS v2.4, but disabled by default for PAS deployments upgrading to PAS v2.4.

Breaking Change: If you have scripts that rely on cf as the value for deployment, your scripts might break. For more information, see Changed Deployment Value for PAS Metrics.

See Human-Friendly Metadata for Metrics

PAS now tags metrics with additional metadata to help operators better parse the metrics coming from their different deployments. These metadata tags also enable downstream monitoring products, such as PCF Healthwatch, to easily display human-readable names.

The tags are as follows:

  • product: The value of this tag is always Pivotal Application Service for the PAS tile. The tags for other products are PCF Isolation Segment, PCF Small Footprint, Pivotal Application Service for Windows 2012R2, and Pivotal Application Service for Windows.

  • system_domain: The value of this tag corresponds to what you set in the System Domain field in the Domains tab of the PAS tile.

  • placement_tag: The value of this tag is always null for PAS. However, for PAS for Windows and PCF Isolation Segment tiles, you can configure this value using the Segment Name field in the Application Containers pane.

Previously, you could not easily know the deployment that a metric from an Isolation Segment was emitted from. Now, an operator can display capacity and other relevant metrics using the placement_tag name. This makes it easier to reason the importance of a given segment when issues arise.

These tags are properties of the metron agent running on each VM in a deployment.

Loggregator v2 API Is Readable through RLP Gateway

As a nozzle developer, you can access the Loggregator v2 API through a Reverse Log Proxy (RLP) gateway. The RLP gateway provides an HTTP API to access the RLP. With the RLP gateway, you do not need to manage mutual TLS to access the Loggregator v2 API.

By default, the RLP communicates with clients using gRPC over mutual TLS. To enable HTTP access instead, use the RLP Gateway. For more information about the RLP Gateway, see Reverse Log Proxy (RLP) Gateway in the Loggregator GitHub repository.

For more information about the Loggregator API, see loggregator-api in GitHub.

Emit Custom App Metrics to the Metric Registrar

PAS v2.4 includes a new component: the Metric Registrar. The Metric Registrar allows app developers to export custom app metrics and events in a format that Loggregator can consume. App developers can then use the custom metrics to monitor apps with PCF Metrics and configure autoscaling rules with PCF Autoscaler.

For more information, see the following topics:

Create Dynamic Egress Policies (Beta)

PAS v2.4 includes a beta feature that allows you to create dynamic egress policies so your apps can communicate with external services. These policies are similar to Application Security Groups (ASGs) but include the following advantages:

  • You do not have to restart your apps when applying these policies, so there is no downtime.
  • The policies include an additional level of granularity: you can apply them to specific apps.

For more information, see Administering Dynamic Egress Policies (Beta).

Pivotal Application Service Tile Property Changes

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

The following tables list the properties that Pivotal removed and added in PAS v2.4:

Removed Properties
.properties.system_db_link
Added Properties
.properties.cloud_controller_temporary_disable_deployments
.properties.enable_cf_metric_name
.properties.enable_smb_volume_driver
.properties.enable_tls_to_internal_pxc
.properties.experimental_dynamic_egress_enforcement
.properties.metric_registrar_blacklisted_tags
.properties.metric_registrar_enabled
.properties.metric_registrar_orchestrator_tls
.properties.metric_registrar_rlp_tls
.properties.metric_registrar_scrape_interval_in_seconds
.properties.metric_registrar_worker_tls
.properties.reverse_log_proxy_gateway_client_tls_cc_cert
.properties.reverse_log_proxy_gateway_client_tls_rlp_cert
.properties.ssh_proxy_backends_tls

Breaking Changes

CredHub v2.1 Backwards Incompatible API and Manifest Changes

CredHub v2.1 has the following backwards­ incompatible API and manifest changes:

  • Authorization model changes: Identities are no longer able to write to CredHub solely by virtue of authenticating. Instead, an explicit access control entry needs to be created, granting an identity read, write, delete, read_acl, or write_acl permissions to an identity, for a given namespace.
  • set and generate changes: CredHub is simplifying the rules that determine when set or generate requests do nothing or overwrite existing values.
  • Minor manifest changes: The structure of the CredHub job properties in the BOSH manifest has some minor changes:
    • The keys encryption_password and encryption_key_name are now nested under the key_properties key.
    • Properties for configuring encryption providers are now nested under a key called connection_properties. These include endpoint, partition, partition_password, client_certificate, client_key, and servers.
    • There is a new property called credhub.authorization.permissions that takes an array of permissions objects. Each permissions object has the following key value pairs:
      • path—a string that represents the credential path
      • actors—an array of authorized users and/or services that can perform operations on the given credential path
      • operations—a list of operations that can be performed by the given actors on a given credential path. These operations include read, write, delete, read_acl, and write_acl.
  • Authorization on by default: The default value of credhub.authorization.acls.enabled is changing from false to true.

If you use CredHub, perform regression testing with PAS for CredHub v2.1. The Pivotal ISV Partner Program can give you access to an environment with an alpha PAS release with the new CredHub verison.

Customers who do a fresh install of PAS are impacted and need to apply new permissions when bootstrapping. The CredHub v2.1 upgrade does not affect customers who upgrade PAS.

Tile Authors Must Manually Migrate Apps to cflinuxfs3

In PAS v2.4, cflinuxfs3 is the default stack. The stack property on an app is sticky. Stack properties do not change automatically unless apps are explicitly repushed with cflinuxfs3.

In PAS v2.5, the cflinuxfs2 stack will no longer be included.

Note: Canonical will end general support for cflinuxfs2 stack (derived from Ubuntu Trusty 14.04 LTS) on April 18th, 2019.

If your tile contains errands that push apps, such as service brokers, you must manually configure the errands to push apps using the cflinuxfs3 stack.

To maintain compatibility with PAS v2.2, you must also configure the errands to push apps using cflinuxfs2 if the cflinuxfs3 stack is not available. There are no plans to make cflinuxfs3 available as a patch release to PAS v2.2.

Errands cannot detect the PAS version. Configure the errands in your tile to run cf stacks to see which stacks are available, and then push the app using the appropriate stack.

To push an app using cflinuxfs3, run cf push -s cflinuxfs3 MY-APP, replacing MY-APP with the name of the app.

To push an app using cflinuxfs2, run cf push MY-APP, replacing MY-APP with the name of the app.

Tile Authors Must Use Xenial Stemcells

Canonical will end support for Ubuntu Trusty Tahr on April 30th, 2019 and security fixes will no longer be backported. PCF is transitioning to use stemcells based on Xenial Xerus and will no longer support Trusty stemcells in PCF 2.5. Tile authors should start testing with the Xenial stemcells and fix any compatibility issues.

Starting in PCF v2.3, Ops Manager uses a Xenial stemcell. Before you upgrade to PCF v2.4, you must do the following:

  1. If you are using any of the BOSH add-ons for PCF, you must update the add-on and its configuration to include the Ubuntu Xenial 16.04 stemcell. The following add-on versions support the Xenial stemcell:

  2. Verify that any tiles that you have installed in your current deployment, either from Pivotal or a partner, are compatible with PCF v2.4. For more information on checking PCF and stemcell compatibility, see Tile Compatibility in the Upgrade Checklist.

    In some cases, you might need to download and import a new Xenial stemcell into Ops Manager v2.2 to upgrade your tiles. To download a Xenial stemcell from Pivotal Network, visit Stemcells for PCF (Ubuntu Xenial).

For information on which PCF tile releases now use Xenial, see Tiles Using Xenial Stemcells in PCF.

Tile Authors Must Remove consul_agent

If your tile includes consul clients, you must remove consul clients from your product.

This is because the consul server no longer exists. The consul client expects the consul server to be present until their links are updated. If your tile includes consul clients, deployments fail to deploy. This can cause extra error logging and unhealthy instances.

Take the following actions according to which PCF versions your tile supports:

  • If your tile only supports PCF v2.2 and earlier, do not remove consul agents.

  • If your tile only supports PCF v2.3 or later, you must remove consul agents completely from your tile.

  • If your tile supports multiple versions, including PCF v2.2 (where consul agents cannot be removed) and PCF v2.3 (where consul agents must be removed) make the following changes to any job_type that is colocated with consul_agent:

    - name: consul_agent
        release: consul
        ...
        manifest: |
          ...
          consul:
            client:
              enabled: "(( $ops_manager.dns_enabled ? false : true ))"
    

Administrative Tasks Must Use Client Credentials

Components have errands and other tasks such as smoke tests and deploy scripts that use an internal user to perform administrative operations. These apps must migrate from internal users and instead use client credentials.

This allows you to disable internal users to meet customer compliance. To conform to customer compliance you must use enterprise users, such as SAML or LDAP, and must not have service accounts. Disabling internal users also facilitates rotating credentials and enabling multi-factor authentication.

Tile Authors Must Migrate to MySQL for PCF v2

PCF v2.4 does not support MySQL for PCF v1. Tiles that depend on MySQL for PCF v1 must migrate to MySQL for PCF v2 tile. If your tile uses MySQL for PCF v1, you should do the following:

  1. Change your tile to use MySQL for PCF v2.
  2. Update your tile to declare a dependency on MySQL for PCF v2.
  3. Document a strategy for data migration. For more information, see Migrating Data in MySQL for PCF.