Setting up and deploying CredHub with BOSH

Page last updated:

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

If you use the bosh-deployment repository on GitHub, 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 the appropriate components.

Once configured, any variable in a BOSH deployment manifest with the syntax ((variable-name)) causes the BOSH Director to retrieve the variable value from CredHub at deployment time. You can tell your manifest already uses CredHub if the fields with secure data have ((variables)) formatted with double 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: https://bosh.io/d/github.com/cloudfoundry/bosh?v=261.2
          version: 261.2
          sha1: d4635b4b82b0dc5fd083b83eb7e7405832f6654b
        # ...
        - name: credhub
          url: https://bosh.io/d/github.com/pivotal-cf/credhub-release?v=0.6.1
          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: credhub.example.com
            alternative_names:
            - 10.0.0.10
            - 127.0.0.1
        - 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: mysql.example.com
          port: 3306
          database: credhub
          username: user
          password: PASSWORD
          require_tls: true
          tls_ca: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
          authentication:
            uaa:
              url: "https://uaa.example.com:8443"
              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: hsm.example.com
                  port: 1792
                  partition_serial_number: 123456
                  certificate: |
                    -----BEGIN CERTIFICATE-----
                    ...
                    -----END CERTIFICATE-----
    

    Where:

    • 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.read,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.read,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: bosh.EXAMPLE.com
        name: director-name
        config_server:
          enabled: true
          url: "https://127.0.0.1:8844/api/"
          ca_cert: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
          uaa:
            url: "https://127.0.0.1:8443"
            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: 127.0.0.1
        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. Users must have both credhub.read and credhub.write access scopes.

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

    Where:

    • 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 credhub.read 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
    

    Where:

    • 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 ~/ssh.pub --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-Manifest
    releases:
    - name: shell
      url: https://bosh.io/d/github.com/cloudfoundry-community/shell-boshrelease?v=3.2.0
      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: 10.0.0.100
            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