README.md

How to integrate Concourse pipelines with Vault

Concourse 3.3.1+ supports credential management integration with HashiCorp's Vault and eliminates the need to feed credentials to pipelines via plain-text parameter files.

This integration requires configuration updates to both Vault and Concourse servers as described further below.

From a pipeline definition standpoint, the usage of credentials from Vault is very simple: just add the desired secret to a resources or params section of the pipeline using surrounding double parenthesis.

For example:

jobs:
- name: hello-world
  plan:
  - task: say-hello
    params:
      SYS_USERNAME: ((vault-system-username))

When Concourse runs that pipeline/job, it will search for the corresponding secret in Vault, using a pre-determined search order, and execute the task appropriately with the retrieved values.

Configuring the Vault server

These instructions assume that you already have a Vault server up and running. For more information, refer to Vault's installation documentation or the Vault Bosh release and this sample deployment file.

On an unsealed Vault server while authenticated with a root token, perform the following configuration steps using the Vault CLI:

• Create a mount in value for use by Concourse pipelines
  vault mount -path=/concourse -description="Secrets for concourse pipelines" generic

• Create a policy file (e.g. policy.hcl) with the following content:

  path "concourse/*" {
    policy = "read"
    capabilities =  ["read", "list"]
  }
  

• Register the policy above with Vault:
  vault policy-write policy-concourse policy.hcl

• Initialize Vault and create a periodic token using the new policy:
  vault token-create --policy=policy-concourse -period="600h" -format=json
  Write down the token number created.

• Populate all the variables in Vault under concourse/<team-name>/

  • Write secrets to Vault using the following syntax
    vault write concourse/<team-name>/<variable-name> value=<variable-value>

    Examples:
    vault write concourse/main/username value=admin
vault write concourse/pcf/om-password value=pa$$w0rd

  • Hint: all common secrets used across multiple pipelines within a Concourse team can be defined in concourse/<team-name>/ and pipeline specific secrets can be defined in concourse/<team-name>/<pipeline-name>

Configuring the Concourse server

Copy the token value from the step further above and set it in the Concourse server.

• For binary-based Concourse deployments, see the Concourse documentation for setup instructions.

• For Bosh-based Concourse deployments, update the atc job properties in the deployment manifest as described below and then redeploy Concourse:

instance_groups:
- name: web ...
  jobs:
  - name: atc
    release: concourse
    properties: ...
      vault:
        path_prefix: /concourse
        url: YOUR-VAULT-ADDRESS-GOES-HERE  # e.g. http://192.168.10.15:8200
        auth:
          client_token: YOUR-VAULT-TOKEN-GOES-HERE

Click here for an example of a complete Concourse deployment manifest with Vault integration.

For a complete list of Vault integration parameters for the atc job, please consult the ATC job's documentation.

Then, once you run the pipelines, you should see secret keys being replaced with the corresponding values retrieved from the Vault server by Concourse.

For more information on Concourse and Vault integration, please refer to Concourse's Credentials Management documentation page.

Hint: how to keep pipeline YML files untouched and still integrate with Vault

You could keep existing pipeline YML files untouched while replacing current double curly brackets {{ }} variables with double parenthesis (( )) variables: just change the parameter files that feed the pipeline setup during the fly CLI command execution instead.

For example, if your hello-world.yml looks like this:

jobs:
- name: hello-world
  plan:
  - task: say-hello
    params:
      SYSTEM_PASSWORD: {{system-password}}
    ...

and your params.yml file looked like this:

---
system-password: mypassw0rd123

Then you can simply change params.yml to contain the secret key from Vault:

---
system-password: ((system-password-from-vault-key))

Once you update that pipeline in Concourse with the fly CLI, the vault key ID will be injected into the pipeline YML along with the double parenthesis and it will work just fine.

Many thanks go to Rahul Jain and Ian Zink for their contribution to this research effort.

Back to Concourse Pipeline Patterns