GitLab CI/CDでAWS Secrets Managerシークレットを使用する

プラン: Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLab継続的インテグレーションとデリバリーパイプラインで、AWS Secrets Managerに保存されているシークレットを使用できます。

前提要件:

AWSアカウントのAWS Secrets Managerにアクセスできる必要があります。
次のいずれかの方法で認証を設定します:
- IAM Role（IAMロール）: GitLab Runnerインスタンスに割り当てられたIAMロールを使用します。
- OpenID Connect: 一時的な認証情報を取得するには、AWSでOpenID Connectを設定します。
AWSの設定に関する詳細を提供するには、プロジェクトにCI/CD変数を追加します:
- AWS_REGION: シークレットが保存されているAWSリージョン。
- AWS_ROLE_ARN: OpenID Connectを使用する場合に必要となる、引き受けるAWS IAMロールのAmazonリソースネーム。
- AWS_ROLE_SESSION_NAME: オプション。引き受けられたロールのカスタムセッション名。

CI/CDジョブでAWS Secrets Managerシークレットを使用する

IAMロール認証を使用

aws_secrets_managerキーワードで定義することにより、ジョブでAWS Secrets Managerに保存されているシークレットを使用できます。この方法では、GitLab Runnerインスタンスに割り当てられたIAMロールを使用します。

前提要件:

GitLab Runner 18.3バージョン以降。

例:

variables:
  AWS_REGION: us-east-1

database-migration:
  secrets:
    DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: app-secrets/database
        field: 'password'
      file: false
  stage: deploy
  script:
    - echo "Running database migration..."
    - mysql -h $DB_HOST -u $DB_USER -p$DATABASE_PASSWORD < migration.sql
    - echo "Migration completed successfully."

OpenID Connect認証を使用

セキュリティを強化するために、OpenID Connectを使用してAWSで認証を行い、特定のIAMロールを引き受けることができます。デフォルトでは、RunnerはAWS_ID_TOKENという名前のIDトークンを検索します。例:

variables:
  AWS_REGION: us-east-1
  AWS_ROLE_ARN: 'arn:aws:iam::123456789012:role/gitlab-secrets-role'

database-migration:
  id_tokens:
    AWS_ID_TOKEN:
      aud: 'sts.amazonaws.com'
  secrets:
    DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: app-secrets/database
        field: 'password'
      file: false
  stage: deploy
  script:
    - echo "Connecting to production database..."
    - psql postgresql://$DB_USER:$DATABASE_PASSWORD@$DB_HOST:5432/$DB_NAME -c "SELECT version();"
    - echo "Database connection successful."

tokenオプションを使用して、カスタムトークンを指定することもできます。例:

variables:
  AWS_REGION: us-east-1
  AWS_ROLE_ARN: 'arn:aws:iam::123456789012:role/gitlab-secrets-role'

database-migration:
  id_tokens:
    CUSTOM_AWS_TOKEN:
      aud: 'sts.amazonaws.com'
  secrets:
    DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: app-secrets/database
        field: 'password'
      token: $CUSTOM_AWS_TOKEN
      file: false
  stage: deploy
  script:
    - echo "Connecting to production database with custom token..."
    - psql postgresql://$DB_USER:$DATABASE_PASSWORD@$DB_HOST:5432/$DB_NAME -c "SELECT version();"
    - echo "Database connection successful."

短い形式の構文

シークレットIDを文字列として指定することにより、簡略化された構文を使用できます。オプションで、#文字で区切ってフィールドを指定できます。例:

variables:
  AWS_REGION: us-east-1

api-deployment:
  secrets:
    API_KEY:
      aws_secrets_manager: 'app-secrets/api#api_key'
      file: false
    FULL_SECRET:
      aws_secrets_manager: 'app-secrets/api'
      file: false
  stage: deploy
  script:
    - echo "Deploying API with specific field..."
    - curl --header "Authorization: Bearer $API_KEY" https://api.example.com/deploy
    - echo "Using full secret..."
    - curl --header "Authorization: Bearer $(cat $FULL_SECRET | jq --raw-output '.api_key')" https://api.example.com/status

シークレットのバージョニング

AWS Secrets Managerは、シークレットの複数のバージョンをサポートしています。version_idまたはversion_stageのいずれかを使用して、特定のバージョンを指定できます。例:

variables:
  AWS_REGION: us-east-1

production-deployment:
  secrets:
    DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: prod-app-secrets/database
        field: 'password'
        version_stage: 'AWSCURRENT'
      file: false
    STAGING_DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: prod-app-secrets/database
        field: 'password'
        version_id: '01234567-89ab-cdef-0123-456789abcdef'
      file: false
  stage: deploy
  script:
    - echo "Deploying to production with current secret version..."
    - deploy-prod.sh --db-password $DATABASE_PASSWORD
    - echo "Testing with specific secret version..."
    - test-with-version.sh --db-password $STAGING_DATABASE_PASSWORD

クロスアカウントシークレットアクセス

別のAWSアカウントからシークレットを取得するには、完全なAmazonリソースネームを使用する必要があります。例:

variables:
  AWS_REGION: us-east-1
  AWS_ROLE_ARN: 'arn:aws:iam::123456789012:role/cross-account-secrets-role'

cross-account-deployment:
  id_tokens:
    AWS_ID_TOKEN:
      aud: 'sts.amazonaws.com'
  secrets:
    SHARED_API_KEY:
      aws_secrets_manager:
        secret_id: 'arn:aws:secretsmanager:us-east-1:987654321098:secret:shared-api-keys-AbCdEf'
        field: 'production_key'
      file: false
  stage: deploy
  script:
    - echo "Accessing shared secret from another account..."
    - curl --header "Authorization: Bearer $SHARED_API_KEY" https://shared-api.example.com/deploy

シークレットごとの設定のオーバーライド

シークレットごとに、グローバルなAWS設定をオーバーライドできます。例:

variables:
  AWS_REGION: us-east-1
  AWS_ROLE_ARN: 'arn:aws:iam::123456789012:role/default-role'

multi-region-deployment:
  id_tokens:
    AWS_ID_TOKEN:
      aud: 'sts.amazonaws.com'
    EU_AWS_TOKEN:
      aud: 'sts.amazonaws.com'
  secrets:
    EU_DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: eu-app-secrets/database
        field: 'password'
        region: 'eu-west-1'
        role_arn: 'arn:aws:iam::123456789012:role/eu-deployment-role'
        role_session_name: 'gitlab-eu-deployment'
      token: $EU_AWS_TOKEN
      file: false
    US_DATABASE_PASSWORD:
      aws_secrets_manager:
        secret_id: us-app-secrets/database
        field: 'password'
      file: false
  stage: deploy
  script:
    - echo "Deploying to EU region..."
    - deploy-to-eu.sh --db-password $EU_DATABASE_PASSWORD
    - echo "Deploying to US region..."
    - deploy-to-us.sh --db-password $US_DATABASE_PASSWORD

これらの例では:

aud: オーディエンス。フェデレーションアイデンティティおよびアクセス管理 () 認証情報の作成時に使用するオーディエンスと一致する必要があります。
secret_id: AWS Secrets Manager内のシークレットの名前またはAmazonリソースネーム。別のアカウントからシークレットを取得するには、Amazonリソースネームを使用する必要があります。
field: 取得するJSONシークレット内の特定のキーです。指定されていない場合、シークレット全体が取得されます。フィールドアクセスは、フラットなJSONシークレット（トップレベルのキーのみ）でのみサポートされており、文字列、数値、およびブール値をサポートしています。例:
- password: passwordフィールドにアクセスします。
- api_key: api_keyフィールドにアクセスします。token: 認証に使用するIDトークンを指定します。指定しない場合、RunnerはAWS_ID_TOKENという名前のトークンを検索します。
version_id: シークレットの特定のバージョンの固有識別子です。version_idまたはversion_stageのいずれかを指定しない場合、AWS Secrets ManagerはAWSCURRENTバージョンを返します。
version_stage: 取得するシークレットのバージョンのステージングラベル（AWSCURRENTやAWSPENDINGなど）。同じシークレットに対してversion_idとversion_stageの両方を指定することはできません。
region: この特定のシークレットのグローバルなAWS_REGIONをオーバーライドします。
role_arn: この特定のシークレットのグローバルなAWS_ROLE_ARNをオーバーライドします。
role_session_name: この特定のシークレットのグローバルなAWS_ROLE_SESSION_NAMEをオーバーライドします。
GitLabは、AWS Secrets Managerからシークレットをフェッチし、一時ファイルに値を格納します。このファイルへのパスは、ファイルタイプCI/CD変数と同様に、CI/CD変数に格納されます。

トラブルシューティング

AWSでOIDCをセットアップする際の一般的な問題については、AWSのOIDCのトラブルシューティングを参照してください。