Securing Services Instance Credentials with Runtime CredHub (Beta)

This topic describes how Pivotal Cloud Foundry (PCF) operators can ensure service instance credentials are securely stored in CredHub.

Note: This feature is currently in Beta.

  • What is runtime CredHub?
    • The Pivotal Application Service (PAS) tile includes its own CredHub component, separate from the CredHub component included with the Ops Manager Director tile. For more information about this centralized credential management component, see the CredHub documentation.
  • What is runtime CredHub used for?
    • Runtime CredHub exists to securely store service instance credentials. Previously, PCF could only use the Cloud Controller database for storing these credentials.
  • What are service instance credentials?
    • When developers want their app to use a service, such as those provided by the Spring Cloud Services tile for PCF, they must bind their app to an instance of that service. Service bindings include credentials that developers can use to access the service from their app. For more information, see Binding Credentials.
  • How can I ensure that service instance credentials are stored in runtime CredHub?
    • You must configure PAS to enable this functionality by following the procedure below. Not all services support the use of runtime CredHub.
  • Can I use runtime CredHub to store service instance credentials if some of my services do not support the use of runtime CredHub?
    • PAS supports both services that do and do not use runtime CredHub. Services that do not use runtime CredHub continue to pass their credentials to the Cloud Controller database.
  • Can I rotate service instance credentials in runtime CredHub?

PCF Services that Use Secure Binding Credentials

The procedures in this document are only effective for services that support storing their instance credentials in runtime CredHub. To learn whether a service supports this feature, see the table below or the documentation for that service.

Service Versions with Secure Binding Credentials Pivotal Network Listing
CredHub Service Broker for PCF All CredHub Service Broker for PCF
MySQL for PCF v2 v2.3 and later (available to user groups only) MySQL for PCF v2
Spring Cloud Services for PCF v1.5 and later Spring Cloud Services for PCF
RabbitMQ for PCF v1.12 and later RabbitMQ for PCF


Breaking Change: If you opt out of the BOSH DNS feature, your PCF deployment cannot support Secure Service Instance Credentials.

Step 1: Configure the PAS Tile

You must configure the PAS tile to support securing service instance credentials in CredHub. From the PAS tile in Ops Manager, complete the following steps:

  1. Select the CredHub pane. Credhub
  2. Choose the location of your CredHub Database. PAS includes this CredHub database for services to store their service instance credentials. If you chose External, enter the following:
    • Hostname: The IP address of your database server.
    • TCP Port: The port of your database server, such as 3306.
    • Username: A unique username that can access this specific database on the database server.
    • Password: The password for the provided username.
    • Database CA Certificate: A certificate to use for encrypting traffic to and from the database.
  3. Under Encryption Keys, specify a key to use for encrypting and decrypting the values stored in the CredHub database.
    • Name: Enter the name of the key.
    • Key: Enter a key that is at least 20 characters in length.
    • Primary: Select this checkbox to use this key as your primary key.

      Note: Ensure that you only mark one key as Primary. The UI includes an Add button to add more keys to support key rotation.

  4. If your deployment uses any PCF services that support storing service instance credentials in CredHub and you want to enable this feature, select the Secure Service Instance Credentials checkbox.
  5. Select the Resource Config pane.
  6. In the CredHub row, under the Job column, set the number of instances to at least 2. This is the minimum instance count required for high availability.

Step 2: Create Application Security Groups

Application Security Groups (ASGs) are network policy rules specifying protocols, ports, and IP ranges that apply to outbound network connections initiated from apps. You must follow the steps below to ensure the ASGs for your deployment allow apps to communicate with the runtime CredHub API.

Note: The default ASGs in PCF allow apps running on your deployment to send traffic to almost any IP address. This step is only required if your ASGs restrict network access from apps to the network that PAS runs on, as documented in Restricting App Access to Internal PCF Components.

  1. From the PAS tile, click Assign AZs and Networks and record the selected Network where the tile is installed.

  2. From the Ops Manager Director tile, within the Settings tab, click Create Networks.

  3. In the Networks section, click the name of the PAS network to expand it.

  4. Record the CIDR for the PAS network.

  5. Create a file named runtime-credhub.json for specifying your ASG rules. Copy the content below into the file. Replace YOUR-PAS-CIDR with the CIDR you recorded in the previous step.

      "protocol": "tcp",
      "destination": "YOUR-PAS-CIDR",
      "ports": "8844"
  6. Run the following command to create an ASG that allows apps to access the CredHub API:

    $ cf create-security-group runtime-credhub ~/workspace/runtime-credhub runtime-credhub.json

  7. Bind this ASG to your deployment or the specific space in which you want apps to access CredHub. For more information about binding ASGs, see Bind ASGs. Ensure that apps deployed as part of the service tile installation process have access to CredHub in addition to the apps pushed to the platform by developers. For example, the Spring Cloud Services tile deploys the spring-cloud-broker app to the p-spring-cloud-services space of the system org.

  8. Restart apps for the ASGs to take effect. Optionally, you can use the app-restarter cf CLI plugin to restart all apps in a particular space, org, or deployment.

Step 3: Unbind and Rebind Service Instances

For any service instance bindings that existed before runtime CredHub was supported for that service, you must work with your developers to unbind and rebind the service instances to their apps. If you do not unbind and rebind the service, apps continue functioning as before and fetch credentials from the Cloud Controller database, and not from runtime CredHub.

Note: This step is not required for bindings created after you installed the new version of the service tile that supports CredHub and you completed the procedures in steps 1 and 2 of this topic.

  1. Unbind the service instance from the app:

    $ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE

  2. Rebind the service instance to the app:

    $ cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE

  3. Review the VCAP_SERVICES environment variable to verify that the new service instance binding includes CredHub pointers:

    $ cf env YOUR-APP
    See the VCAP_SERVICES section of Cloud Foundry Environment Variables for help parsing the output of the cf-env command.

  4. Restart the app to apply the service instance binding:

    $ cf restart YOUR-APP
    If you run cf-env again, you can see the VCAP-SERVICES environment variable now contains the credentials for the service instance binding.

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