# Harness CIプラグイン
### 機能 * Harness CIパイプライン内でKeeperボルトからシークレットを取得 * Harness CIパイプラインのビルド引数としてシークレット認証情報を設定 * Keeperボルトからセキュアファイルをコピー * プラグインURL: {% hint style="info" %} Keeperシークレットマネージャーの機能一覧は [概要](/keeperpam/jp/secrets-manager/overview.md) をご参照ください。 {% endhint %} ### 要件 #### Keeperシークレットマネージャーの要件 | 要件 | 説明 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | KSMアクセス | Keeperシークレットマネージャーの有効なサブスクリプションが必要です ([クイックスタートガイド](/keeperpam/jp/secrets-manager/quick-start-guide.md)) | | アドオン有効化 | Keeperアカウントでシークレットマネージャーアドオンが有効になっていること | | ロール所属 | シークレットマネージャー適用ポリシーが有効なロールのメンバーであること | | KSMアプリケーション | シークレットが共有された[Keeperシークレットマネージャー](/keeperpam/jp/secrets-manager/about/terminology.md)アプリケーションが構成済みであること | | KSM構成 | 初期化済みの[構成](/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md) (Base64トークン、ワンタイムアクセストークン、またはJSON構成ファイルのいずれか) | #### Harness CIの要件 * 有効なHarness[アカウント](https://app.harness.io/auth/#/signin)があること * [Harness CI](https://developer.harness.io/docs/continuous-integration/use-ci/prep-ci-pipeline-components/)のパイプラインが設定されていること * Harness CIの[シークレット管理](https://developer.harness.io/docs/platform/secrets/add-use-text-secrets/)を理解していること * [Keeperプラグイン](https://plugins.drone.io/plugins/keeper-plugin)がインストールされていること ### 構成の種類 プラグインは3つの認証方式をサポートします。セキュリティ要件に合わせて選択します。 | 種類 | Harnessのシークレット種別 | 用途 | | -------------------- | ---------------- | --------------- | | ワンタイムアクセストークン (OTAT) | テキストシークレット | 使い捨て、最高のセキュリティ | | Base64トークン | テキストシークレット | 再利用可、標準的なセキュリティ | | JSON構成ファイル | ファイルシークレット | 完全な構成、再利用可 | ### セットアップ手順 #### 手順1. Keeperボルトの構成 1. Keeperボルトに[共有フォルダ](/enterprise-guide/jp/sharing/folders.md)を作成します。 2. 共有フォルダ内にシークレットを含む[レコードを作成](/enterprise-guide/jp/creating-vault-records.md)します。 3. シークレットマネージャーの[アプリケーション](/keeperpam/jp/secrets-manager/quick-start-guide.md#create-a-secrets-manager-application)を作成します。 4. 希望する認証情報の種類を生成します。 * ワンタイムアクセストークン ([OTAT](/keeperpam/jp/secrets-manager/about/one-time-token.md)) * Base64[トークンまたはJSON](/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md#creating-a-secrets-manager-configuration)構成 #### 手順2. Harness CIのシークレット作成 次の画面に移動します。**\[Project] → \[Project Setup] → \[Secrets] → \[+ New Secret]** **オプションA: ワンタイムアクセストークン (テキストシークレット)** 1. **\[+ New Secret → Text]** をクリックします。 2. 次のとおり設定します。 * **\[Secret Name]:** `keeper_otat_secret` * **\[Secret Value]:** トークンを貼り付けます (例: `US:xxxxx...`) * **\[Scope]:** **\[Project]** (推奨) 3. **\[Save]** をクリックします。 {% hint style="info" %} ワンタイムアクセストークンは1回限りの利用です。パイプライン実行ごとに新しいトークンを生成してください。 {% endhint %} **オプションB: Base64トークン (テキストシークレット)** 1. **\[+ New Secret → Text]** をクリックします。 2. 次のとおり設定します。 * **\[Secret Name]:** `keeper_base64_secret` * **\[Secret Value]:** Base64エンコードされたトークンを貼り付けます。 * **\[Scope]:** **\[Project]** (推奨) 3. **\[Save]** をクリックします。 {% hint style="info" %} Base64文字列に改行や空白が入らないようにしてください。 {% endhint %} **オプションC：JSON構成ファイル (ファイルシークレット)** 1. **\[+ New Secret] → \[File]** をクリックします。 2. 次のとおり設定します。 * **\[Secret Name]:** `keeper_ksm_config_file` * **\[Upload File]:** KSMのJSON構成ファイルを選択します。 * **\[Scope]:** **\[Project]** (推奨) 3. **\[Save]** をクリックします。 想定されるJSONの構造は次のとおりです。 ```json { "hostname": "keepersecurity.com", "clientId": "your-client-id", "privateKey": "your-private-key" } ``` #### 手順3. パイプラインでの参照 シークレットは次の構文で参照します。 ```yaml settings: ksm_config: <+secrets.getValue("your_secret_identifier_name")> ``` ### クイックスタート #### パイプラインの例 ```yaml pipeline: name: harness_keeper_plugin identifier: harness_keeper_plugin projectIdentifier: default_project orgIdentifier: default stages: - stage: name: HkpCI identifier: HkpCI type: CI spec: cloneCodebase: false platform: os: Linux arch: Amd64 runtime: type: Cloud spec: {} execution: steps: - step: type: Plugin name: Fetch_Keeper_Secrets identifier: Fetch_Keeper_Secrets spec: image: keeper/harness-plugin:latest settings: ksm_config: <+secrets.getValue("keeper_base64_secret")> secrets: | RECORD_UID/field/password > PASSWORD RECORD_UID/field/login > USERNAME - step: type: Run name: Use_Secrets identifier: Use_Secrets spec: image: alpine:3.20 shell: Sh command: | if [ -f /harness/secrets/USERNAME ] && [ -f /harness/secrets/PASSWORD ]; then USERNAME=$(cat /harness/secrets/USERNAME) PASSWORD=$(cat /harness/secrets/PASSWORD) echo "Username: $USERNAME" echo "Password retrieved successfully" else echo "Error: Secret files not found" exit 1 fi ``` {% hint style="info" %} `RECORD_UID` はKeeperボルトの実際のレコードUIDに置き換えてください。 {% endhint %} パイプライン実行が完了すると、シークレットを出力する手順のログで内容を確認できます。
### シークレットの設定 #### Keeper表記法の構文 `secrets` 入力は、取得するシークレットを指定するためにKeeper表記法を用います。 ```yaml settings: secrets: | RECORD_UID/field/password > PASSWORD RECORD_UID/field/login > USERNAME RECORD_UID/custom_field/apiKey > API_KEY RECORD_UID/file/certificate.crt > CERT_FILE ``` #### 表記の形式 ``` // > ```
要素説明
record_uidKeeperレコードの識別子
selectorデータの種類です。field、custom_field、file のいずれか
field_name取得するフィールドまたはファイルの名前
destination_name/harness/secrets/ 内の出力ファイル名
#### セレクターの種類
セレクター説明出力先
field標準のレコードフィールド (ログイン、パスワードなど)/harness/secrets/<destination>
custom_fieldレコードに定義されたカスタムフィールド/harness/secrets/<destination>
fileファイル添付/harness/secrets/<destination>
#### 例 ```yaml secrets: | # Standard fields abc123/field/password > DB_PASSWORD abc123/field/login > DB_USERNAME # Custom fields xyz789/custom_field/apiKey > API_KEY xyz789/custom_field/endpoint > API_ENDPOINT # File attachments def456/file/server.crt > SERVER_CERT def456/file/server.key > SERVER_KEY ``` {% hint style="info" %} 配列やキーと値のペアなど複雑な値については、[Keeper表記法](/keeperpam/jp/secrets-manager/about/keeper-notation.md)の述語 (Predicates) のドキュメントをご参照ください。 {% endhint %} ### ローカルDockerランナーの構成 Harness Cloudではなく `runtime: type: docker` ([ローカルランナー](https://developer.harness.io/docs/continuous-integration/use-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure/)) を使う場合、ローカル上のパイプライン間で[データ](https://developer.harness.io/docs/continuous-integration/use-ci/caching-ci-data/share-ci-data-across-steps-and-stages/#share-data-between-steps-in-a-stage)を共有するには[共有パス](https://developer.harness.io/docs/continuous-integration/use-ci/prep-ci-pipeline-components/#shared-paths)を設定する必要があります。 ```yaml spec: cloneCodebase: false platform: os: Linux arch: Amd64 runtime: type: docker spec: {} sharedPaths: - /harness execution: steps: # ... your steps ``` {% hint style="info" %} Harness Cloudでは `/harness` が自動的に共有されます。ローカルDockerでは `sharedPaths` を明示的に設定する必要があります。 {% endhint %} ### セキュリティのベストプラクティス
項目説明
ワンタイムアクセストークンの利用可能な限りパイプライン実行ごとに新しいトークンを生成します
シークレットファイルの削除パイプラインの手順で利用後にシークレットファイルを削除します
適切なスコープより広いアクセスが不要な限りプロジェクトレベルのスコープを使います
アクセスの制限パイプラインを編集できるユーザーを制限します (編集者はシークレットを読み取れる可能性があります)
#### シークレットのマスキング (ログからの隠蔽) Harness CIはコンソールに出力されたシークレットをログ上で自動的にマスキングします。ただし次の点に注意してください。 * 隠されるのは出力ログのみです * パイプライン編集者がシークレットを取り出せる可能性があります * 常に最小権限の原則に従ってください ### トラブルシューティング #### よくある問題 | 現象 | 原因 | 対処 | | ------------------------- | ------------------------ | ------------------------------------------------------ | | `KSM config is required` | シークレットが見つからない、または式が誤っている | シークレット名が完全一致しているか確認します (大文字・小文字を区別) | | `Missing required fields` | JSON構成が不完全 | JSONに `hostname`、`clientId`、`privateKey` が含まれることを確認します | | 式が解決されない | シークレットのスコープが一致しない | シークレットのスコープがパイプラインのスコープと一致しているか確認します | | トークンはすでに使用済み | ワンタイムトークンは1回限り | 実行ごとに新しいOTATを生成します | #### 事象: クラウドでは動くがローカルで失敗する **症状:** `Fetch_Keeper_Secrets` は成功しますが、次の手順で `/harness/secrets/` の読み取りに失敗します **原因と対処** 1. **シークレット名の不一致** * プラグインは `> USERNAME` および `> PASSWORD` に書き込みます * Run手順では `/harness/secrets/USERNAME` および `/harness/secrets/PASSWORD` を参照する必要があります 2. **ワークスペースが共有されていない** * ステージのspecに `sharedPaths: /harness` を追加します (ローカルDockerランナーの構成を参照) #### デバッグ: プラグイン出力の確認 プラグインの直後にデバッグ用の手順を追加します。 ```yaml - step: type: Run name: Debug_Secrets spec: image: alpine:3.20 shell: Sh command: | echo "Contents of /harness/secrets:" ls -la /harness/secrets/ || echo "Directory not found" ``` ファイルが表示されない場合は次を確認してください。 * プラグインの設定 (シークレット名) * ワークスペースの共有 (ローカルランナー向け) * `ksm_config` の設定 (`PLUGIN_KSM_CONFIG` へのマッピング) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/harness-ci-plugin.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.