Kubernetes Secrets Injector

実行時にKeeperシークレットマネージャーからKubernetesポッドへシークレットを自動注入

概要

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

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

インジェクターは公式Helmチャートとして配布され、ArtifactHub で入手できます。Keeperシークレットマネージャー専用の連携です。マルチバックエンドのオペレーターが必要な場合は、External Secrets Operatorをご参照ください。

仕組み

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

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

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

モード

アプリケーションでの利用方法

etcd にシークレット?

ファイル (デフォルト)

メモリバックアップの tmpfs ボリューム上の /keeper/secrets/ からファイルを読み取り

いいえ

環境変数

コンテナ内の標準環境変数

はい (ポッド仕様内)

Kubernetes Secret

secretKeyRef またはボリューム経由のネイティブ Secret オブジェクト

はい

ファイル注入は最も安全なデフォルトです (メモリのみ、ポッド単位)。アプリケーションまたはコントローラーが明示的に要求する場合は、環境変数または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 (代替)をご参照ください。

要件

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

Keeper Injectorのインストール

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

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

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

KSM認証Secretの作成

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

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

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

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

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

シークレットの注入

ファイル (デフォルト)

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

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 に書き込まれ、アプリケーションがそこから読み取ります。

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

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

環境変数

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

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 になります。

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

Kubernetes Secret

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

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)。

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

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

デフォルトのJSONファイル以外が必要な場合は、keeper.security/config 注釈を使用します。これは、出力 path、format、またはGo template を個別に指定できる小さな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 関数ライブラリ (文字列操作、base64/hex、ハッシュ、条件分岐など) を使用し、レコードのフィールドをトップレベル変数 (.login、.password など) として利用できます。

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

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

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"

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

ファイル添付

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

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"

ローテーションと更新

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

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に保存して参照します。

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>"

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

注釈リファレンス

注釈

説明

例

keeper.security/inject

このポッドで注入を有効化

"true"

keeper.security/ksm-config

KSM構成を保持するKubernetes Secret (キー config)

"keeper-credentials"

keeper.security/secret

注入する単一レコード (タイトルで指定)

"my-secret"

keeper.security/secrets

複数レコード (タイトル、カンマ区切り)

"db-creds, api-keys"

keeper.security/secret-<name>

1レコード (タイトルまたは keeper:// 表記) を指定パスへ

keeper.security/secret-db: "keeper://UID/field/password:/keeper/secrets/db.txt"

keeper.security/config

フォーマット、テンプレート、シークレットごとのパス用YAMLブロック

(上記をご参照ください)

keeper.security/folder / keeper.security/folder-uid

フォルダ内のすべてのレコードを取得 (パスまたはUID)

"Production/Databases"

keeper.security/folder-path

フォルダレコードの出力ディレクトリ

"/keeper/secrets/db"

keeper.security/file-<name>

ファイル添付をダウンロード (record:filename:/path)

"tls:server.crt:/keeper/secrets/server.crt"

keeper.security/inject-env-vars

フィールドを環境変数として注入

"true"

keeper.security/env-prefix

注入する環境変数名のプレフィックス

"APP_"

keeper.security/inject-as-k8s-secret

ネイティブのKubernetes Secret を作成

"true"

keeper.security/k8s-secret-name

作成する Secret の名前

"app-secrets"

keeper.security/k8s-secret-mode

競合時の動作: overwrite、merge、skip-if-exists、fail

"merge"

keeper.security/k8s-secret-type

Secret のタイプ

"kubernetes.io/tls"

keeper.security/refresh-interval

サイドカーの再取得間隔

"5m"

keeper.security/init-only

起動時に1回だけ取得、更新サイドカーなし

"true"

keeper.security/fail-on-error

シークレット取得に失敗した場合にポッド起動を失敗 (デフォルト "true")

"false"

keeper.security/ca-cert-secret / keeper.security/ca-cert-configmap

SSLインスペクションプロキシ用のカスタムCA

"corporate-ca"

keeper.security/auth-method

クラウド認証プロバイダー (K8s Secret認証時は省略)

"aws-secrets-manager"

Helm構成

パラメータ

説明

デフォルト

replicaCount

Webhookレプリカ数 (HA)

2

image.repository / image.tag

Webhookイメージ / タグ

keeper/injector-webhook / チャート appVersion

sidecar.repository / sidecar.tag

サイドカーイメージ / タグ

keeper/injector-sidecar / チャート appVersion

metrics.enabled

Prometheusメトリクスを公開

true

tls.autoGenerate

WebhookのTLS証明書を自動生成

true

tls.certManager.enabled

cert-managerでWebhook証明書を発行

false

rbac.create

コントローラーのRBACロールおよびバインディングを作成

true

チャートの完全なオプション一覧は values.yaml をご参照ください。

セットアップの確認

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

kubectl get pods -n keeper-security

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

# 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" を設定し、シークレット取得に失敗してもポッドを起動。

アンインストール

helm uninstall keeper-injector --namespace keeper-security

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

構成例

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

例

前へKeeperコネクションマネージャー次へ例

最終更新 1 か月前