Harness CIプラグイン

Harness CIにおけるKeeperシークレットマネージャー連携による動的シークレット取得

機能

• Harness CIパイプライン内でKeeperボルトからシークレットを取得

• Harness CIパイプラインのビルド引数としてシークレット認証情報を設定

• Keeperボルトからセキュアファイルをコピー

• プラグインURL： https://plugins.drone.io/plugins/keeper-plugin

Keeperシークレットマネージャーの機能一覧は 概要 をご参照ください。

要件

Keeperシークレットマネージャーの要件

要件	説明
KSMアクセス	Keeperシークレットマネージャーの有効なサブスクリプションが必要です (クイックスタートガイド)
アドオン有効化	Keeperアカウントでシークレットマネージャーアドオンが有効になっていること
ロール所属	シークレットマネージャー適用ポリシーが有効なロールのメンバーであること
KSMアプリケーション	シークレットが共有された Keeperシークレットマネージャー アプリケーションが構成済みであること
KSM構成	初期化済みの 構成 (Base64トークン、ワンタイムアクセストークン、またはJSON構成ファイルのいずれか)

Harness CIの要件

• 有効なHarness アカウント があることです

• Harness CI のパイプラインが設定されていることです

• Harness CIの シークレット管理 を理解していることです

• Keeperプラグイン がインストールされていることです

構成の種類

プラグインは3つの認証方式をサポートします。セキュリティ要件に合わせて選択してください。

種類	Harnessのシークレット種別	用途
ワンタイムアクセストークン (OTAT)	テキストシークレット	使い捨て、最高のセキュリティ
Base64トークン	テキストシークレット	再利用可、標準的なセキュリティ
JSON構成ファイル	ファイルシークレット	完全な構成、再利用可

セットアップ手順

手順1. Keeperボルトの構成

1. Keeperボルトに 共有フォルダ を作成します。

2. 共有フォルダ内にシークレットを含む レコードを作成 します。

3. シークレットマネージャーの アプリケーション を作成します。

4. 希望する認証情報の種類を生成します。

   • ワンタイムアクセストークン (OTAT)

   • Base64 トークンまたはJSON 構成

手順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] をクリックします。

注意： ワンタイムアクセストークンは1回限りの利用です。パイプライン実行ごとに新しいトークンを生成してください。

オプションB：Base64トークン (テキストシークレット)

1. [+ New Secret → Text] をクリックします。

2. 次のとおり設定します。

   • [Secret Name]: keeper_base64_secret

   • [Secret Value]: Base64エンコードされたトークンを貼り付けます。

   • [Scope]: [Project] (推奨)

3. [Save] をクリックします。

注意： Base64文字列に改行や空白が入らないようにしてください。

オプションC：JSON構成ファイル (ファイルシークレット)

1. [+ New Secret] → [File] をクリックします。

2. 次のとおり設定します。

   • [Secret Name]: keeper_ksm_config_file

   • [Upload File]: KSMのJSON構成ファイルを選択します。

   • [Scope]: [Project] (推奨)

3. [Save] をクリックします。

想定されるJSONの構造は次のとおりです。

{
  "hostname": "keepersecurity.com",
  "clientId": "your-client-id",
  "privateKey": "your-private-key"
}

手順3：パイプラインでの参照

シークレットは次の構文で参照します。

settings:
  ksm_config: <+secrets.getValue("your_secret_identifier_name")>

クイックスタート

パイプラインの例

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

重要： RECORD_UID はKeeperボルトの実際のレコードUIDに置き換えてください。

パイプライン実行が完了すると、シークレットを出力する手順のログで内容を確認できます。

シークレットの設定

Keeper表記法の構文

secrets 入力は、取得するシークレットを指定するためにKeeper表記法を用います。

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_uid>/<selector>/<field_name> > <destination_name>

要素	説明
record_uid	Keeperレコードの一意の識別子です。
selector	データの種類です。field、custom_field、file のいずれかです。
field_name	取得するフィールドまたはファイルの名前です。
destination_name	/harness/secrets/ 内の出力ファイル名です。

セレクターの種類

セレクター	説明	出力先
field	標準のレコードフィールド (ログイン、パスワードなど)です。	/harness/secrets/<destination>
custom_field	レコードに定義されたカスタムフィールドです。	/harness/secrets/<destination>
file	ファイル添付です。	/harness/secrets/<destination>

例

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

ヒント： 配列やキーと値のペアなど複雑な値については、Keeper表記法 の述語 (Predicates) のドキュメントをご参照ください。

ローカルDockerランナーの構成

Harness Cloudではなく runtime: type: docker (ローカルランナー)を使う場合、ローカル上のパイプライン間で データ を共有するには 共有パス を設定する必要があります。

spec:
  cloneCodebase: false
  platform:
    os: Linux
    arch: Amd64
  runtime:
    type: docker
    spec: {}
  sharedPaths:
    - /harness
  execution:
    steps:
      # ... your steps

理由： Harness Cloudでは /harness が自動的に共有されます。ローカルDockerでは sharedPaths を明示的に設定する必要があります。

セキュリティのベストプラクティス

項目	説明
ワンタイムアクセストークンの利用	可能な限りパイプライン実行ごとに新しいトークンを生成します
シークレットファイルの削除	パイプラインの手順で利用後にシークレットファイルを削除します
適切なスコープ	より広いアクセスが不要な限りプロジェクトレベルのスコープを使います
アクセスの制限	パイプラインを編集できるユーザーを制限します (編集者はシークレットを読み取れる可能性があります)

シークレットのマスキング (ログからの隠蔽)

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ランナーの構成を参照)

デバッグ：プラグイン出力の確認

プラグインの直後にデバッグ用の手順を追加します。

- 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 へのマッピング)