Setting Up and Deploying CredHub with BOSH

Page last updated:

This topic provides details about how to deploy a BOSH Director with CredHub so that you can use credential variables in your deployment manifests.

If you use bosh-deployment, include the file credhub.yml to enable CredHub on the BOSH Director VM.

How It Works

CredHub exists co-located on a virtual machine (VM) with the Director, UAA, and other high-level components. A deployment manifest configured with variables calls to CredHub which then passes the credential to the appropriate components.

Once configured, any variable in a BOSH deployment manifest with the syntax ((variable-name)) causes the Director to retrieve the variable value from CredHub at deploy time. You can tell your manifest already uses CredHub if fields with secure data have ((variables)) formatted with double parentheses.

Setup Before Deployment

  1. Set up BOSH Director.

    The following configuration steps assume that you have an existing BOSH Director. If you do not have a Director, read the initialization guide for more details.

  2. Configure UAA on your Director.

    CredHub uses UAA for user and client authentication. You need a UAA server configured on the Director to enable CredHub. For more information about provisioning UAA on the Director, read the BOSH documentation.

  3. (Optional) Configure an external database.

    To optimize fault tolerance, store CredHub data in an external database. To do so, you must create a database and user on your database server before deployment. You can use the internal Director database to store CredHub data, but take care to avoid data loss when you provision or update the Director VM.

  4. (Optional) Configure a Luna HSM.

    If you use an external Hardware Security Module (HSM) to perform cryptographic operations:

    • Configure the HSM to allow access from the deployed CredHub instance, and
    • Grant the operator all of the required permissions to use the HSM.

      For more information about the required HSM values and how to configure an HSM, read about configuring a Luna HSM.

Configuring the Director

  1. Update the deployment manifest to include the CredHub release. Download the latest CredHub release from
  2.     releases:
        - name: bosh
          version: 261.2
          sha1: d4635b4b82b0dc5fd083b83eb7e7405832f6654b
        # ...
        - name: credhub # <---
          version: 0.6.1
          sha1: 5ab4c4ef3d67f8ea07d78b1a87707e7520a97ab7
  3. Add the CredHub job to the Director instance.
  4.     instance_groups:
        - name: bosh
          instances: 1
          - {name: nats, release: bosh}
          - {name: redis, release: bosh}
          - {name: postgres, release: bosh}
          - {name: blobstore, release: bosh}
          - {name: director, release: bosh}
          - {name: health_monitor, release: bosh}
          - {name: uaa, release: uaa-release}
          - {name: credhub, release: credhub} # <---
          resource_pool: default
          # ...
  5. (Optional) Add variable generation specifications for CredHub properties.

    You can generate values that CredHub requires automatically with the BOSH CLI. To enable generation, add the variable specifications to the manifest as shown below. You can adjust or remove these if you prefer to provide your own values.
  6.     variables:
        - name: credhub-ca
          type: certificate
            is_ca: true
            common_name: 'CredHub CA'
        - name: credhub-tls
          type: certificate
            ca: credhub-ca
        - name: credhub-encryption-password
          type: password
  7. Add CredHub properties to the deployment manifest.
            port: 8844
            log_level: info
              certificate: ((credhub-tls.certificate))
              private_key: ((credhub-tls.private_key))
              type: mysql
              port: 3306
              database: credhub
              username: user
              password: EXAMPLE-PASSWORD
              require_tls: true
              tls_ca: |
                -----BEGIN CERTIFICATE-----
                -----END CERTIFICATE-----
                url: ""
                verification_key: |
                  -----BEGIN PUBLIC KEY-----
                  -----END PUBLIC KEY-----
                - |
                  -----BEGIN CERTIFICATE-----
                  -----END CERTIFICATE-----
              - provider_name: corp-hsm
                encryption_key_name: KEY-NAME
                active: true
              - name: corp-hsm
                type: hsm
                partition: PARTITION-NAME
                partition_password: PARTITION-PASSWORD
                client_certificate: |
                  -----BEGIN CERTIFICATE-----
                  -----END CERTIFICATE-----
                client_key: |
                  -----BEGIN EXAMPLE RSA PRIVATE KEY-----
                  -----END EXAMPLE RSA PRIVATE KEY-----
                - host:
                  port: 1792
                  partition_serial_number: 123456
                  certificate: |
                    -----BEGIN CERTIFICATE-----
                    -----END CERTIFICATE-----
    The example above includes a configuration to use a hardware security module (HSM) for encryption. Alternatively, you can use the internal software-based encryption provider with the configuration below.

    This method derives a 256-bit key from the provided encryption password and utilized AES256-GCM encryption.
            - name: main
              type: internal
            - provider_name: main
              encryption_password: ((credhub-encryption-password))
              active: true
    For the full list of CredHub properties and default values, read the job spec properties.
  8. Add CredHub CLI and Director/CredHub UAA clients.
  9.     properties:
                override: true
                authorized-grant-types: password,refresh_token
                authorities: uaa.none
                access-token-validity: 120
                refresh-token-validity: 1800
                secret: "" # <--- CLI expects this secret to be empty
                override: true
                authorized-grant-types: client_credentials
                scope: uaa.none
                access-token-validity: 43200
                secret: EXAMPLE-SECRET # <--- Replace with custom client secret
  10. Enable the config server feature of Director and configure it to utilize CredHub.
  11.     properties:
            name: director-name
              enabled: true
              # URL must contain /api/ path with trailing slash
              url: ""
              ca_cert: |
                -----BEGIN CERTIFICATE-----
                -----END CERTIFICATE-----
                url: ""
                client_id: director_to_credhub
                client_secret: EXAMPLE-SECRET
                ca_cert: |
                  -----BEGIN CERTIFICATE-----
                  -----END CERTIFICATE-----
  12. (Optional) Configure the Director Postgres server with additional database named credhub. If you are using the internal Director database, you must provision an additional database for the CredHub data. If you use an external database, you must create the database on your database server before deploying.
  13.     properties:
          postgres: &db
            port: 5432
            user: postgres
            password: POSTGRES-PASSWORD
            database: bosh
            additional_databases: [credhub]
            adapter: postgres
  14. (Optional) Seed initial CredHub users to UAA.
  15.     properties:
              - name: CREDHUB-USER
                password: USER-PASSWORD
                # Users must have both and credhub.write access
                -             # <---
                - credhub.write            # <---
              - name: OTHER-CREDHUB-USER
                password: OTHER-USER-PASSWORD
                - credhub.write
  16. Deploy.

Using CredHub

  1. Create CredHub users in UAA.

    To authenticate with CredHub to manage credentials, you must have a UAA user account with the scopes and credhub.write. You can create users in UAA as described in the UAA documentation. Alternatively, you can configure UAA with an external LDAP provider.

    The example below shows how to create two users in UAA.
  2. $ uaac token client get admin -s example-password
      Successfully fetched token via client credentials grant.
      Context: admin, from client admin
    $ uaac user add EXAMPLE-USER --emails Password: ******** Verify password: ******** user account successfully added
    $ uaac user add OTHER-EXAMPLE-USER --emails Password: ******** Verify password: ******** user account successfully added
    $ uaac group add $ uaac member add EXAMPLE-USER OTHER-EXAMPLE-USER success
    $ uaac group add credhub.write $ uaac member add credhub.write EXAMPLE-USER OTHER-EXAMPLE-USER success

  3. Install the CredHub CLI.

    The CredHub CLI offers a simple, scriptable interface to manage stored credentials. You can download the latest release from the GitHub repository.

  4. Run the following command to target the CredHub API:

    credhub api CREDHUB-API-TARGET

    Where CREDHUB-API-TARGET is the URL to your CredHub API server.

  5. Run the following command to authenticate with CredHub:
    credhub login --client-name= CLIENT-NAME --client-secret= CLIENT-SECRET

    • CLIENT-NAME is the client name for UAA client grant.
    • CLIENT-SECRET is the client secret for UAA client grant.
  6. Place or generate credentials in CredHub using the CLI.
  7. $ credhub set --type ssh --name /static/ssh_key --public ~/ --private ~/ssh.key
    $ credhub generate --type ssh --name /generated/ssh_key

  8. Update BOSH deployment manifests.

    Once you have a Director that integrates with CredHub, you can update your deployment manifests to use it. The example below is of a deployment manifest using two credentials; one stored in CredHub, and one generated by CredHub.

    Define credentials that you want to be generated automatically in the variables section.

  9.     name: Sample-Manifest
    releases: - name: shell url: sha1: 893b10af531a7519da99bb8656cc07b8277d1692
    variables: - name: generated/ssh_key type: ssh
    jobs: - name: shell instances: 1 persistent_disk: 0 resource_pool: vms networks: - name: private static_ips: default: [dns, gateway] templates: - name: shell release: shell properties: shell: users: - name: shell ssh_keys: - ((/static/ssh_key)) - ((generated/ssh_key))

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