# Puppet

<figure><img src="/files/5Ex7nfsBXJheBFQG9bTW" alt=""><figcaption></figcaption></figure>

## 概要

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` に次の設定を追加してください。

```ini
[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. **デフォルト (空)**

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

2. **環境変数出力 (env:)**

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

3. **ファイル出力 (file:)**

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

## セットアップ

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

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

```bash
puppet module install keepersecurity-keeper_secrets_manager_puppet
```

### 手順2: Hieraの設定

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

### 構成の構造

#### 基本構成 (必須)

{% tabs %}
{% tab title="YAML" %}

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

{% endtab %}

{% tab title="JSON" %}

```json
{
  "keeper::config": {
    "authentication": [
      "AUTH_TYPE",  // 認証タイプ (base64、token、json のいずれか)
      "AUTH_VALUE"  // 認証情報 または ENV:KEEPER_CONFIG を指定
    ]
  }
}

```

{% endtab %}
{% endtabs %}

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

{% hint style="info" %}
これらのシークレットは、パラメータータイプとして `Default Lookup` が使用された場合に取得されます。
{% endhint %}

{% tabs %}
{% tab title="YAML" %}

```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 環境変数に設定
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "authentication": ["AUTH_TYPE", "AUTH_VALUE"],
  "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 環境変数に設定
  ]
}

```

{% endtab %}
{% endtabs %}

#### 構成の詳細

* `keeper::config` (必須): メインの構成コンテナ
* `authentication` (必須): 要素数2の配列
  * `[0]`: 認証タイプ (`base64`、`token`、`json`)
  * `[1]`: 認証値 (認証情報か `ENV:VARIABLE_NAME`)
* `secrets` (任意): シークレット表記法文字列の配列

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

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

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

```bash
# 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

```

{% hint style="info" %}
環境変数を公開する際、`KEEPER_CONFIG` を使用せずに独自の環境変数名を指定することもできます。
{% endhint %}

## 使用方法

### モジュールを含める

```puppet
# マニフェストにモジュールを含める
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: デフォルトルックアップ (パラメーターなし)

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

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

```puppet
# シークレット配列を定義
$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: 単一文字列

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

## 完全な例

```puppet
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構成でログレベルを設定してデバッグログを有効化します。

```ini
[agent]
log_level = debug
```

### よくある問題

1\. **"preprocess\_deferred = false" エラー**

* **問題**: 構成エラーでモジュールが失敗する
* **解決策**: `puppet.conf` の `[agent]` セクションに以下を追加します。

```ini
[agent]
preprocess_deferred = false
```

2\. **"KSM script not found" エラー**

* **問題**: 初回実行で Deferred 関数が失敗する
* **解決策**: モジュールが正しく含まれていること、Pythonのインストールが完了していることを確認します。

3. **認証エラー**

* **問題**: `"Authentication failed"` や\
  `Error: access_denied, message=Unable to validate Keeper application access` が発生する
* **解決策**: 構成内のKeeper認証情報を再確認し、ネットワーク接続を確認します。


---

# 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/puppet.md?ask=<question>
```

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.