ツイートシェアはてブ LINE Pocket

HashiCorp ボールトの統合

HashiCorp Vault(英語) は、トークン、パスワード、証明書、暗号化キーを安全に保管するためのストレージです。TeamCity パラメーターとトークン内に機密情報を保存する代わりに、機密情報を Vault に保持し、Vault エンジン (KV/KV2、AWS、Google Cloud など) からこのデータに安全にアクセスできるように TeamCity を設定できます。

TeamCity-Vault 統合をセットアップするには、公式ボールトプラグイン(英語)をダウンロードし、追加のプラグインをインストールするの記事の説明に従ってインストールします。

共通情報

HashiCorp Vault との統合を設定するには、次のものが必要です。

必要なプロジェクトの HashiCorp Vault 接続 (または、TeamCity プロジェクトでこの接続を使用する場合は <ルートプロジェクト>)。
必要なシークレットへの Vault パスを保存するパラメーター。
ビルドステップ (たとえば、terraform apply -var password=%myVaultParam% 行を実行するコマンドラインランナー) 内でのこのパラメーター (%parameter_name%) への参照。

このパラメーターを使用するビルドが開始されると、TeamCity サーバーは Vault 接続を使用してワンタイムレスポンスラッピングトークン(英語)を要求し、それをこのビルドを実行する TeamCity エージェントに渡します。ビルドエージェントは、このトークンを使用して Vault シークレットを要求し、取得した資格情報を TeamCity サーバーと共有することはありません。ビルドが完了すると、エージェントのトークンは取り消されます。

ボールト接続のセットアップ

管理 | <あなたのプロジェクト> | 接続に移動し、接続の追加をクリックします。
接続タイプとして HashiCorp Vault を選択します。
基本的な接続設定 (接続名、Vault およびパラメーターの名前空間、および Vault URL) を指定します。
- ボールトの名前空間(英語)を使用すると、「ボールト内にボールト」、つまり単一の Vault Enterprise インスタンス内に分離されたテナントを作成できます。この分離環境に Vault シークレットを保存する場合は、ボールトの名前空間接続フィールドにその名前空間を指定します (たとえば、TeamABC/secrets/)。それ以外の場合は、この設定を空のままにしておきます。
- パラメーターの名前空間は、この Vault 接続を識別するカスタム文字列です。複数の Vault 接続を設定し、特定のパラメーターでどの接続を使用するかを指定する場合は、このフィールドを指定できます。それ以外の場合は、このフィールドを空白のままにしておきます。
- ボールトの URL は、Vault インスタンスのアドレスです。ローカル Vault インストール (デフォルトの URL は http://localhost:8200) もサポートされています。

必要な認証方法を選択します。TeamCity は、Vault の AppRole、AWS IAM ロール、またはディレクトリアクセスプロトコル (LDAP) を使用して HCP Vault に対して認証できます。

この認証方法では、Vault インスタンスで AppRole 認証方法を有効にし、AppRole を作成する必要があります。AppRoles は、ユーザー (この場合は TeamCity) がアクセスできるシークレットを指定する Vault ポリシーのセットです。

Vault AppRole 認証方法では、次の設定を行う必要があります。

AppRole 認証エンドポイントパス — AppRole 認証エンドポイントがマウントされている Vault インスタンス内のパス。デフォルトのパスは approle (前にバックスラッシュ文字は付きません) です。
AppRole ロール ID および AppRole シークレット ID — これらの値は、次のコマンドを使用して CLI で取得できます。

vault read -field=role_id auth/<AE>/role/<RN>/role-id vault write -f -field=secret_id auth/<AE>/role/<RN>/secret-id

ここで、<AE> は上で指定した認証エンドポイントパス ( approle など)、<RN> はロールの名前 ( my-teamcity-role など) です。

AppRoles オンラインドキュメント: ポリシー(英語)、AppRole の認証方法(英語)の作成および設定方法については、Vault ドキュメントの記事を参照してください。

このメソッドは、LDAP 認証方式(英語)が有効になっている Vault インスタンスに使用できます。この認証オプションにはユーザー名とパスワードが必要です。パス設定には、LDAP 認証エンドポイントへのパス (たとえば、デフォルトの auth/ldap/users/userA および auth/ldap/groups/groupB エンドポイントの場合は ldap) が保存されます。

Vault でのこの認証方法の設定の詳細については、この記事を参照してください: LDAP 認証方式(英語)。

エージェントが Vault シークレットを取得して TeamCity パラメーターに書き込むことができない場合に、「HashiCorp Vault からデータをフェッチ中にエラーが発生しました」というメッセージが表示されてビルドが失敗するようにするには、エラーの場合は失敗にチェックを入れます。これらのパラメーターがまったく使用されない場合でも、ビルドは失敗することに注意してください。この設定が無効になっている場合、ビルドはシークレットパラメーター値として空の文字列を使用して実行を継続します。

Kotlin DSL:

project {

    features {
        hashiCorpVaultConnection {
            id = "PROJECT_EXT_34"
            name = "HashiCorp Vault"
            url = "http://127.0.0.1:8200/"
            vaultNamespace = "enterprise/vault/namespace"
            authMethod = appRole {
                roleId = "..."
                secretId = "..."
            }
            failOnError = false
        }
    }
}

パラメーターの作成と設定

ビルドで HCP Vault のシークレット値の使用を開始するには、次の 2 つの目的を果たすパラメーターを作成します。

値を取得する必要がある Vault シークレットへのパスを保存します
Vault が提供した後にシークレット値を保存します

このようなパラメーターを作成するには、次の手順を実行します。

管理 | <プロジェクトまたはビルド構成> | パラメーターに移動し、新規パラメーターを追加をクリックしてください。
有効なボールト接続を持つプロジェクトに対してのみパラメーターを設定できます (または親プロジェクトから継承します)。
環境変数型を選択し、パラメーター名を入力します。例: env.AWS_ACCESS_KEY_ID
「仕様」ラベルの横にある編集 ... をクリックし、次の値を設定します。
- タイプ : リモート
- リモート接続タイプ : HashiCorp ボールトパラメーター
- パラメーターの名前空間 : 使用するボールト接続と同じ値を選択します。
  デフォルトの名前空間 (空) を選択して、パラメーターの名前空間フィールドが空の接続を選択します。
- ボールトクエリ : path!/key 形式のシークレットへのパス。例: 次の文字列は、パラメーターが KV2 エンジンに保存されている「awscreds」シークレットの「access_key」キーを指します: secret/data/awscreds!/access_key
ダイアログを閉じるには保存をクリックしてください。

Kotlin DSL:

project {
    params {
        hashiCorpVaultParameter {
            name = "env.AWS_ACCESS_KEY_ID"
            query = "secret/data/awscreds!/access_key"
            namespace = "DataLore"
        }
    }
}

レガシーパラメーターの更新

2023.11 バージョンよりも前に TeamCity Vault プラグインをすでに使用していた場合は、仕様がなく、Vault シークレットへのパスがパラメーター値 (%\vault:PATH!/KEY% 形式) に直接保存されているレガシーパラメーターがある可能性があります。

これらの従来のパラメーターと比較して、新しい「リモートパラメーター」には次の利点があります。

ボールトパスはパラメーター spec に保存されるため、値フィールドはデフォルト / 初期パラメーター値用に空きのままになります。
シークレットパス (クエリ) は、vault: プレフィックスのない、より単純な形式を使用します。

さらに、動的シークレットを発行する Vault エンジン (AWS エンジンなど) は、クライアント (TeamCity) が新しいリクエストを送信するたびに新しい認証情報を生成します。そのため、同じビルド内で同じ動的シークレットエンジンにアクセスするレガシーパラメーターとリモートパラメーターを混合しないようにする必要があります。

例: Vault AWS エンジンからアクセスキー ID を取得するリモートパラメーターと、対応するシークレットアクセスキーを取得するレガシーパラメーターがある場合、TeamCity はパラメーターごとに個別のリクエストを送信します。エンジンは 2 セットの値を発行するため、ID/ シークレットのペアは不一致になります。

既存のレガシーパラメーターをリモートの対応するパラメーターに更新することをお勧めします。

Kotlin DSL

Kotlin DSL では、従来の Vault パラメーターを新しい型に更新できます。従来の Vault パラメーターは次のように宣言されます。

project {
    params {
        param("env.AWS_ACCESS_KEY_ID", "%\vault:secret/data/awscreds!/access_key%")
    }
}

これらのパラメーターを更新するには、次のブロックに置き換えます。

project {
    params {
        hashiCorpVaultParameter {
            name = "env.AWS_ACCESS_KEY_ID"
            query = "secret/data/awscreds!/access_key"
        }
    }
}

元のパラメーター値とは異なり、新しいパラメーターの query フィールドには vault: プレフィックスもパーセント文字も含まれないことに注意してください。

従来のパラメーターが %\vault:foobar:/path!/key% 形式の場合、「foobar」部分は、このパラメーターがシークレットを取得するためにどの Vault 接続を使用するかを識別します。この値をリモートパラメーターの namespace フィールドに移動します。

project {
   params {
      hashiCorpVaultParameter {
         name = "parameter name"
         query = "path!/key"
         namespace = "foobar"
      }
   }
}

最終更新日: 2023 年 11 月 22 日

TeamCity オンプレミス 2023.11 ヘルプ