Migrating Existing Credentials to CredHub

This topic explains how to migrate non-configurable secrets from Ops Manager into CredHub.

CredHub Credential Types

CredHub uses BOSH credential types, which may have different names from Ops Manager credential types. The following table lists the Ops Manager credential types you can migrate to CredHub and the corresponding CredHub credential types.

Ops Manager Credential Type CredHub Credential Type Supported Ops Manager Version
secret password 1.11.1
simple_credential user 1.12 Alpha 1
salted_credential user 1.12 Beta 1
rsa_pkey_credential rsa 1.12 Alpha 1

Note: CredHub does not retain the salt when migrating salted_credentials.

See Property Reference for more information about credential types.

Use the JavaScript Migration Process

Tile Authors can write a JavaScript migration to move their existing non-configurable secrets into CredHub. After a successful migration, Ops Manager deletes credentials from installation.yml.

  1. Use the following example to write the JavaScript migration. Save the JavaScript file to the PRODUCT/migrations/v1 directory of your .pivotal tile, following the naming conventions discussed in the Update Values or Property Names Using JavaScript topic.

    exports.migrate = function(input) {
      input.variable_migrations.push({
        from: input.properties['.PROPERTY-REFERENCE.EXAMPLE-SECRET'],
        to_variable: 'SECRET-VARIABLE'
      });
      return input;
    };
    

    In the code block above, replace the example text as follows:

    • PROPERTY-REFERENCE: Replace with the property reference that corresponds to the metadata file, such as properties. See Tile Upgrades for more information about migrating properties.
    • EXAMPLE-SECRET: Replace with the name of the key.
    • SECRET-VARIABLE: Choose a variable name for the migrated secret.
  2. Remove the property blueprint for the secret and replace it with a CredHub variable.

    • In your metadata, remove the block that includes the credential. For example, remove the block that includes -name: EXAMPLE-SECRET and type: secret:

      property_blueprints:
        - name: EXAMPLE-SECRET
          type: secret
        - name: generated_uuid
          type: uuid
        - name: configured_secret
          type: secret
          configurable: true
          optional: true
        - name: configured_simple_credentials
          type: simple_credentials
          configurable: true
          optional: true
      
    • In handcraft.yml, add a variables section and include the variable name and type:

      variables:
        - name: SECRET-VARIABLE
          type: password
      

      Note: While the property blueprint refers to the above type as secret, BOSH refers to the type as password. See the CredHub Credential Types table at the beginning of this topic for more information about credential types.

  3. In your manifest snippet, replace the existing secret value with the new triple-parenthesis syntax.

    • Remove the existing secret from the manifest snippet:

      secret: (( .PROPERTY-REFERENCE.SECRET-VARIABLE.SECRET-VALUE ))
      
    • Add the new CredHub variable to the manifest snippet:

      secret: ((( SECRET-VARIABLE )))
      
  4. Run a test deploy of your tile.

  5. Use an API endpoint to confirm that the credential is stored in the variable. For more information about the endpoint, see Fetching Variable Names and Values.

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