Интеграция с внешним Vault

Эта функция позволяет настроить интеграцию с Vault-сервером и использовать секреты в CI-пайплайнах. Перед началом работы необходимо настроить Vault-сервер и подготовить соответствующие роли и политики.

Настройка Vault

1. Включите аутентификацию через JWTT:

   vault auth enable jwt
   
   vault write auth/jwt/config \
     oidc_discovery_url="https://code.example.com" \
     bound_issuer="https://code.example.com" \
     default_role="gitlab-role"
   

2. Создайте роль:

   vault write auth/jwt/role/gitlab-role - <<EOF
   {
     "role_type": "jwt",
     "user_claim": "sub",
     "bound_audiences": ["vault"],
     "bound_claims": {
       "project_id": "23"
     },
     "policies": ["gitlab-policy"],
     "ttl": "1h"
   }
   EOF
   

   Всегда используйте bound_claims, чтобы ограничить доступ к роли. Без этого любой JWT, выданный платформой, сможет получить доступ с этой ролью.

3. Настройте политики:

   vault policy write gitlab-policy - <<EOF
   path "kv/data/code/vault-demo" {
     capabilities = ["read"]
   }
   EOF
   

Конфигурация CI

Переменные окружения

Для корректной работы с Vault в пайплайне CI/CD необходимо задать следующие переменные окружения:

• VAULT_SERVER_URL — обязательно. URL-адрес Vault-сервера (например, https://vault.example.com).
• VAULT_AUTH_ROLE — опционально. Название роли в Vault. Если не указано, будет использована роль по умолчанию, заданная в конфигурации метода аутентификации.
• VAULT_AUTH_PATH — опционально. Путь до метода аутентификации в Vault. По умолчанию используется jwt.
• VAULT_NAMESPACE — опционально. Namespace Vault, если используется многоуровневая иерархия.

Использование секретов в CI

Для получения секретов из Vault можно использовать следующий шаблон job’а:

stages:
  - test
vault-login:
  stage: test
  image: ruby:3.2
  id_tokens:
    VAULT_ID_TOKEN:
      aud: vault
  secrets:
    DATABASE_PASSWORD:
      vault: code/vault-demo/DATABASE_PASSWORD@kv
      token: $VAULT_ID_TOKEN
  script: echo $DATABASE_PASSWORD

Параметры секрета

Пример:

DATABASE_PASSWORD:
  vault: code/vault-demo/DATABASE_PASSWORD@kv
  token: $VAULT_ID_TOKEN
  file: false

Описание параметров:

1. vault (обязательно) — путь к секрету в формате строки path/to/secret/KEY@ENGINE, где:
   • code/vault-demo/ — путь до секрета в Vault;
   • DATABASE_PASSWORD — имя поля внутри секрета;
   • kv — точка монтирования Secret Engine (по умолчанию — secret).

По умолчанию используется engine kv-v2. Если необходимо использовать другой engine, можно указать объект вместо строки:

DATABASE_PASSWORD:
  vault: 
    path: code/vault-demo
    field: DATABASE_PASSWORD
    engine:
      name: 'kv-v1'
      path: 'kv1'
  token: $VAULT_ID_TOKEN
  file: false

1. token (обязательно) — JWT-токен из секции id_tokens, используемый для аутентификации в Vault.

2. file (опционально, по умолчанию true) — определяет способ предоставления секрета:

   • true — секрет сохраняется во временный файл;
   • false — секрет передаётся как строка в переменную окружения.

Поля, включённые в JWT

Следующие поля автоматически включаются в JWT-токен и могут использоваться Vault для проверки прав доступа: