ローカルにある kubeconfig の認証情報を 1Password に分離する方法
kubectl は ~/.kube/config などの kubeconfig を読んでクラスタに接続する。kubeconfig にはクライアント証明書の秘密鍵や token が平文で書かれている。ホームディレクトリにあるファイルなので、バックアップに複製され、同じユーザーで動くプロセスなら読める。AI エージェントにリポジトリを触らせている環境では、エージェントがファイルを読むこともある。
この記事では、kubeconfig から認証情報だけを抜き出して 1Password に置き、kubectl の実行時に 1Password CLI (op) で取り出す方法を書く。そのために作った 2 つのスクリプトの中身と使い方を載せる。
op-kube-credential: kubectl から呼ばれ、1Password から認証情報を読んで返すkubeconfig-to-op: 既存の kubeconfig を、op-kube-credentialを使う形に書き換える
kubeconfig のどこが秘密か
kubeconfig には秘密の値とそうでない値が混ざっている。
| フィールド | 秘密か |
|---|---|
clusters[].cluster.server |
秘密ではない |
clusters[].cluster.certificate-authority-data |
秘密ではない (クラスタの CA 証明書) |
users[].user.client-certificate-data |
秘密ではない (クライアント証明書) |
users[].user.client-key-data |
秘密 (クライアント証明書の秘密鍵) |
users[].user.token |
秘密 |
証明書は鍵ペアの公開側なので、読まれても問題はない。certificate-authority-data は、接続先の API サーバーが本物かを kubectl が確かめるのに使う。この値で問題になるのは読まれることではなく書き換えられることだが、書き換えるにはホームディレクトリへの書き込み権限が要る。
1Password に移す必要があるのは users の側だけである。
方式の選択
kubeconfig を 1Password に置く方法は、いくつか考えられる。
- kubeconfig 全体を 1Password に置き、
KUBECONFIG=<(op inject -i template)のようにプロセス置換で渡す - 実行のたびに kubeconfig を一時ファイルに書き出し、終わったら消す
- kubeconfig は手元に残し、
usersだけを exec credential plugin に置き換える
1 は、プロセス置換で作ったファイルを一度しか読めない。k9s や kubectl config use-context は kubeconfig に書き込むので、この方式では動かない。2 は、途中で落ちたり Ctrl-C で止めたりすると平文のファイルが残る。
3 を選んだ。exec credential plugin は kubectl の標準の仕組みで、users[].user.exec に書いたコマンドを kubectl が実行し、その標準出力から認証情報を受け取る。kubeconfig には秘密の値が残らないので、コンテキストを切り替えてファイルに書き込まれても問題にならない。
書き換え後の users は次のようになる。
users:
- name: admin
user:
exec:
apiVersion: client.authentication.k8s.io/v1
interactiveMode: Never
command: op-kube-credential
args:
- op://development/kubeconfig-example/cluster-a-user
args に渡しているのは 1Password のシークレット参照 (op://<vault>/<item>/<field>) である。interactiveMode: Never は、プラグインが標準入力を使わないことを kubectl に伝える。
command にはシェルの展開が効かない。kubectl はシェルを通さずにコマンドを実行するので、~ や ${HOME} はそのままの文字列になる。代わりに使える書き方は 2 つある。
./op-kube-credentialのように/を含めると、kubeconfig ファイルのあるディレクトリからの相対パスになるop-kube-credentialのように/を含めなければ、PATHから探す
ここでは PATH の通ったディレクトリにスクリプトを置き、名前だけを書いている。
1Password に保存する形式
exec credential plugin は、ExecCredential という JSON を標準出力に書く。
{
"apiVersion": "client.authentication.k8s.io/v1",
"kind": "ExecCredential",
"status": {
"clientCertificateData": "-----BEGIN CERTIFICATE-----\n...",
"clientKeyData": "-----BEGIN EC PRIVATE KEY-----\n..."
}
}
token で認証する場合は、status に token を入れる。
1Password のフィールドには、このうち status の部分を YAML で保存することにした。op read を 1 回呼ぶだけで済み、証明書と鍵を別々のフィールドに分けるより速い。JSON で保存すると PEM の改行を \n と書く必要があり、1Password 上で読みにくい。
status:
clientCertificateData: LS0tLS1CRUdJTi...
clientKeyData: LS0tLS1CRUdJTi...
kubeconfig の client-certificate-data と client-key-data は、PEM を base64 でエンコードした値である。一方、ExecCredential の clientCertificateData と clientKeyData には、PEM をそのまま入れる。kubeconfig の値をそのまま渡すと、kubectl は次のエラーで止まる。
Unable to connect to the server: getting credentials: failed parsing client key/certificate: tls: failed to find any PEM data in certificate input
kubeconfig から値をコピーする手間を減らすため、1Password には base64 のまま保存し、op-kube-credential の側でデコードする。token は kubeconfig でも平文なのでデコードしない。
op-kube-credential
#!/bin/zsh
# kubeconfig の認証情報を 1password から読み込むためのスクリプト
set -eu
# kubectl を Dock 起動のアプリ等から呼ばれると Homebrew が PATH に無い
PATH=/opt/homebrew/bin:/usr/local/bin:$PATH
# 1Password には kubeconfig の *-data の値 (base64) をそのまま保存しているが、
# ExecCredential は生の PEM を要求する。token は kubeconfig でも平文なので戻さない。
# 無いフィールドに @base64d を当てると壊れた値が作られるので、有る時だけ変換する
op read "$1" | yq -o=json '
with(.status | select(has("clientCertificateData"));
.clientCertificateData |= @base64d
| .clientKeyData |= @base64d)
| . + {
"apiVersion": "client.authentication.k8s.io/v1",
"kind": "ExecCredential"
}'
op read で取り出した YAML を、mikefarah 版の yq で JSON に変換している。
with(.status | select(has("clientCertificateData")); ...)で、証明書がある時だけ@base64dをかける。無いフィールドに@base64dをかけると、yq は壊れた値のclientCertificateDataを作ってしまい、token だけの設定が動かなくなるapiVersionとkindはスクリプトで足すので、1Password にはstatusだけを保存すればよい- kubectl を Dock から起動したアプリなどから呼ぶと、
PATHに Homebrew のディレクトリが入っていない。opとyqが見つかるように、先頭でPATHを設定している
スクリプトの中で set -x やログ出力をしてはいけない。kubectl はプラグインの標準エラーを端末に出すので、認証情報が表示されてしまう。
kubeconfig-to-op
既存の kubeconfig を手で書き換えると、ファイルの改名や上書きを間違えやすい。そこで、次の処理をまとめて行うスクリプトを作った。
- 書き換える内容を表示し、
yを入力した時だけ先へ進む - 元の kubeconfig を
<kubeconfig>.backup.YYYYmmddに改名する - 元の名前で、
usersを exec credential plugin に置き換えた kubeconfig を書く - 1Password のフィールドに貼る YAML を標準出力に出す
kubeconfig-to-op ~/.kube/config-cluster-a op://development/kubeconfig-example/cluster-a-user
実行すると、まず次の確認が出る。確認とメッセージは標準エラーに出し、標準出力には 1Password に貼る YAML だけを出す。
This will:
1. Rename /Users/me/.kube/config-cluster-a
-> /Users/me/.kube/config-cluster-a.backup.20261117
2. Write /Users/me/.kube/config-cluster-a (credentials removed)
3. Print the credentials to stdout for these 1Password fields:
user 'admin' -> op://development/kubeconfig-example/cluster-a-user
Proceed? [y/N]
y を入力すると書き換えを行い、確認用のコマンドと YAML を出す。
Done. The backup still has the plaintext credentials: /Users/me/.kube/config-cluster-a.backup.20261117
Save the credentials below to 1Password, then test with:
KUBECONFIG=~/.kube/config-cluster-a kubectl auth whoami
KUBECONFIG=~/.kube/config-cluster-a kubectl get pods --all-namespaces
# ===== 1Password: op://development/kubeconfig-example/cluster-a-user =====
status:
clientCertificateData: LS0tLS1CRUdJTi...
clientKeyData: LS0tLS1CRUdJTi...
この YAML を 1Password のフィールドに貼り、表示されたコマンドで接続を確かめる。
第 2 引数を op://<vault>/<item> までにすると、kubeconfig の user 名がフィールド名になる。対象の user が複数ある kubeconfig では、この形で指定する。
kubeconfig-to-op ~/.kube/config op://development/kubeconfig-example
#!/usr/bin/env zsh
# kubeconfig の users からクライアント証明書・token を抜き、op-kube-credential で
# 1Password から読む形に書き換える。
#
# 確認 (y/N) のあとで次を行う。
# 1. 元のファイルを <kubeconfig>.backup.YYYYmmdd に改名する
# 2. 元の名前で、認証情報を抜いた kubeconfig を書く
# 3. 1Password のフィールドに貼る YAML (秘密鍵や token) を標準出力に出す
#
# 使い方:
# kubeconfig-to-op.sh <kubeconfig> <op://development/kubeconfig-XXX/YYY-user>
#
# kubeconfig-to-op.sh ~/.kube/config-cluster-a op://development/kubeconfig-example/cluster-a-user
#
# フィールドを省いて op://<vault>/<item> だけを渡すと、kubeconfig の user 名を
# フィールド名に使う。フィールドまで書けるのは、書き換え対象の user が
# 1 つの時だけ。
set -eu
die() {
echo "error: $*" >&2
exit 1
}
if (( $# != 2 )); then
echo "usage: ${0:t} <kubeconfig> <op://development/kubeconfig-XXX/YYY-user>" >&2
exit 1
fi
KUBECONFIG_PATH="$1"
OP_REF="${2%/}"
BACKUP_PATH="$KUBECONFIG_PATH.backup.$(date +%Y%m%d)"
[[ -L "$KUBECONFIG_PATH" ]] && die "$KUBECONFIG_PATH is a symlink. Pass the real file."
[[ -f "$KUBECONFIG_PATH" ]] || die "not found: $KUBECONFIG_PATH"
# 同じ日に 2 回実行すると、平文のバックアップを書き換え後のファイルで潰してしまう
[[ -e "$BACKUP_PATH" ]] && die "backup already exists: $BACKUP_PATH"
if [[ "$OP_REF" == op://*/*/* ]]; then
export OP_ITEM="${OP_REF%/*}"
export OP_FIELD="${OP_REF##*/}"
elif [[ "$OP_REF" == op://*/* ]]; then
export OP_ITEM="$OP_REF"
export OP_FIELD=""
else
die "the op reference must look like op://<vault>/<item>/<field>: $OP_REF"
fi
# kubeconfig に埋め込まれた証明書と token だけを対象にする。
# ファイルパス指定 (client-key / tokenFile) や username/password は対象外
HAS_CERT='((.user | has("client-certificate-data")) and (.user | has("client-key-data")))'
HAS_CRED="($HAS_CERT or (.user | has(\"token\")))"
SELECT="select($HAS_CRED)"
users=("${(@f)$(yq ".users[] | $SELECT | .name" "$KUBECONFIG_PATH")}")
users=(${users:#})
(( ${#users} > 0 )) || die "no user has client-certificate-data / client-key-data or token"
if [[ -n "$OP_FIELD" ]] && (( ${#users} > 1 )); then
die "several users to convert (${users[*]}). Pass only op://<vault>/<item> so each user gets its own field."
fi
# yq の select の中では `| not` が効かないので `== false` で比べる
skipped=("${(@f)$(yq ".users[] | select($HAS_CRED == false and (.user | has(\"exec\")) == false) | .name" "$KUBECONFIG_PATH")}")
skipped=(${skipped:#})
if [[ -n "$OP_FIELD" ]]; then
field_expr='strenv(OP_FIELD)'
else
field_expr='$name'
fi
# 確認より前に変換まで済ませておき、yq が失敗してもファイルに触れていない状態で止める
converted=$(yq "(.users[] | $SELECT) |= (.name as \$name | .user = {
\"exec\": {
\"apiVersion\": \"client.authentication.k8s.io/v1\",
\"interactiveMode\": \"Never\",
\"command\": \"op-kube-credential\",
\"args\": [strenv(OP_ITEM) + \"/\" + $field_expr]
}
})" "$KUBECONFIG_PATH")
{
echo "This will:"
echo " 1. Rename $KUBECONFIG_PATH"
echo " -> $BACKUP_PATH"
echo " 2. Write $KUBECONFIG_PATH (credentials removed)"
echo " 3. Print the credentials to stdout for these 1Password fields:"
for name in $users; do
echo " user '$name' -> $OP_ITEM/${OP_FIELD:-$name}"
done
for name in $skipped; do
echo " Skip user '$name' (no embedded certificate or token)"
done
} >&2
# 標準出力をリダイレクトされていても、確認は端末から読む
read -r "answer?Proceed? [y/N] " < /dev/tty || answer=""
[[ "$answer" == [yY] ]] || { echo "Aborted." >&2; exit 1; }
tmp_path=$(mktemp "$KUBECONFIG_PATH.XXXXXX")
trap 'rm -f "$tmp_path"' EXIT
print -r -- "$converted" > "$tmp_path"
chmod 600 "$tmp_path"
mv "$KUBECONFIG_PATH" "$BACKUP_PATH"
mv "$tmp_path" "$KUBECONFIG_PATH"
kubeconfig_display="${${KUBECONFIG_PATH:A}/#$HOME/~}"
{
echo "Done. The backup still has the plaintext credentials: $BACKUP_PATH"
echo
echo "Save the credentials below to 1Password, then test with:"
# whoami は RBAC の権限が無くても認証さえ通れば成功するので、1Password からの
# 読み込みの確認に向く。1.27 未満のクラスタでは使えないので get pods も出す
echo " KUBECONFIG=$kubeconfig_display kubectl auth whoami"
echo " KUBECONFIG=$kubeconfig_display kubectl get pods --all-namespaces"
} >&2
for name in $users; do
echo
echo "# ===== 1Password: $OP_ITEM/${OP_FIELD:-$name} ====="
USER_NAME="$name" yq ".users[] | select(.name == strenv(USER_NAME)) | {
\"status\": (
(select($HAS_CERT) | {
\"clientCertificateData\": .user[\"client-certificate-data\"],
\"clientKeyData\": .user[\"client-key-data\"]
}) // {}
) + (
(select(.user | has(\"token\")) | {\"token\": .user.token}) // {}
)
}" "$BACKUP_PATH"
done
対象にする user
書き換えるのは、kubeconfig に証明書 (client-certificate-data と client-key-data) か token が埋め込まれている user だけである。次の user は書き換えず、確認の画面に Skip と表示する。
- 証明書や token をファイルのパスで指定している (
client-key,tokenFile) usernameとpasswordで認証している
exec で認証している user (EKS の aws eks get-token など) は、kubeconfig に秘密が入っていないので、何も表示せずにそのまま残す。
書き換えの失敗に備えた処理
- バックアップのファイル名が既にあれば止まる。同じ日に 2 回実行すると、1 回目に作った平文のバックアップを、書き換え後のファイルで上書きしてしまうためである
- 書き換え後の内容は、確認を出す前に作っておく。yq が失敗した時は、ファイルに触れずに止まる
- 新しい kubeconfig は一時ファイルに書いてから、元の名前に移す。パーミッションは
600にする - 確認の入力は
/dev/ttyから読む。標準出力をリダイレクトしていても確認は端末に出る。端末が無い環境ではAborted.で止まる - シンボリックリンクは受け付けない。改名するとリンクだけが動くためである
確認用のコマンド
最後に表示するコマンドは kubectl auth whoami にした。
kubectl get pods --all-namespacesは、全 namespace の Pod を見る権限 (RBAC) が要る。権限を絞った token では、認証が通っていてもForbiddenで失敗するkubectl versionやkubectl cluster-infoは、認証の確認には向かない。/versionは認証なしで応答するクラスタが多いkubectl auth whoamiは、権限が無くても認証が通れば自分のユーザー名を返す
auth whoami は Kubernetes 1.27 以上でしか使えないので、古いクラスタ向けに get pods も並べて表示している。
移行した後の注意
この方式で守れるのは、ディスク上のファイルである。バックアップへの複製、ディスクの盗難、ファイルを走査するツールに対しては効く。1Password CLI をデスクトップアプリと連携させている場合、承認はターミナルのセッション単位で一定時間続く。その間に同じセッションで動くプロセスは op read を呼べるので、すでに動いている悪意のあるプロセスは防げない。
kubectl を実行するたびに op が動くので、1 回あたり 0.5〜1 秒ほど遅くなる。kubectl を何度も呼ぶデプロイ用のスクリプトでは、この差が積み重なる。新しいターミナルを開いた時や、しばらく操作しなかった後には、1Password の承認 (Touch ID) を求められる。
kubeconfig-to-op が作るバックアップには、平文の認証情報が残る。接続を確かめたら消す必要がある。Time Machine などのバックアップにも、移行前の kubeconfig が残っている。それらから認証情報を読まれないようにするには、クライアント証明書や token を作り直して、1Password の値を入れ替える。Kubernetes にはクライアント証明書を単体で失効させる仕組みが無いので、証明書の場合は再発行が要る。kubeconfig に直接書かれた token の多くは期限の無い ServiceAccount の token なので、こちらも作り直したほうがよい。
未解決の事例
k3s のクラスタの 1 つで、書き換えた後に次のエラーになった。
$ kubectl auth whoami
error: You must be logged in to the server (Unauthorized)
鍵と証明書が対になっていなければ、kubectl は通信の前に private key does not match public key で止まる。op read に失敗した場合も、getting credentials: exec: ... という別のエラーになる。今回は通信まで進んで Unauthorized が返っているので、kubectl は 1Password から対になった証明書と鍵を受け取り、サーバーがその証明書を受け付けなかったことになる。
原因の候補は 2 つある。
- 証明書の期限切れ。k3s のクライアント証明書の期限は 1 年で、期限が近づいてから k3s を再起動すると、サーバー側の証明書は作り直される。手元にコピーした kubeconfig は古いままなので、1 年経つと期限が切れる
- 1Password に別のクラスタの証明書を保存した
バックアップの kubeconfig でも Unauthorized になるか、証明書の notAfter が過去の日付になっていないかを見れば切り分けられる。この事例はまだ確認していない。
開発相談をお待ちしています。