HashiCorp Vault Integration

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.

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 and parameter namespaces, and Vault URL.

   • 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.

   • Parameter namespace 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).

   Vault AppRole

   LDAP Auth

   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:

project {

    features {
        hashiCorpVaultConnection {
            id = "PROJECT_EXT_34"
            name = "HashiCorp Vault"
            url = "http://127.0.0.1:8200/"
            vaultNamespace = "enterprise/vault/namespace"
            authMethod = appRole {
                roleId = "..."
                secretId = "..."
            }
            failOnError = false
        }
    }
}

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.

   note

   You can set up parameters only for projects with a valid Vault connection (or inherit it from a parent project).

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 the same value as in the Vault connection you wish to use.

     

     Select Default Namespace (empty) to choose a connection with an empty Parameter Namespace field.

   • 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:

project {
    params {
        hashiCorpVaultParameter {
            name = "env.AWS_ACCESS_KEY_ID"
            query = "secret/data/awscreds!/access_key"
            namespace = "DataLore"
        }
    }
}

project {
    params {
        param("env.AWS_ACCESS_KEY_ID", "%\vault:secret/data/awscreds!/access_key%")
    }
}

project {
    params {
        hashiCorpVaultParameter {
            name = "env.AWS_ACCESS_KEY_ID"
            query = "secret/data/awscreds!/access_key"
        }
    }
}

project {
   params {
      hashiCorpVaultParameter {
         name = "parameter name"
         query = "path!/key"
         namespace = "foobar"
      }
   }
}