Creating New Variables in CredHub
Page last updated:
Warning: Pivotal Operations Manager v2.3 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
This topic explains how CredHub manages variables in the context of a larger deployment, and how to create new variables for use in CredHub.
When a tile author defines a top-level
variables section in the product template, Ops Manager passes the
variables section to the product manifest.
tile authors can define variables in the product template as follows:
variables: - name: EXAMPLE-CREDHUB-PASSWORD type: password
You can reference these variables in the manifest snippets in their tile metadata using a triple parentheses syntax:
((( EXAMPLE-CREDHUB-PASSWORD )))
Using triple parentheses lets Ops Manager identify CredHub variables while still supporting the BOSH double parentheses syntax. A variable referenced within triple parentheses is replaced by double parentheses in the generated manifest. After contacting CredHub, BOSH populates that variable value internally.
The benefit of this approach is that the Ops Manager YAML file does not contain sensitive credentials when the metadata manifest snippets have triple parentheses. The resulting manifest file contains variables within double parentheses, rather than unobscured credentials.
For example, a tile author adds credentials to a manifest snippet in the following format:
key: ((( EXAMPLE-CREDHUB-PASSWORD ))) key: prefix-((( ANOTHER-CREDHUB-PASSWORD )))-suffix
Ops Manager evaluates the above example to generate the following section in the product manifest:
(( EXAMPLE-CREDHUB-PASSWORD )) prefix-(( ANOTHER-CREDHUB-PASSWORD ))-suffix
How CredHub Works Within a Deployment
CredHub is distributed as a BOSH release. As part of this installation, Ops Manager co-locates the CredHub release on the BOSH Director, including the CredHub job configurations, and the Director is configured to point to the CredHub API.
Once CredHub has been deployed and configured on the Director, any Director deployment can use CredHub variables in place of credential values. Using variables, rather than values, provides an extra layer of security when transmitting credentials within your deployment.
Changing Your Deployment Manifest to Include CredHub Variables
The BOSH Director interpolates credential values into manifests that use the
((variables)) syntax. When the Director encounters a variable using this syntax, it requests the credential value from CredHub. If the credential does not exist and the release or manifest contains generation properties, the credential value is generated automatically.
The manifest excerpt below includes references to two credentials,
When this manifest is deployed, the BOSH Director retrieves the stored variables and replaces them with the credential values associated with each variable. The
EXAMPLE-TLS variables include property accessors, so only the
private_key components are interpolated.
name: demo-deploy instance_groups: jobs: - name: demo release: demo properties: demo: password: ((EXAMPLE-PASSWORD)) tls: certificate: ((EXAMPLE-TLS.certificate)) private_key: ((EXAMPLE-TLS.private_key))
Ops Manager configures the Director to generate a credential if it does not exist. The manifest includes generation parameters that define how the credential should be generated. These generation parameters are defined in the variables section as shown below.
--- name: demo deploy variables: - name: EXAMPLE-PASSWORD type: password - name: EXAMPLE-CA type: certificate options: is_ca: true common_name: 'Example Certificate Authority' - name: EXAMPLE-TLS type: certificate options: ca: EXAMPLE-CA common_name: example.com instance_groups: jobs: - name: demo release: demo properties: demo: password: (( EXAMPLE-PASSWORD )) tls: certificate: (( EXAMPLE-TLS.certificate )) private_key: (( EXAMPLE-TLS.private_key ))
Deployment manifests often use common variable names; for example,
(( PASSWORD )). To avoid variable name collisions between deployments, the BOSH Director automatically stores variables with the BOSH Director name and deployment name. For example, the variable
(( EXAMPLE-PASSWORD )) is stored in CredHub as /BOSH-Director-name/deployment-name/example-password.
Other Namespacing Options
Use a BOSH link to share credentials across deployments. You can read about BOSH links in the v1.11 Release Notice. Alternatively, if you want to use an exact name, prefixing the variable with a forward slash (/) will cause the Director to use the exact name you type. An example of a precisely typed variable follows.