Setting up and deploying CredHub with BOSH | Cloud Foundry Docs (2023)

Page last updated:

  • Preparing for deployment
  • Configuring the BOSH Director
  • Using CredHub

You can deploy a BOSH Director with CredHub so that you can use credential variables in yourdeployment manifests.

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

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

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

Preparing for deployment

To prepare to deploy a BOSH Director with CredHub:

  1. Set up your BOSH Director.

    The following configuration steps assume that you have an existing BOSH Director. If you do not have a BOSH Director, see Deploying BOSH with create-env in the BOSH documentation.

  2. Configure UAA on your Director.

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

  3. (Optional) Configure an external database.

    To optimize fault tolerance, store CredHub data in an external database. To accomplish this, you must create a database and user on your database server before deployment. You can use the internal BOSH Director database to store CredHub data, but be careful to avoid data loss when you provision or update the BOSH 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.
    • 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, see Using hardware security modules with CredHub.

Configuring the BOSH Director

To configure your BOSH Director with CredHub:

  1. Download the latest CredHub release from the Releases page in the CredHub repository on GitHub.

  2. Update the deployment manifest to include the latest CredHub release. For example:

     releases: - name: bosh url: version: 261.2 sha1: d4635b4b82b0dc5fd083b83eb7e7405832f6654b # ... - name: credhub url: version: 0.6.1 sha1: 5ab4c4ef3d67f8ea07d78b1a87707e7520a97ab7

    For more information, see Latest Version in credhub Release in the BOSH documentation.

  3. Add the CredHub job to the BOSH Director instance:

    instance_groups: - name: bosh instances: 1 jobs: - {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 # ...
  4. (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 in the following example. You can adjust or remove these if you prefer to provide your own values.

     variables: - name: credhub-ca type: certificate options: is_ca: true common_name: 'CredHub CA' - name: credhub-tls type: certificate options: ca: credhub-ca common_name: alternative_names: - - - name: credhub-encryption-password type: password
  5. Add CredHub properties to the deployment manifest, as in the following example. This example includes a configuration to use a hardware security module (HSM) for encryption.

    properties: credhub: port: 8844 log_level: info tls: certificate: ((credhub-tls.certificate)) private_key: ((credhub-tls.private_key)) data_storage: type: mysql host: port: 3306 database: credhub username: user password: PASSWORD require_tls: true tls_ca: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- authentication: uaa: url: "" verification_key: | -----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY----- mutual_tls: trusted_cas: - | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- encryption: keys: - provider_name: corp-hsm encryption_key_name: KEY-NAME active: true providers: - 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----- servers: - host: port: 1792 partition_serial_number: 123456 certificate: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----


    • PASSWORD is the password for your CredHub instance.
    • KEY-NAME is your CredHub encryption key.
    • PARTITION-NAME is the name of the HSM partition on which your CredHub encryption key is stored.
    • PARTITION-PASSWORD is the password of the HSM partition on which your CredHub encryption key is stored.

      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.

    ... encryption: providers: - name: main type: internal keys: - provider_name: main encryption_password: ((credhub-encryption-password)) active: true...

    For the full list of CredHub properties and default values, see credhub job in the BOSH documentation.

  6. Add CredHub CLI and your BOSH Director and CredHub UAA clients.

    properties: uaa: clients: credhub_cli: override: true authorized-grant-types: password,refresh_token scope:,credhub.write authorities: uaa.none access-token-validity: 120 refresh-token-validity: 1800 secret: "" director_to_credhub: override: true authorized-grant-types: client_credentials scope: uaa.none authorities:,credhub.write access-token-validity: 43200 secret: CUSTOM-CLIENT-SECRET

    Where CUSTOM-CLIENT-SECRET is the client secret you set for the BOSH Director.

  7. Enable the configuration server feature of the BOSH Director and configure it to utilize CredHub:

    properties: director: address: name: director-name config_server: enabled: true url: "" ca_cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- uaa: url: "" client_id: director_to_credhub client_secret: EXAMPLE-SECRET ca_cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
  8. (Optional) Configure the BOSH Director Postgres server with an additional database named credhub. If you are using the internal BOSH 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.

    properties: postgres: &db host: port: 5432 user: postgres password: POSTGRES-PASSWORD database: bosh additional_databases: [credhub] adapter: postgres

    Where POSTGRES-PASSWORD is the password for your Postgres server.

  9. (Optional) Seed initial CredHub users to UAA.

    Note: Users must have both and credhub.write access scopes.

    properties: uaa: scim: users: - name: CREDHUB-USER password: USER-PASSWORD groups: - - credhub.write - name: OTHER-CREDHUB-USER password: OTHER-USER-PASSWORD groups: - - credhub.write


    • CREDHUB-USER and OTHER-CREDHUB-USER are the CredHub users you want to seed to UAA.
    • CREDHUB-PASSWORD and OTHER-CREDHUB-PASSWORD are the passwords for the CredHub users you want to seed to UAA.
  10. Deploy the BOSH Director. For more information, see Deploying in the BOSH documentation.

Using CredHub

To use 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. To create users in UAA, see Creating and managing users with the UAA CLI . Alternatively, you can configure UAA with an external LDAP provider. For more information, see User Account and Authentication LDAP Integration in the CloudFoundry User Account and Authentication (UAA) Server repository on GitHub.

  2. Install the CredHub CLI to manage stored credentials. Download the CredHub CLI from the Releases page in the CredHub CLI repository on GitHub.

  3. Target the CredHub API by running:

    credhub api CREDHUB-API-TARGET

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

  4. Authenticate with CredHub by running:

    credhub login --client-name= CLIENT-NAME --client-secret= CLIENT-SECRET


    • CLIENT-NAME is the name of the UAA client.
    • CLIENT-SECRET is the secret for the UAA client.
  5. Place or generate credentials in CredHub using the CredHub CLI:

    • To place credentials in CredHub, run:

      credhub set --type ssh --name /static/ssh_key --public ~/ --private ~/ssh.key
    • To generate credentials in CredHub, run:

      credhub generate --type ssh --name /generated/ssh_key
  6. Update your BOSH deployment manifests. Once you have a BOSH Director that integrates with CredHub, you can update your deployment manifests to use it. The following example is a deployment manifest using two credentials: one stored in CredHub, and one that is generated by CredHub. You can define credentials that you want to be generated automatically in the variables section.

    name: Sample-Manifestreleases:- name: shell url: sha1: 893b10af531a7519da99bb8656cc07b8277d1692#...variables:- name: generated/ssh\_key type: sshjobs: - 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
Top Articles
Latest Posts
Article information

Author: Zonia Mosciski DO

Last Updated: 16/09/2023

Views: 6295

Rating: 4 / 5 (71 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Zonia Mosciski DO

Birthday: 1996-05-16

Address: Suite 228 919 Deana Ford, Lake Meridithberg, NE 60017-4257

Phone: +2613987384138

Job: Chief Retail Officer

Hobby: Tai chi, Dowsing, Poi, Letterboxing, Watching movies, Video gaming, Singing

Introduction: My name is Zonia Mosciski DO, I am a enchanting, joyous, lovely, successful, hilarious, tender, outstanding person who loves writing and wants to share my knowledge and understanding with you.