Puppet

Puppetカタログ実行でシークレットにアクセスするためのKeeperシークレットマネージャーモジュール

概要

Puppetは、IT環境全体で一貫性と拡張性のある構成管理を実現する強力なインフラ自動化プラットフォームです。Infrastructure as Code (IaC)、自動プロビジョニング、DevOpsプロセスにおける継続的コンプライアンスを支援します。

このモジュールは、PuppetとKeeperシークレットマネージャーを安全に統合し、カタログ実行時にシークレットを取得できるようにします。

機能

• カタログ実行時にPuppetでKeeperボルト内のシークレットを使用可能

• Base64、JSON、トークン認証構成をサポート

• シークレット出力をJSONレスポンス、ファイル、環境変数に対応

要件

• Keeperシークレットマネージャーへのアクセス (詳細はクイックスタートガイドを参照)

• Keeperのサブスクリプションでシークレットマネージャーアドオンが有効になっていること

• シークレットマネージャーポリシーが有効なロールに所属していること

• シークレットが共有されているKeeperシークレットマネージャーアプリケーション (アプリケーション作成手順はクイックスタートガイドを参照)

• Keeperシークレットマネージャー構成が初期化されていること

• PuppetモジュールはBase64、トークン、JSON形式の構成を受け付けます

システム要件

• Puppet: 7.24以降 (preprocess_deferredをサポート)

• Python: 3.6以降 (エージェントノード上)

• 対応OS: Linux、macOS、Windows

重要な構成

必須: エージェントの puppet.conf に次の設定を追加してください。

[agent]
preprocess_deferred = false

この設定により、遅延関数がカタログ適用中に実行され、事前に実行されないようになります。

シークレット表記法

フォーマット

表記は "KEEPER_NOTATION > OUTPUT_SPECIFICATION" という形式を取ります。

• 左側: Keeper表記法を使用

• 右側: 出力仕様

  • VARIABLE_NAME (例: Label2)

  • env:VARIABLE_NAME (例: env:Label2)

  • file:/path/to/file-on-agent (例: file:/opt/ssl/cert.pem)

表記	デフォルト (空)	env:	file:
field または custom_field	表記クエリの結果はJSON出力に配置される	表記クエリの結果はエージェント上の環境変数としてエクスポートされる	許可されていない
file	ファイルがダウンロードされ、エージェントの指定先に配置される	ファイルがダウンロードされ、エージェントの指定先に配置される	ファイルがダウンロードされ、エージェントの指定先に配置される

例

1. デフォルト (空)

"UID/custom_field/Label1 > Label2"
# 出力JSON: { "Label2": "VALUE_HERE" }

1. 環境変数出力 (env:)

"secret-uid/field/password > env:DB_PASSWORD"
# エージェントノード上で DB_PASSWORD 環境変数を設定
# 注意: env:DB_PASSWORD は環境変数としてエクスポートされ、DB_PASSWORD は出力JSONに含まれない

1. ファイル出力 (file:)

"secret-uid/file/ssl_cert.pem > file:/opt/ssl/cert.pem"
# エージェントノード上の指定パスにファイルをダウンロード
# 出力JSON: { "ssl_cert.pem": "/opt/ssl/cert.pem" }
# 注意: ファイル名がキーとなり、エージェント上のファイルパスが値となる

セットアップ

手順1: モジュールのインストール

Puppet Forgeからインストールします。

puppet module install keepersecurity-keeper_secrets_manager_puppet

手順2: Hieraの設定

Hiera構成ファイルを作成または更新します (例: data/common.yaml)。

構成の構造

基本構成 (必須)

YAML

keeper::config:
  authentication:
    - "AUTH_TYPE"    # 認証タイプ (base64、token、json のいずれか)
    - "AUTH_VALUE"   # 認証情報 または ENV:KEEPER_CONFIG を指定

JSON

シークレットの追加 (任意)

これらのシークレットは、パラメータータイプとして Default Lookup が使用された場合に取得されます。

YAML

keeper::config:
  authentication:
    - "AUTH_TYPE"     # 認証タイプ (base64、token、json のいずれか)
    - "AUTH_VALUE"    # 認証情報 または ENV:KEEPER_CONFIG を指定
  secrets:            # 任意: 取得するシークレットのリスト
    - "your-secret-uid/title > title"                  # レコードのタイトルを title に出力
    - "your-secret-uid/field/login > login_name"       # ログインフィールドを login_name に出力
    - "your-secret-uid/field/password > env:DB_PASSWORD" # パスワードを DB_PASSWORD 環境変数に設定

JSON

構成の詳細

• keeper::config (必須): メインの構成コンテナ

• authentication (必須): 要素数2の配列

  • [0]: 認証タイプ (base64、token、json)

  • [1]: 認証値 (認証情報か ENV:VARIABLE_NAME)

• secrets (任意): シークレット表記法文字列の配列

secrets配列は、keeper::config の下に記述しなくてもかまいません。 Deferred('keeper_secrets_manager_puppet::lookup', [SECRETS_ARRAY_HERE]) 関数呼び出しで、secrets配列または単一のシークレットを直接パラメータとして渡すことができます。

手順3: 環境変数の設定 (任意)

AUTH_VALUE に ENV:KEEPER_CONFIG を使用する場合、Puppetマスターに環境変数を設定してください。

# base64認証の場合 (推奨)
echo "KEEPER_CONFIG='your-base64-string-configuration'" >> /etc/environment

# トークン認証の場合
echo "KEEPER_CONFIG='your-token-configuration'" >> /etc/environment

# JSON認証の場合
echo "KEEPER_CONFIG='your-json-configuration-path-on-master'" >> /etc/environment

環境変数を公開する際、KEEPER_CONFIG を使用せずに独自の環境変数名を指定することもできます。

使用方法

モジュールを含める

# マニフェストにモジュールを含める
contain keeper_secrets_manager_puppet

実行時に遅延実行されるカスタムルックアップ関数

このモジュールには keeper_secrets_manager_puppet::lookup というカスタム関数が用意されており、Puppetの Deferred() ラッパーと組み合わせて実行時に使用する必要があります。 詳細については「関数を遅延させる」をご参照ください。

Deferred('keeper_secrets_manager_puppet::lookup', []) 関数は3種類のパラメーターオプションを受け付けます。

パラメータタイプ	説明	例
パラメータなし	Hiera構成からシークレットを使用	Deferred('keeper_secrets_manager_puppet::lookup', [])
配列[文字列]	パラメーターからシークレットを使用	Deferred('keeper_secrets_manager_puppet::lookup', [$secrets_array])
文字列	パラメーターからシークレットを使用	Deferred('keeper_secrets_manager_puppet::lookup', ['UID/field/login > login_name'])

詳細な例

オプション1: デフォルトルックアップ (パラメーターなし)

# Hiera構成で定義されたシークレットを使用
$secrets = Deferred('keeper_secrets_manager_puppet::lookup', [])

オプション2: 文字列配列

# シークレット配列を定義
$secrets_array = [
  'UID/custom_field/Label1 > Label2',
  'UID/field/login > agent2_login',
  'UID/field/password > env:agent2_password',
  'UID/file/ssl_cert.pem > file:/etc/ssl/certs/agent2_ssl_cert.pem',
]

$secrets = Deferred('keeper_secrets_manager_puppet::lookup', [$secrets_array])

オプション3: 単一文字列

# 単一シークレットをルックアップ
$secrets = Deferred('keeper_secrets_manager_puppet::lookup', ['UID/field/login > agent2_login'])

完全な例

node 'puppetagent' {
  # keeperモジュールを含める
  contain keeper_secrets_manager_puppet

  # 取得するシークレットを定義
  $secrets = [
    'UID/custom_field/Label1 > Label2',
    'UID/field/login > agent2_login',
    'UID/field/password > env:agent2_password',
    'UID/file/ssl_cert.pem > file:/etc/ssl/certs/agent2_ssl_cert.pem',
  ]

  # 遅延関数を使ってシークレットを取得
  $secrets_result = Deferred('keeper_secrets_manager_puppet::lookup', [$secrets])
  
  # JSONレスポンスから個別の値にアクセス
  $agent2_login_value = Deferred('dig', [$secrets_result, 'agent2_login'])

  # 取得したシークレットを利用
  notify { 'Retrieved secrets':
    message => $agent2_login_value,
  }

  # モジュールによって設定された環境変数を利用
  exec { 'create_file_with_secret':
    command => '/bin/echo $agent2_password > /tmp/secret.txt',
    path    => ['/bin', '/usr/bin'],
  }
}

トラブルシューティング

デバッグモード

Puppet構成でログレベルを設定してデバッグログを有効化します。

[agent]
log_level = debug

よくある問題

1. "preprocess_deferred = false" エラー

• 問題: 構成エラーでモジュールが失敗する

• 解決策: puppet.conf の [agent] セクションに以下を追加します。

[agent]
preprocess_deferred = false

2. "KSM script not found" エラー

• 問題: 初回実行で Deferred 関数が失敗する

• 解決策: モジュールが正しく含まれていること、Pythonのインストールが完了していることを確認します。

1. 認証エラー

• 問題: "Authentication failed" や Error: access_denied, message=Unable to validate Keeper application access が発生する

• 解決策: 構成内のKeeper認証情報を再確認し、ネットワーク接続を確認します。