create-credhub-vars.html.md.erb

---
title: Creating New Variables in CredHub
owner: CredHub
---

<strong><%= modified_date %></strong>

This topic explains how CredHub manages variables in the context of a larger deployment, and how to create new variables for use in CredHub. 

## Background

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 Ops Manager 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 Ops Manager Director interpolates credential values into manifests that use the <code>((variables))</code> 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, <code>EXAMPLE-PASSWORD</code> and <code>EXAMPLE-TLS</code>. 

When this manifest is deployed, the Ops Manager Director retrieves the stored variables and replaces them with the credential values associated with each variable. The <code>EXAMPLE-TLS</code> variables include property accessors, so only the `certificate` and `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 ))
```

## Variable Namespacing

Deployment manifests often use common variable names; for example, <code>(( PASSWORD ))</code>. To avoid variable name collisions between deployments, the Ops Manager Director automatically stores variables with the Ops Manager Director name and deployment name. For example, the variable <code>(( EXAMPLE-PASSWORD ))</code> is stored in CredHub as /Ops-Manager-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](https://docs.pivotal.io/tiledev/1-11/release-notes.html#bosh-links). 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.

```
((/EXAMPLE-PASSWORD))
```