HCP Vault and Gitlab Integration

Introduction

This guide will provide examples of errors you may encounter when trying to setup GitLab Vault integrations with HCP Vault, why the error occurs, and how to resolve the issue.

Problem

After setting up GitLab CI/CD integration with Vault and trying to run a job, you may run into 400 errors similar to the following:

ERROR: Job failed (system failure): resolving secrets: initializing Vault service: preparing authenticated client: authenticating Vault client: writing to Vault: api error: status code 400: role "vault-example" could not be found

ERROR: Job failed (system failure): resolving secrets: initializing Vault service: preparing authenticated client: authenticating Vault client: writing to Vault: api error: status code 400: missing client token

Causes

If no namespace is specified in the job script, GitLab/GitLab runner tries to run in the "root" namespace which does not exist in HCP Vault.

Some versions of GitLab/GitLab Runner do not support namespaces in Vault.

Solutions

HCP Vault requires all CLI and API requests go to a namespace (see this article for more details). You'll need to export the namespace for HCP vault via the export command or via GitLab CI/CD variables (only available with GitLab/GitLab Runner versions 14.9 or higher).

Job Script

In your job script, export the namespace for HCP Vault:

read_secrets:
  script:
    # Vault's address can be provided here or as CI/CD variable
    - export VAULT_ADDR=http://vault.example.com:8200
# Vault's namespace can be provided here or as a CI/CD variable
- export VAULT_NAMESPACE=admin

GitLab CI/CD variables

GitLab supports CI/CD environment variables to be used in jobs. In order to be able to use VAULT_NAMESPACE CI/CD variable, please make sure that you are using the GitLab/GitLab Runner version 14.9 or higher.

read_secrets:
  script:
    - echo $VAULT_ADDR
- echo $VAULT_TOKEN
- echo $VAULT_NAMESPACE

Additional Information and Resources

VAULT_NAMESPACE CI/CD variable setting introduced in GitLab 14.9 and GitLab Runner 14.9. View the full GitLab changelog for more details.

See GitLab's guide to learn how to authenticate and reading secrets with HashiCorp Vault.

See GitLab's guide to learn how to use external secrets in CI.