HashiCorp Vault Integration

Common Information

To set up an integration with HashiCorp Vault, you need the following:

• The HashiCorp Vault connection in the required project (or <Root project>, if you want any TeamCity project to use this connection).

• The parameter that will store a Vault path to a required secret.

• References to this parameter (%parameter_name%) in your build steps (for example, in a Command Line runner that executes the terraform apply -var password=%myVaultParam% line).

When a build that utilizes this parameter starts, the TeamCity server uses the Vault connection to request a one-time response wrapping token, which it then passes to a TeamCity agent that runs this build. The build agent uses this token to request Vault secrets and never shares obtained credentials with the TeamCity server. When the build finishes, the agent's token is revoked.

Since all communication with Vault is orchestrated by the TeamCity server, this integration is highly scalable and not affected by the number of build agents accessing Vault secrets. The tokens received by agents from the TeamCity server are not lease tokens (which are solely utilized for testing Vault connections), thus the number of actual build agents does not impact your quota. Consequently, only one Vault license for the TeamCity server is required.

Set Up a Vault Connection

1. Navigate to Administration | <Your Project> | Connections and click Add Connection.

2. Choose HashiCorp Vault as the connection type.

3. Specify the basic connection settings: the connection name, Vault URL and namespace, and an optional ID.

   • Vault namespaces allow you to create "vaults within a vault" — isolated tenants inside a single Vault Enterprise instance. If you store Vault secrets in this isolated environment, specify its namespace in the Vault namespace connection field (for example, TeamABC/secrets/). Otherwise, leave this setting empty.

   • ID is a custom string that identifies this Vault connection. You can specify this field if you set up multiple Vault connections and specify which connection a specific parameter should use. Otherwise, leave this field blank.

   • Vault URL is the address of your Vault instance. Local Vault installations (the default URL is http://localhost:8200) are also supported.

4. Choose the desired authentication method. TeamCity can authenticate to HCP Vault using a Vault's AppRole, an AWS IAM role, or a directory access protocol (LDAP).

   This authentication method requires that you enable the AppRole auth method in your Vault instance and create an AppRole. AppRoles are sets of Vault policies that specify which secrets a user (in this case, TeamCity) can access. The Vault AppRole auth method requires you to set up the following settings: AppRole auth endpoint path — the path in your Vault instance where the AppRole auth endpoint is mounted. The default path is approle (without the preceding backslash character). AppRole Role ID and AppRole Secret ID — these values can be obtained in CLI using the following commands: vault read -field=role_id auth/<AE>/role/<RN>/role-id vault write -f -field=secret_id auth/<AE>/role/<RN>/secret-id where <AE> is the auth endpoint path you specified above (for example, approle) and <RN> is the name of your role (for example, my-teamcity-role). Refer to these Vault documentation articles to learn how to create and set up AppRoles: Getting Started: Policies, AppRole auth method.

   This method can be used for Vault instances with enabled LDAP auth method. This authentication option requires username and password. The Path setting stores the path to the LDAP authentication endpoint (for example, ldap for the default auth/ldap/users/userA and auth/ldap/groups/groupB endpoints). Refer to this article for more information about setting up this authentication method in Vault: LDAP auth method.

5. Tick Fail in case of error if you want builds to fail with the "Error while fetching data from HashiCorp Vault" message if the agent cannot obtain Vault secrets and write them to TeamCity parameters. Note that builds will fail even if these parameters are never used. If this setting is disabled, builds will continue running with empty strings as secret parameter values.

Kotlin DSL:

Create and Set Up a Parameter

To start using a secret value from HCP Vault in your builds, create a parameter that serves two purposes:

• Stores a path to the Vault secret whose value needs to be obtained

• Stores the secret value after Vault provided it

To create such a parameter, do the following:

1. Go to Administration | <Project or Build Configuration> | Parameters and click Add new parameter.

2. Choose the Environment variable type and enter the parameter name. For example, env.AWS_ACCESS_KEY_ID.

3. Click Edit... next to the "Spec" label and set up the following values:

   • Type: Remote

   • Remote Connection Type: HashiCorp Vault Parameter

   • Parameter Namespace: choose existing Vault connection you wish to use to retrieve this parameter's value. This drop-down menu shows Display names for all connections that have IDs.

     

     

   • Vault Query: the path to the secret in the path!/key format. For example, the following string points the parameter to the "access_key" key of the "awscreds" secret stored in the KV2 engine: secret/data/awscreds!/access_key.

4. Click Save to close the dialog.

Kotlin DSL: