From 442dc0c58e73d5eab09e35e38f1e1a2aa28fa060 Mon Sep 17 00:00:00 2001
From: Jayakrishnan Mallissery <jmallissery@gitlab.com>
Date: Thu, 13 Mar 2025 07:42:12 +0100
Subject: [PATCH] Update vault integration troubleshooting docs
---
doc/ci/secrets/_index.md | 19 +++++++++++++------
doc/ci/secrets/hashicorp_vault.md | 26 +++++++++++++++++++++-----
2 files changed, 34 insertions(+), 11 deletions(-)
diff --git a/doc/ci/secrets/_index.md b/doc/ci/secrets/_index.md
index b9216a200c247..9d6b32893a2ea 100644
--- a/doc/ci/secrets/_index.md
+++ b/doc/ci/secrets/_index.md
@@ -152,15 +152,17 @@ job_using_vault:
aud: https://vault.example.com
secrets:
DATABASE_PASSWORD:
- vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password`
+ vault: production/db/password@ops
token: $VAULT_ID_TOKEN
```
In this example:
-- `production/db` - The secret.
-- `password` The field.
-- `ops` - The path where the secrets engine is mounted.
+- `production/db` is the path to the secret.
+- `password` is the field.
+- `ops` is the path where the secrets engine is mounted.
+- `production/db/password@ops` translates to a path of `ops/data/production/db`.
+- Authentication is with `$VAULT_ID_TOKEN`.
After GitLab fetches the secret from Vault, the value is saved in a temporary file.
The path to this file is stored in a CI/CD variable named `DATABASE_PASSWORD`,
@@ -262,7 +264,9 @@ IP address range, and number of uses. The full list of options is available in
[Vault's documentation on creating roles](https://developer.hashicorp.com/vault/api-docs/auth/jwt#create-role)
for the JSON web token method.
-## Using a self-signed Vault server
+## Troubleshooting
+
+### Self-signed certificate error: `certificate signed by unknown authority`
When the Vault server is using a self-signed certificate, you see the following error in the job logs:
@@ -291,7 +295,10 @@ You have two options to solve this error:
value: "/home/gitlab-runner/.gitlab-runner/certs/<VAULT_CERTIFICATE>"
```
-## Troubleshooting
+If you are running vault server in development mode locally with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit),
+you might also get this error. You can manually ask the system to trust the self signed certificate of Vault server.
+This [sample tutorial](https://iboysoft.com/tips/how-to-trust-a-certificate-on-mac.html)
+explains how to do this on macOS.
### `resolving secrets: secret not found: MY_SECRET` error
diff --git a/doc/ci/secrets/hashicorp_vault.md b/doc/ci/secrets/hashicorp_vault.md
index e6f57720a0c77..aa3b8f7253851 100644
--- a/doc/ci/secrets/hashicorp_vault.md
+++ b/doc/ci/secrets/hashicorp_vault.md
@@ -319,7 +319,8 @@ In GitLab, create the following [CI/CD variables](../variables/_index.md#for-a-p
to provide details about your Vault server:
- `VAULT_SERVER_URL` - The URL of your Vault server, for example `https://vault.example.com:8200`.
-- `VAULT_AUTH_ROLE` - Optional. The role to use when attempting to authenticate. If no role is specified,
+- `VAULT_AUTH_ROLE` - Optional. Name of the Vault JWT Auth role to use when attempting to authenticate. In this tutorial,
+ we already created two roles with the names `myproject-staging` and `myproject-production`. If no role is specified,
Vault uses the [default role](https://developer.hashicorp.com/vault/api-docs/auth/jwt#default_role)
specified when the authentication method was configured.
- `VAULT_AUTH_PATH` - Optional. The path where the authentication method is mounted.
@@ -340,7 +341,7 @@ job_with_secrets:
aud: https://vault.example.com
secrets:
STAGING_DB_PASSWORD:
- vault: secret/myproject/staging/db/password@secrets # authenticates using $VAULT_ID_TOKEN
+ vault: myproject/staging/db/password@secret # translates to a path of 'secret/myproject/staging/db' and field 'password'. Authenticates using $VAULT_ID_TOKEN.
script:
- access-staging-db.sh --token $STAGING_DB_PASSWORD
```
@@ -348,9 +349,9 @@ job_with_secrets:
In this example:
- `id_tokens` - The JSON Web Token (JWT) used for OIDC authentication. The `aud` claim
- is set to match the `bound_audiences` parameter of the Vault JWT authentication method.
-- `@secrets` - The vault name, where your Secrets Engines are enabled.
-- `secret/myproject/staging/db` - The path location of the secret in Vault.
+ is set to match the `bound_audiences` parameter of the `role` used for the Vault JWT authentication method.
+- `@secret` - The vault name, where your Secrets Engines are enabled.
+- `myproject/staging/db` - The path location of the secret in Vault.
- `password` The field to be fetched in the referenced secret.
If more than one ID token is defined, use the `token` keyword to specify which token should be used. For example:
@@ -423,3 +424,18 @@ The secrets provider can not be found. Check your CI/CD variables and try again.
The job can't be created because the required variable is not defined:
- `VAULT_SERVER_URL`
+
+### `api error: status code 400: missing role` error
+
+You might receive a `missing role` error when attempting to start a job configured to access HashiCorp Vault.
+The error could be because the `VAULT_AUTH_ROLE` variable is not defined, so the job cannot authenticate
+with the vault server.
+
+### `audience claim does not match any expected audience` error
+
+If there is a mismatch between values of `aud:` claim of the ID token specified in the YAML file
+and the `bound_audiences` parameter of the `role` used for JWT authentication, you can get this error:
+
+`invalid audience (aud) claim: audience claim does not match any expected audience`
+
+Make sure these values are the same.
--
GitLab