> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/kubernetes-secrets-injector.md).

# Kubernetes Secrets Injector

### 概要

**Keeper Injector**は、実行時にKeeperシークレットマネージャー (KSM) からシークレットをKubernetesポッドへ自動注入する**ミューテーションアドミッションWebhook**です。注釈付きポッドに軽量な**サイドカー**が追加され、Keeperへ認証して要求されたシークレットを取得し、アプリケーションで利用できるようにします。デフォルトでは `etcd` やディスクに触れない、メモリバックアップ (`tmpfs`) ボリューム上に配置されます。

インジェクターは**ポッド注釈**のみで構成され、カスタムリソースの管理は不要です。

{% hint style="info" %}
インジェクターは公式Helmチャートとして配布され、[ArtifactHub](https://artifacthub.io/packages/helm/keeper-security/keeper-injector) で入手できます。Keeperシークレットマネージャー専用の連携です。マルチバックエンドのオペレーターが必要な場合は、External Secrets Operatorをご参照ください。
{% endhint %}

### 仕組み

ポッドに `keeper.security/inject: "true"` 注釈がある場合、Webhookは以下を追加するようポッドを変更します。

* アプリケーション起動前にシークレットを1回取得する**initコンテナ**
* 一定間隔でシークレットを更新する**サイドカーコンテナ** (initのみに限定する場合を除く)

サイドカーは3つの方法でシークレットを配信できます。注釈でポッドごとに選択します。

<table data-header-hidden><thead><tr><th width="212.83984375"></th><th width="361.171875"></th><th></th></tr></thead><tbody><tr><td>モード</td><td>アプリケーションでの利用方法</td><td><code>etcd</code> にシークレット?</td></tr><tr><td><strong>ファイル</strong> (デフォルト)</td><td>メモリバックアップの <code>tmpfs</code> ボリューム上の <code>/keeper/secrets/</code> からファイルを読み取り</td><td>いいえ</td></tr><tr><td><strong>環境変数</strong></td><td>コンテナ内の標準環境変数</td><td>はい (ポッド仕様内)</td></tr><tr><td><strong>Kubernetes Secret</strong></td><td><code>secretKeyRef</code> またはボリューム経由のネイティブ <code>Secret</code> オブジェクト</td><td>はい</td></tr></tbody></table>

ファイル注入は最も安全なデフォルトです (メモリのみ、ポッド単位)。アプリケーションまたはコントローラーが明示的に要求する場合は、環境変数またはKubernetes `Secret` を使用してください。

### Keeper InjectorとExternal Secrets Operatorの比較

どちらもKSMシークレットをKubernetesへ取り込みますが、方法が異なります。

|                               | **Keeper Injector**     | **External Secrets Operator** |
| ----------------------------- | ----------------------- | ----------------------------- |
| Kubernetes `Secret` オブジェクトの作成 | 任意 (デフォルト: いいえ)         | はい (コアモデル)                    |
| シークレットの保存場所                   | デフォルトはポッド `tmpfs` (メモリ) | `etcd`                        |
| 構成                            | ポッド注釈                   | カスタムリソース (CRD)                |
| 実行時ローテーション                    | はい (サイドカー)              | 同期間隔に応じて                      |
| ポッド単位の分離                      | はい                      | 共有 `Secret` オブジェクト            |
| バックエンド                        | Keeperのみ                | 35以上のプロバイダー                   |

**Keeper Injectorを選択する場合:** シークレットを **`etcd` の外** (ポッドメモリへ配信) に保ち、**ポッド単位の分離**と**ポッド再起動なしのその場ローテーション**が必要で、カスタムリソースなしに数個のポッド注釈で構成したいとき。

**External Secrets Operatorを選択する場合:** クラスタの既存運用に合わせたいとき。たとえば、**すでにESOを標準のシークレットオペレーターとして運用**しており (多くの場合マルチバックエンド)、Keeperを同じCRDワークフローに組み込みたい場合。シークレットを他のコントローラーやGitOpsツールが消費する**長寿命の共有 `Secret` オブジェクト**として調整したい場合。または書き戻し (`PushSecret`) などESO固有の機能が必要な場合。ESOにはメンテナンスされたKeeperプロバイダーが含まれます。

レガシーのinitコンテナ方式については、[Kubernetes (代替)](https://github.com/Keeper-Security/gitbook-jp-secrets-manager/blob/main/secrets-manager/integrations/kubernetes-secrets-injector/kubernetes.md)をご参照ください。

### 要件

* Kubernetesクラスタ (バージョン **1.25以降**)
* [Helm 3](https://helm.sh/docs/intro/install/)
* Keeperシークレットマネージャーの**アプリケーション**および**デバイス構成** (クイックスタートガイドをご参照ください)
* 対象クラスタへの `kubectl` アクセス

### Keeper Injectorのインストール

専用の名前空間にWebhookおよびサイドカーコントローラーをインストールします。

{% tabs %}
{% tab title="Helmリポジトリ" %}

```bash
helm repo add keeper https://keeper-security.github.io/helm-charts
helm repo update

helm upgrade --install keeper-injector keeper/keeper-injector \
  --namespace keeper-security --create-namespace
```

{% endtab %}

{% tab title="OCIレジストリ (Docker Hub)" %}

```bash
helm upgrade --install keeper-injector oci://registry-1.docker.io/keeper/keeper-injector \
  --namespace keeper-security --create-namespace
```

{% endtab %}
{% endtabs %}

Webhook用のTLS証明書はデフォルトで自動生成されます (`tls.autoGenerate=true`)。`tls.certManager.enabled=true` でcert-managerも利用できます。

### KSM認証Secretの作成

サイドカーはシークレットマネージャーの**デバイス構成**でKeeperへ認証します。構成は、ワークロードを実行する名前空間のKubernetes Secret (キー `config`) に保存します。

構成を取得する最も簡単な方法は、**Keeperウェブボルト**から行います。**\[シークレットマネージャー]** → 対象アプリケーション → **\[デバイスを追加]** → **\[構成ファイル方式]** → **\[Base64タイプ]** の順で進み、Base64文字列をコピーします。その後、以下を実行します。

```bash
kubectl create secret generic keeper-credentials \
  --from-literal=config='<paste-base64-config>' \
  --namespace default
```

{% hint style="info" %}
シークレットマネージャーCLIまたはコマンダーで構成を生成し、JSONファイルを読み込むこともできます (`--from-file=config=ksm-config.json`)。いずれの形式でも動作します。Secretのキーは `config` である必要があります。
{% endhint %}

{% hint style="warning" %}
構成は認証情報です。Secretは直接作成し (ソース管理にコミットしない)、RBACでアクセスを制限してください。
{% endhint %}

### シークレットの注入

#### ファイル (デフォルト)

ポッドテンプレートに注入用注釈を追加します。インジェクターはサイドカーと共有 `tmpfs` ボリュームを追加し、要求された各レコードを `/keeper/secrets/` 配下のファイルとして書き込みます。

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/secret: "database-credentials"
spec:
  containers:
    - name: app
      image: my-app:latest
```

レコードは `/keeper/secrets/database-credentials.json` に書き込まれ、アプリケーションがそこから読み取ります。

```bash
cat /keeper/secrets/database-credentials.json
# {"login":"app_user","password":"…","host":"db.internal"}
```

{% hint style="info" %}
注入されたファイルは**読み取り専用 (`0440`)** で書き込まれ、サイドカーのユーザーが所有します。**root** または **`nobody`** ユーザーで実行するコンテナは追加設定なしで読み取れます。別の固定非root UIDでアプリケーションを実行する場合は、ポッドレベルの `securityContext.fsGroup` を一致させて、グループ読み取り可能なファイルにアクセスできるようにしてください。
{% endhint %}

#### 環境変数

`keeper.security/inject-env-vars: "true"` を設定すると、ファイルの代わりに (または加えて) レコードのフィールドを環境変数として注入します。フィールド名は大文字の環境変数キーになります。`keeper.security/env-prefix` でプレフィックスを追加できます。

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: legacy-app
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/inject-env-vars: "true"
    keeper.security/env-prefix: "APP_"
    keeper.security/secret: "database-credentials"
    keeper.security/init-only: "true"   # env vars can't change without a restart
spec:
  containers:
    - name: app
      image: legacy-app:latest
```

`login` および `password` フィールドは `APP_LOGIN` および `APP_PASSWORD` になります。

{% hint style="warning" %}
環境変数はポッド仕様に書き込まれるため、`kubectl get pod -o yaml` で表示され、`etcd` に保存されます。機密値にはファイル注入を推奨します。環境変数はポッドを再起動しないとローテーションできないため、`keeper.security/init-only: "true"` と併用してください。
{% endhint %}

#### Kubernetes Secret

`keeper.security/inject-as-k8s-secret: "true"` を設定すると、インジェクターがレコードからネイティブのKubernetes `Secret` を作成し、ワークロードは標準的な方法で利用できます。

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: app-with-secret
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/inject-as-k8s-secret: "true"
    keeper.security/k8s-secret-name: "app-secrets"
    keeper.security/secret: "database-credentials"
spec:
  containers:
    - name: app
      image: my-app:latest
      env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: password
```

各レコードフィールドが `Secret` のキーになります。競合時の動作は `keeper.security/k8s-secret-mode` (`overwrite`、`merge`、`skip-if-exists`、`fail`) で制御し、タイプは `keeper.security/k8s-secret-type` で設定できます (例: `kubernetes.io/tls`)。

{% hint style="info" %}
作成された `Secret` は**ポッド自身の名前空間**に書き込まれ、ポッド削除時に**自動削除されません**。不要になったら明示的に削除するか、名前空間を削除してください。
{% endhint %}

### 出力フォーマットとテンプレート

デフォルトのJSONファイル以外が必要な場合は、`keeper.security/config` 注釈を使用します。これは、出力 `path`、`format`、またはGo `template` を個別に指定できる小さなYAMLドキュメントです。

```yaml
metadata:
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/config: |
      secrets:
        # Render a single field, raw
        - record: database-credentials
          path: /keeper/secrets/password.txt
          fields: [password]
          format: raw

        # Render as a .env file
        - record: database-credentials
          path: /keeper/secrets/db.env
          format: env

        # Build a connection string with a Go template
        - record: database-credentials
          path: /keeper/secrets/db-url.txt
          template: |
            postgresql://{{ .login }}:{{ .password }}@{{ .host }}:5432/app
```

対応する `format` 値: `json` (デフォルト)、`env`、`yaml`、`properties`、`ini`、`raw`。テンプレートはGo `text/template` と [Sprig](https://masterminds.github.io/sprig/) 関数ライブラリ (文字列操作、base64/hex、ハッシュ、条件分岐など) を使用し、レコードのフィールドをトップレベル変数 (`.login`、`.password` など) として利用できます。

### 複数シークレット、フォルダ、Keeper Notation

複数レコード、フォルダ全体、またはKeeper Notationによる単一フィールドを注入できます。

```yaml
metadata:
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"

    # Several records by title (comma-separated)
    keeper.security/secrets: "database-credentials, api-keys"

    # A whole folder → one file per record under the output path
    keeper.security/folder: "Production/Databases"
    keeper.security/folder-path: "/keeper/secrets/db"

    # One field, by Keeper Notation, to a chosen path
    keeper.security/secret-token: "keeper://Rh1k…UID/field/password:/keeper/secrets/token.txt"
```

{% hint style="info" %}
Keeper Notation (`keeper://…`) は、**シークレットごとの** `keeper.security/secret-<name>` 注釈および `keeper.security/config` ブロック内で解析されます。プレーンな `keeper.security/secret` 注釈では解析されず、値は常にレコードの**タイトル**として扱われます。フォルダはパス (`keeper.security/folder`) またはUID (`keeper.security/folder-uid`) で参照できます。
{% endhint %}

### ファイル添付

`keeper.security/file-<name>` でKeeperレコードに添付されたファイルをダウンロードします。形式は `record:filename:/output/path` です。

```yaml
metadata:
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/file-cert: "tls-record:server.crt:/keeper/secrets/tls/server.crt"
    keeper.security/file-key: "tls-record:server.key:/keeper/secrets/tls/server.key"
```

### ローテーションと更新

サイドカーモードでは、エージェントが一定間隔でシークレットを再取得し、ファイルを**その場で**上書きします。ポッドの再起動は不要で、ファイルを再読み取りするアプリケーションは新しい値を自動的に取得します。

```yaml
metadata:
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/secret: "database-credentials"
    keeper.security/refresh-interval: "5m"   # default is 5m
```

`keeper.security/init-only: "true"` を設定すると、起動時に1回だけ取得し、更新用サイドカーは追加しません。環境変数注入、またはローテーションが不要な場合に適しています。

### コーポレートプロキシ / カスタムCA

アウトバウンドトラフィックがSSLインスペクションプロキシ (Zscaler、Palo Alto、Cisco Umbrellaなど) によって傍受される場合、サイドカーが信頼するようプロキシのCA証明書を指定します。CAをSecretまたはConfigMapに保存して参照します。

```yaml
metadata:
  annotations:
    keeper.security/inject: "true"
    keeper.security/ksm-config: "keeper-credentials"
    keeper.security/secret: "database-credentials"
    keeper.security/ca-cert-configmap: "corporate-ca"   # or keeper.security/ca-cert-secret
    keeper.security/ca-cert-key: "ca.crt"               # key within the ConfigMap/Secret (default: ca.crt)
```

### クラウド認証 (任意)

Kubernetes Secretの代わりに、サイドカーが実行時にクラウドのシークレットストアからKSM構成を取得できます。`keeper.security/auth-method` とプロバイダーのロケーターを設定し、**`keeper.security/ksm-config` は省略**します。

| プロバイダ               | 注釈                                                                                                                                           |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS Secrets Manager | `keeper.security/auth-method: "aws-secrets-manager"`、`keeper.security/aws-secret-id: "<id/arn>"`、`keeper.security/aws-region: "<region>"`    |
| GCP Secret Manager  | `keeper.security/auth-method: "gcp-secret-manager"`、`keeper.security/gcp-secret-id: "<resource>"`                                            |
| Azure Key Vault     | `keeper.security/auth-method: "azure-key-vault"`、`keeper.security/azure-vault-name: "<vault>"`、`keeper.security/azure-secret-name: "<name>"` |

{% hint style="info" %}
クラウド認証は**ファイルベース**の注入と組み合わせて使用します。クラウドプロバイダー側のワークロードID (IRSA、Workload Identity、Azure Workload Identity) により、保存されたKSM構成が読み取られます。
{% endhint %}

### 注釈リファレンス

<table><thead><tr><th>注釈</th><th width="315.54296875">説明</th><th>例</th></tr></thead><tbody><tr><td><code>keeper.security/inject</code></td><td>このポッドで注入を有効化</td><td><code>"true"</code></td></tr><tr><td><code>keeper.security/ksm-config</code></td><td>KSM構成を保持するKubernetes Secret (キー <code>config</code>)</td><td><code>"keeper-credentials"</code></td></tr><tr><td><code>keeper.security/secret</code></td><td>注入する単一レコード (<strong>タイトル</strong>で指定)</td><td><code>"my-secret"</code></td></tr><tr><td><code>keeper.security/secrets</code></td><td>複数レコード (タイトル、カンマ区切り)</td><td><code>"db-creds, api-keys"</code></td></tr><tr><td><code>keeper.security/secret-&#x3C;name></code></td><td>1レコード (タイトルまたは <code>keeper://</code> 表記) を指定パスへ</td><td><code>keeper.security/secret-db: "keeper://UID/field/password:/keeper/secrets/db.txt"</code></td></tr><tr><td><code>keeper.security/config</code></td><td>フォーマット、テンプレート、シークレットごとのパス用YAMLブロック</td><td><em>(上記をご参照ください)</em></td></tr><tr><td><code>keeper.security/folder</code> / <code>keeper.security/folder-uid</code></td><td>フォルダ内のすべてのレコードを取得 (パスまたはUID)</td><td><code>"Production/Databases"</code></td></tr><tr><td><code>keeper.security/folder-path</code></td><td>フォルダレコードの出力ディレクトリ</td><td><code>"/keeper/secrets/db"</code></td></tr><tr><td><code>keeper.security/file-&#x3C;name></code></td><td>ファイル添付をダウンロード (<code>record:filename:/path</code>)</td><td><code>"tls:server.crt:/keeper/secrets/server.crt"</code></td></tr><tr><td><code>keeper.security/inject-env-vars</code></td><td>フィールドを環境変数として注入</td><td><code>"true"</code></td></tr><tr><td><code>keeper.security/env-prefix</code></td><td>注入する環境変数名のプレフィックス</td><td><code>"APP_"</code></td></tr><tr><td><code>keeper.security/inject-as-k8s-secret</code></td><td>ネイティブのKubernetes <code>Secret</code> を作成</td><td><code>"true"</code></td></tr><tr><td><code>keeper.security/k8s-secret-name</code></td><td>作成する <code>Secret</code> の名前</td><td><code>"app-secrets"</code></td></tr><tr><td><code>keeper.security/k8s-secret-mode</code></td><td>競合時の動作: <code>overwrite</code>、<code>merge</code>、<code>skip-if-exists</code>、<code>fail</code></td><td><code>"merge"</code></td></tr><tr><td><code>keeper.security/k8s-secret-type</code></td><td><code>Secret</code> のタイプ</td><td><code>"kubernetes.io/tls"</code></td></tr><tr><td><code>keeper.security/refresh-interval</code></td><td>サイドカーの再取得間隔</td><td><code>"5m"</code></td></tr><tr><td><code>keeper.security/init-only</code></td><td>起動時に1回だけ取得、更新サイドカーなし</td><td><code>"true"</code></td></tr><tr><td><code>keeper.security/fail-on-error</code></td><td>シークレット取得に失敗した場合にポッド起動を失敗 (デフォルト <code>"true"</code>)</td><td><code>"false"</code></td></tr><tr><td><code>keeper.security/ca-cert-secret</code> / <code>keeper.security/ca-cert-configmap</code></td><td>SSLインスペクションプロキシ用のカスタムCA</td><td><code>"corporate-ca"</code></td></tr><tr><td><code>keeper.security/auth-method</code></td><td>クラウド認証プロバイダー (K8s Secret認証時は省略)</td><td><code>"aws-secrets-manager"</code></td></tr></tbody></table>

### Helm構成

<table><thead><tr><th width="227.94921875">パラメータ</th><th width="294.0859375">説明</th><th>デフォルト</th></tr></thead><tbody><tr><td><code>replicaCount</code></td><td>Webhookレプリカ数 (HA)</td><td><code>2</code></td></tr><tr><td><code>image.repository</code> / <code>image.tag</code></td><td>Webhookイメージ / タグ</td><td><code>keeper/injector-webhook</code> / チャート appVersion</td></tr><tr><td><code>sidecar.repository</code> / <code>sidecar.tag</code></td><td>サイドカーイメージ / タグ</td><td><code>keeper/injector-sidecar</code> / チャート appVersion</td></tr><tr><td><code>metrics.enabled</code></td><td>Prometheusメトリクスを公開</td><td><code>true</code></td></tr><tr><td><code>tls.autoGenerate</code></td><td>WebhookのTLS証明書を自動生成</td><td><code>true</code></td></tr><tr><td><code>tls.certManager.enabled</code></td><td>cert-managerでWebhook証明書を発行</td><td><code>false</code></td></tr><tr><td><code>rbac.create</code></td><td>コントローラーのRBACロールおよびバインディングを作成</td><td><code>true</code></td></tr></tbody></table>

チャートの完全なオプション一覧は [`values.yaml`](https://github.com/Keeper-Security/helm-charts/blob/main/charts/keeper-injector/values.yaml) をご参照ください。

### セットアップの確認

インジェクターコントローラーが稼働していることを確認します。

```bash
kubectl get pods -n keeper-security
```

注釈付きワークロードをデプロイし、サイドカーが注入され、シークレットが存在することを確認します。

```bash
# the keeper-secrets-sidecar container should be listed
kubectl get pod my-app -o jsonpath='{.spec.containers[*].name}'

# read an injected file
kubectl exec my-app -c app -- cat /keeper/secrets/database-credentials.json
```

### トラブルシューティング

| 症状                                  | 確認事項                                                                                                                                     |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| サイドカーが注入されない                        | 名前空間に `keeper.security/inject=disabled` ラベルが付いていないこと。`keeper-security` のコントローラーPodが稼働していること。ポッドに `keeper.security/inject: "true"` があること。 |
| ポッドが起動しない / シークレットがない               | initコンテナのログを確認: `kubectl logs <pod> -c keeper-secrets-init`。レコードタイトルが完全一致していること、認証Secretに `config` キーがあることを確認。                           |
| 実行時の更新の問題                           | サイドカーのログを確認: `kubectl logs <pod> -c keeper-secrets-sidecar`。                                                                             |
| アプリがファイルを読み取れない (permission denied) | アプリコンテナが `root`/`nobody` 以外のUIDで実行されている。一致するポッド `securityContext.fsGroup` を設定。                                                           |
| ソフトフェイルを希望                          | `keeper.security/fail-on-error: "false"` を設定し、シークレット取得に失敗してもポッドを起動。                                                                      |

### アンインストール

```bash
helm uninstall keeper-injector --namespace keeper-security
```

コントローラーを削除すると新規注入は停止しますが、既存ポッドの注入済みサイドカーは再作成されるまで残ります。`tmpfs` 上のファイルはポッドとともに消えますが、K8s Secretモードで作成された `Secret` オブジェクトは残るため、明示的に削除してください。

### 構成例

Kubernetes Secrets Injectorの詳細な使用例は、以下のページをご参照ください。

[例](/keeperpam/jp/secrets-manager/integrations/kubernetes-secrets-injector/examples.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/kubernetes-secrets-injector.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.