Enabling Instance Identity in Cloud Foundry

Page last updated:

You can enable the Instance Identity system for your Cloud Foundry deployment.

The Instance Identity system provides each app instance with a unique PEM-encoded X.509 certificate and PKCS#1 RSA private key pair that encodes its identity in the Cloud Foundry deployment.

Enabling Instance Identity

Instance Identity is enabled by default in cf-deployment.

To enable this feature in Cloud Foundry deployments not based on cf-deployment, generate a PEM-encoded CA certificate and private key for the Diego Cell reps to use to issue certificates with the following characteristics listed in Requirements. Next, set the following properties in the BOSH deployment manifest on the rep job on the Diego Cells:

  • diego.executor.instance_identity_ca_cert: PEM-encoded CA certificate used to issue Instance Identity credentials.
  • diego.executor.instance_identity_key: PEM-encoded private key used to issue instance identity credentials.

You can also install the Instance Identity CA certificate as a trusted system certificate for apps, so that app instances trust each others’ Instance Identity credentials automatically. For more information about installing this CA certificate, see Configuring Trusted System Certificates for Apps.

For information about how developers can use the Instance Identity credentials in apps on Cloud Foundry, see Using Instance Identity Credentials.

Configuring Instance Identity validity period

By default, the certificate is valid for 24 hours after the container is created. The Cloud Foundry operator can control this validity period by modifying the diego.executor.instance_identity_validity_period_in_hours BOSH property in the rep job. The smallest allowed validity duration is 1 hour.

The Diego Cell rep supplies a new certificate and private key pair to the app instance before the end of the validity period. The new pair of files replaces the existing pair at the same path locations, with each file replaced atomically.

  • If the validity period exceeds 4 hours, the pair regenerates between 1 hour and 20 minutes before the end of the validity period.

  • If the validity period is less than or equal to 4 hours, the pair regenerates between ¼ and 1/12 of the time to the end of the period.


The CA certificate that the Diego Cell rep uses to issue Instance Identity credentials must have all the properties required to sign other certificates:

  • The Subject Key Identifier must be set.

  • The KeyUsage must include KeyCertSign.

  • If the Diego Cell rep is configured with an intermediate CA certificate, the certificate should have either an empty ExtendedKeyUsage extension or one with the any property.

Create a pull request or raise an issue on the source for this page in GitHub