Using CredHub Service Broker

This topic describes how to use CredHub Service Broker for Pivotal Cloud Foundry (PCF).

Create and Bind a Service Instance

Creating a Credhub Service Broker instance and binding it to an app creates a credential in CredHub and provides the reference to that credential in the app environment. This allows developers to deploy apps that can securely access credentials for services that are not running on PAS.

To create a service instance of the CredHub Service Broker and bind it to your app, perform the following steps:

1. Create a CredHub Service Broker service instance. Run the following command:

   cf create-service credhub default SERVICE-INSTANCE \
    -c '{"CREDENTIAL-NAME":"CREDENTIAL-VALUE"}
   

   
   Where:

   • SERVICE-INSTANCE is a name for your new service instance.
   • CREDENTIAL-NAME is the name for the credential you want to provide to services that are not running on PAS.
   • CREDENTIAL-VALUE is the value of the credential.

     Note: You can provide multiple credentials as a JSON list. This JSON list has a maximum size of 64 KB. For example, {"MY_CREDHUB_CRED": "1234", "MY_CREDHUB_CRED2": "5678"}.

     
     
     

     cf create-service credhub default my-credhub-instance \
     -c '{"name":"MY_CREDHUB_CRED","value":"ABCDEFGHIJK123456789"}
     

2. Ensure that your app is written to use the credential that was provided through the service creation.
   
   VCAP_SERVICES is an environment variable that exists in every container. Access the credhub JSON object within VCAP_SERVICES to discover the credentials. For example, in Ruby you would access this JSON object with ENV['VCAP_SERVICES']['credhub'].
   
   If you need to modify your app code, you must re-push the app before continuing.

3. Bind the CredHub Service Broker service instance to your app. Run the following command:

   cf bind-service MY-APP SERVICE-INSTANCE
   

4. Restart your app. Run the following command:

   cf restart MY-APP
   

5. Your app should now have access to the credential created in step 1. To verify that your credential is in the app environment, run the following command and locate the CredHub reference under VCAP_SERVICES in the output:

   cf env MY-APP
   

   
   For example:

   cf env my-app
   Getting env variables for app my-app in org example / space example as admin...
   OK
   System-Provided:
   {
    "VCAP_SERVICES": {
     "credhub": [
      {
       "binding_name": null,
       "credentials": {
        "credhub-ref": "/credhub-service-broker/credhub/ac517e09-2f5e-475a-bf87-ca4275faa536/credentials"
       },
       "instance_name": "credhub",
       "label": "credhub",
       "name": "credhub",
       "plan": "default",
       "provider": null,
       "syslog_drain_url": null,
       "tags": [
        "credhub"
       ],
       "volume_mounts": []
      }
     ]
    }
   }
   

Update Credentials

Perform the following steps to update the credentials in a CredHub Service Broker service instance:

1. Create a CredHub Service Broker service instance. Run the following command:

   cf update-service SERVICE-INSTANCE \
    -c '{"CREDENTIAL-NAME":"CREDENTIAL-VALUE"}
   

   
   Where:

   • SERVICE-INSTANCE is the name of your existing CredHub Service Broker service instance.
   • CREDENTIAL-NAME is the name for the updated credential you want to provide to services that are not running on PAS.
   • CREDENTIAL-VALUE is the value of the credential.

     Note: You can update multiple credentials as a JSON list. For example, {"MY_CREDHUB_CRED": "1234", "MY_CREDHUB_CRED2": "5678"}.

     
     

     cf update-service SERVICE-INSTANCE \
     -c '{"name":"MY_CREDHUB_CRED","value":"ABCDEFGHIJK123456789"}
     

2. Restart your app. Run the following command:

   cf restart MY-APP