Vault Secrets – Secrets aus Vault in der Pipeline

Die vault-secrets-Komponente ermöglicht es, Secrets sicher aus HashiCorp Vault in GitLab CI/CD Pipelines zu laden. Sie nutzt GitLabs JWT-Authentifizierung und stellt die Secrets als Umgebungsvariablen für nachfolgende Jobs bereit.

Hintergrund

Die Vault-JWT-Konfiguration ist Voraussetzung für diese Komponente. Details zur Einrichtung der JWT-Authentifizierung finden sich unter Vault GitLab JWT Integration.

Funktionsweise

1. Die Komponente läuft in der .pre-Stage (vor allen anderen Jobs)
2. Authentifizierung bei Vault über GitLabs JWT-Token (id_tokens)
3. Für jedes konfigurierte Secret wird der Wert aus Vault gelesen
4. Alle Werte werden als dotenv-Artifact exportiert
5. Nachfolgende Jobs können die Secrets als Umgebungsvariablen nutzen

Einrichtung

Schritt 1: Component einbinden

stages:
  - build
  - deploy

include:
  - component: git.styrion.net/iteas/gitlab-components/vault-secrets@main
    inputs:
      secrets: |
        DB_PASSWORD=secret/data/myapp/database@password
        API_KEY=secret/data/myapp/api@key
        COMPOSER_AUTH=secret/data/myapp/gitlab@composer_auth

Schritt 2: Secrets in Jobs verwenden

Die Secrets stehen in allen nachfolgenden Jobs als Umgebungsvariablen zur Verfügung:

build:
  stage: build
  needs:
    - job: vault-secrets
      artifacts: true
  script:
    - echo "Verwende DB_PASSWORD und API_KEY als Umgebungsvariablen"
    - composer install --no-interaction

Secret-Pfad-Format

Das Format für Secrets ist: VARIABLE_NAME=pfad/zum/secret@feldname

Teil	Beschreibung	Beispiel
VARIABLE_NAME	Name der Umgebungsvariable im Job	DB_PASSWORD
pfad/zum/secret	Vault KV-Pfad zum Secret	secret/data/myapp/database
@feldname	Feldname innerhalb des Secrets	@password

Beispiele:

secrets: |
  # Datenbankpasswort aus dem Feld "password"
  DB_PASSWORD=secret/data/myapp/database@password

  # API-Key aus dem Feld "key"
  API_KEY=secret/data/myapp/api@key

  # Composer-Auth-Token
  COMPOSER_AUTH=secret/data/gitlab/tokens@composer_auth

Konfigurationsoptionen

Input	Beschreibung	Pflicht	Standard
secrets	Mehrzeilige Liste der Secrets (Format: VARIABLE_NAME=pfad@feld)	Nein	(leer)

Technische Details

Eigenschaft	Wert
Stage	.pre (läuft vor allen definierten Stages)
Runner	build-docker01
Image	hashicorp/vault:1.21
Vault URL	https://vault.iteas.cloud
Auth-Pfad	auth/jwt_gitlab/login
Artifact-Typ	dotenv Report (secrets.env)
Artifact-Zugriff	none (nur intern)
Artifact-Ablauf	1 Stunde

Pipeline-Regeln

Die Komponente läuft auf:

• Branch-Pipelines (außer wenn ein Merge Request offen ist – dann wird die MR-Pipeline bevorzugt)
• Tag-Pipelines
• Merge-Request-Pipelines (die auf den Default-Branch zielen)

Vault-Voraussetzungen

Damit die Komponente funktioniert, muss in Vault konfiguriert sein:

1. JWT-Authentifizierung für GitLab (siehe Vault GitLab JWT)
2. KV Secrets Engine mit den entsprechenden Secrets
3. Policy die dem GitLab-Role Lesezugriff auf die Secret-Pfade gewährt:

path "secret/data/myapp/*" {
  capabilities = ["read"]
}

Vollständiges Beispiel

stages:
  - build
  - deploy

include:
  - component: git.styrion.net/iteas/gitlab-components/vault-secrets@main
    inputs:
      secrets: |
        DB_PASSWORD=secret/data/myapp/database@password
        API_KEY=secret/data/myapp/api@key
        DEPLOY_TOKEN=secret/data/myapp/deploy@token

build:
  stage: build
  tags:
    - build-ubuntu-2204-64
  needs:
    - job: vault-secrets
      artifacts: true
  script:
    - echo "Build mit Secrets..."
    - composer install

deploy:
  stage: deploy
  tags:
    - build-ubuntu-2204-64
  needs:
    - job: vault-secrets
      artifacts: true
    - job: build
  script:
    - echo "Deploy mit Token $DEPLOY_TOKEN"
  only:
    - master