メインコンテンツまでスキップ

カスタム権限付きの長期利用 Kubeconfig を作成する

1. Overview​

この機能について​

長期利用の kubeconfig を使うと、24 時間しか有効でない FPT Portal の kubeconfig に頼らず、有効期限と権限を自分で決めた kubeconfig を作成できます。

解決する課題​

FPT Portal からダウンロードした kubeconfig は 24 時間 で失効します。ArgoCD、Rancher、Jenkins、Vault、monitoring など継続的に動作するサードパーティ製システムで使うと、接続が切れるたびに再ダウンロードと再設定が必要になります。

得られるもの​

このガイドを実施すると、中断せずに動作する kubeconfig が手に入ります。権限はシステム単位、あるいはチームメンバー単位で調整できます。

2. Who Should Use This​

役割利用する場面
DevOps / Platform EngineerArgoCD、Rancher、Jenkins、Vault、monitoring、backup、自動化スクリプトを M-FKE cluster に接続する
Developer開発環境向けに個人用の長期 kubeconfig が必要
Team Leadチームメンバーごとに適切な権限の kubeconfig を配布する

3. Key Capabilities​

機能説明
有効期限の指定失効しない token、または任意の期限（90 日、1 年など）を指定した token
権限の指定（RBAC）cluster 全体の権限、読み取り専用、namespace 単位、リソース種別ごとの細かい指定
2 種類の認証方式ServiceAccount と bearer token（マシン間）、または client certificate による mTLS（個人向け）
自分で管理・失効サポートへ依頼せずに、credential の作成、確認、失効ができます
各種システムと連携ArgoCD、Rancher、Jenkins、Vault、Prometheus など kubeconfig を受け付けるシステム全般

4. How to Use — Step-by-Step​

方式を選ぶ​

方式 1: ServiceAccount + Token方式 2: Client Certificate
認証Bearer token証明書（mTLS）
有効期限失効しない、または任意指定任意指定、最長 30 日
適した用途マシン間の接続（ArgoCD、Rancher、Jenkins、Vault など）メンバーごとの個人用 kubeconfig
推奨✅ ほとんどの場合はこちらを使用しますUser や Group で個人を識別する必要がある場合

前提条件​

開始前に、次を確認してください。

  • 作業マシンに kubectl がインストールされている
  • FPT Portal から cluster の kubeconfig を取得済みで、24 時間以内である
  • API server に到達できる（cluster でアクセス制限を有効にしている場合は IP を許可リストに追加済み）

注意: コマンドは Linux または macOS のシェルを前提としています。Windows では WSL または Git Bash での実行を推奨します。

共通の準備（両方式で必須）​

準備 P-1: Portal の kubeconfig で cluster に接続する​

操作: Portal の kubeconfig を export し、接続を確認します。

export KUBECONFIG=/path/to/kubeconfig-portal.yaml
kubectl get nodes

想定結果:

NAME                    STATUS   ROLES    AGE   VERSION
fke-node-abc            Ready    <none>   10d   v1.28.x
fke-node-def            Ready    <none>   10d   v1.28.x

⚠️ エラーになる場合は、kubeconfig のパスと取得からの経過時間（有効期限 24 時間）を確認してください。

準備 P-2: cluster の情報（SERVER と CA）を取得する​

操作: API server のアドレスと CA certificate を取得します。

SERVER=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.server}')
CA_B64=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')

echo "$SERVER"

想定結果:

https://api.fke-xxxxxxxx.fptcloud.com:443

重要: SERVER と CA_B64 は cluster に属する値なので、Portal の kubeconfig と一緒に失効することはありません。以降の手順で再利用します。

ユースケース 1: ServiceAccount と token による kubeconfig（推奨）​

ArgoCD、Rancher、Jenkins、Vault、monitoring、backup など、マシン間の接続に適しています。

手順 1.1: ServiceAccount を作成する​

操作: ServiceAccount を新規作成します。システムごとに 1 つ作成してください。

NAMESPACE=kube-system       # または専用の namespace（例: external-access）
SA_NAME=argocd-deployer     # 利用するシステム名を付けます

kubectl create serviceaccount "$SA_NAME" -n "$NAMESPACE"

想定結果:

serviceaccount/argocd-deployer created

ヒント: システムがわかる名前を付けます: argocd-deployer、jenkins-ci、rancher-agent、monitoring-reader。

手順 1.2: 権限を付与する（RBAC）​

操作: 用途に合う権限テンプレートを 1 つ選びます。

テンプレート A — cluster 全体の権限（Portal の kubeconfig と同等）:

kubectl create clusterrolebinding "${SA_NAME}-admin" \
  --clusterrole=cluster-admin \
  --serviceaccount="${NAMESPACE}:${SA_NAME}"

テンプレート B — cluster 全体の読み取り専用（monitoring、dashboard 向け）:

kubectl create clusterrolebinding "${SA_NAME}-view" \
  --clusterrole=view \
  --serviceaccount="${NAMESPACE}:${SA_NAME}"

テンプレート C — 特定 namespace 内の全権限（CI/CD 向け）:

for ns in app-dev app-staging; do
  kubectl create rolebinding "${SA_NAME}-edit" -n "$ns" \
    --clusterrole=edit \
    --serviceaccount="${NAMESPACE}:${SA_NAME}"
done

テンプレート D — 細かく指定したカスタム権限 — 例: workload のデプロイのみ許可し、Secret の読み取りと変更は許可しない。

custom-deployer-rbac.yaml を作成します。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: custom-deployer
rules:
  - apiGroups: ["apps"]
    resources: ["deployments", "statefulsets", "daemonsets", "replicasets"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["services", "configmaps", "pods", "pods/log"]
    verbs: ["*"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-deployer-custom
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: custom-deployer
subjects:
  - kind: ServiceAccount
    name: argocd-deployer
    namespace: kube-system

適用します。

kubectl apply -f custom-deployer-rbac.yaml

ヒント: Kubernetes には cluster-admin（全権限）、admin、edit（読み書き可、RBAC は変更不可）、view（読み取り専用）が標準で用意されています。一覧は kubectl get clusterroles で確認できます。

手順 1.3: token を取得する​

用途に応じてどちらか 1 つを選びます。

方法 A — 失効しない token（自動化システムに推奨）:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: ${SA_NAME}-token
  namespace: ${NAMESPACE}
  annotations:
    kubernetes.io/service-account.name: ${SA_NAME}
type: kubernetes.io/service-account-token
EOF

# token が書き込まれるまで数秒待ってから取得します
TOKEN=$(kubectl get secret "${SA_NAME}-token" -n "$NAMESPACE" \
  -o jsonpath='{.data.token}' | base64 -d)

この token は無期限で有効です。Secret または ServiceAccount を削除したときにのみ無効になります。

方法 B — 有効期限を指定した token（より安全ですが更新が必要）:

# 例: 90 日 = 2160h
TOKEN=$(kubectl create token "$SA_NAME" -n "$NAMESPACE" --duration=2160h)

token は期限が来ると自動的に失効します。その際は新しい token を作成し、利用中のシステムを更新してください。

手順 1.4: 新しい kubeconfig を作成する​

操作:

CLUSTER_NAME=my-fke-cluster   # 任意の名前

cat > kubeconfig-${SA_NAME}.yaml <<EOF
apiVersion: v1
kind: Config
clusters:
  - name: ${CLUSTER_NAME}
    cluster:
      certificate-authority-data: ${CA_B64}
      server: ${SERVER}
contexts:
  - name: ${SA_NAME}@${CLUSTER_NAME}
    context:
      cluster: ${CLUSTER_NAME}
      user: ${SA_NAME}
current-context: ${SA_NAME}@${CLUSTER_NAME}
users:
  - name: ${SA_NAME}
    user:
      token: ${TOKEN}
EOF

結果: カレントディレクトリに kubeconfig-argocd-deployer.yaml が作成されます。

手順 1.5: 新しい kubeconfig を確認する​

操作:

export KUBECONFIG=$PWD/kubeconfig-${SA_NAME}.yaml

# 認証されている ID を確認します
kubectl auth whoami

# 接続を確認します
kubectl get nodes

# 個別の権限を確認します
kubectl auth can-i create deployments -n app-dev

想定結果:

# kubectl auth whoami
ATTRIBUTE                                           VALUE
Username                                            system:serviceaccount:kube-system:argocd-deployer
Groups                                              [system:serviceaccounts system:serviceaccounts:kube-system system:authenticated]

# kubectl get nodes
NAME                    STATUS   ROLES    AGE   VERSION
fke-node-abc            Ready    <none>   10d   v1.28.x

# kubectl auth can-i create deployments -n app-dev
yes

結果​

✅ kubeconfig-argocd-deployer.yaml を ArgoCD、Rancher、Jenkins、Vault などにインポートできます。24 時間を過ぎても接続は中断しません。

ユースケース 2: Client Certificate による個人用 kubeconfig​

チームメンバーごとに kubeconfig を配布し、User や Group で識別する場合に適しています。

⚠️ 制限: 証明書の有効期限は最長 30 日です。自動化システム向けに長期の接続が必要な場合はユースケース 1 を使用してください。

手順 2.1: private key と CSR を作成する​

操作:

USER_NAME=dev-nguyenvana
GROUP=dev-team               # グループ単位の権限付与に使用します

# private key を作成します
openssl genrsa -out ${USER_NAME}.key 2048

# Certificate Signing Request を作成します
openssl req -new -key ${USER_NAME}.key -out ${USER_NAME}.csr \
  -subj "/CN=${USER_NAME}/O=${GROUP}"

想定結果:

Generating RSA private key, 2048 bit long modulus
...

補足: CN（Common Name）はユーザー名、O（Organization）はグループ名です。Kubernetes はこの 2 つを権限判定に使用します。

手順 2.2: CSR を cluster に送信する​

操作:

kubectl apply -f - <<EOF
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
  name: ${USER_NAME}
spec:
  request: $(base64 -w 0 < ${USER_NAME}.csr)
  signerName: kubernetes.io/kube-apiserver-client
  expirationSeconds: 2592000    # 30 日 = 2592000 秒
  usages:
    - client auth
EOF

想定結果:

certificatesigningrequest.certificates.k8s.io/dev-nguyenvana created

手順 2.3: CSR を承認して証明書を取得する​

操作:

# 承認します
kubectl certificate approve ${USER_NAME}

# 署名済みの証明書を取得します
kubectl get csr ${USER_NAME} -o jsonpath='{.status.certificate}' | base64 -d > ${USER_NAME}.crt

# 実際の有効期限を確認します
openssl x509 -in ${USER_NAME}.crt -noout -enddate

想定結果:

certificatesigningrequest.certificates.k8s.io/dev-nguyenvana approved
notAfter=Oct  3 07:30:00 2026 GMT

手順 2.4: User と Group に権限を付与する​

操作:

kubectl create clusterrolebinding ${GROUP}-edit \
  --clusterrole=edit \
  --group=${GROUP}

権限は証明書内の Group（O=dev-team）に紐づくため、同じ Group のメンバー全員が同じ権限を持ちます。メンバーが増えても付与し直す必要はありません。

手順 2.5: kubeconfig を作成する​

操作:

cat > kubeconfig-${USER_NAME}.yaml <<EOF
apiVersion: v1
kind: Config
clusters:
  - name: my-fke-cluster
    cluster:
      certificate-authority-data: ${CA_B64}
      server: ${SERVER}
contexts:
  - name: ${USER_NAME}@my-fke-cluster
    context:
      cluster: my-fke-cluster
      user: ${USER_NAME}
current-context: ${USER_NAME}@my-fke-cluster
users:
  - name: ${USER_NAME}
    user:
      client-certificate-data: $(base64 -w 0 < ${USER_NAME}.crt)
      client-key-data: $(base64 -w 0 < ${USER_NAME}.key)
EOF

結果​

✅ kubeconfig-dev-nguyenvana.yaml をチームメンバーに渡せます。有効期限は 30 日です。

更新​

証明書の期限が近づいたら、手順 2.1 から 2.3 と 2.5 を繰り返します。CN と O は変わらないため、権限の設定はそのままで構いません。certificatesigningrequests の権限があれば、期限内の古い kubeconfig を使って更新することもできます。

ユースケース 3: サードパーティ製システムと連携する​

ユースケース 1 で作成した kubeconfig または token を、次のシステムに設定します。

ArgoCD​

方法 1 — CLI:

argocd cluster add argocd-deployer@my-fke-cluster \
  --kubeconfig kubeconfig-argocd-deployer.yaml

方法 2 — Declarative（cluster Secret）: Secret マニフェストの bearerToken に TOKEN、caData に CA_B64 を設定します。

Rancher（cluster のインポート）​

操作: 新しい kubeconfig で Rancher のインポートコマンドを実行します。

⚠️ Rancher agent のインストールには cluster-admin（手順 1.2 のテンプレート A）が必要です。

Jenkins​

操作:

  1. Jenkins → Manage Jenkins → Credentials を開きます。
  2. 種類が Secret file の credential を追加し、kubeconfig-argocd-deployer.yaml をアップロードします。
  3. pipeline では withKubeConfig または環境変数 KUBECONFIG から利用します。

Vault（Kubernetes auth method）​

設定:

パラメータ値
kubernetes_hostSERVER の値
kubernetes_ca_certCA_B64 をデコードした CA の内容
token_reviewer_jwtClusterRole system:auth-delegator を付与した ServiceAccount の token

5. Interface Explanation — 主なコマンドとパラメータ​

コマンド / パラメータ説明例
kubectl create serviceaccountcluster 内に service account を作成しますkubectl create sa argocd-deployer -n kube-system
kubectl create clusterrolebindingcluster 全体の権限を付与します--clusterrole=cluster-admin
kubectl create rolebinding特定 namespace 内の権限を付与します-n app-dev --clusterrole=edit
kubectl create token --duration有効期限付きの token を作成します--duration=2160h（90 日）
kubectl auth whoami現在の ID を確認しますServiceAccount または User 名を返します
kubectl auth can-i個別の権限を確認しますkubectl auth can-i create deployments
kubectl certificate approveCSR を承認します（方式 2）kubectl certificate approve dev-nguyenvana
kubectl delete secretSecret を削除して token を失効させますkubectl delete secret argocd-deployer-token
--clusterrole=cluster-admincluster 全体の権限Portal の kubeconfig と同等
--clusterrole=viewcluster 全体の読み取り専用monitoring、dashboard 向け
--clusterrole=edit読み書き可、RBAC は変更不可CI/CD、developer 向け

6. System States​

成功​

$ kubectl get nodes
NAME                    STATUS   ROLES    AGE   VERSION
fke-node-abc            Ready    <none>   10d   v1.28.x

→ kubeconfig は正常に動作し、接続は安定しています。

エラー: Unauthorized (401)​

error: You must be logged in to the server (Unauthorized)

→ token が無効か、失効しています。Common Issues & Solutions を参照してください。

エラー: Forbidden (403)​

Error from server (Forbidden): pods is forbidden: User "system:serviceaccount:kube-system:argocd-deployer" 
cannot list resource "pods" in API group "" in the namespace "default"

→ ServiceAccount にそのリソースまたは namespace の RBAC 権限がありません。権限を追加してください。

エラー: certificate error​

Unable to connect to the server: x509: certificate signed by unknown authority

→ certificate-authority-data が誤っているか、設定されていません。Portal の kubeconfig から取得し直してください。

token の作成に成功​

$ kubectl get secret argocd-deployer-token -n kube-system
NAME                     TYPE                                  DATA   AGE
argocd-deployer-token    kubernetes.io/service-account-token   3      5s

→ Secret が作成され、token が書き込まれています。利用できます。

7. Common Issues & Solutions​

事象原因対処
作成直後の token で Unauthorized (401)Secret への書き込みが完了していない、またはコピー時に改行が欠落・混入した5〜10 秒待ってから token を取得し直します。コピー時に余分な文字が入っていないか確認します
リソースへのアクセスで Forbidden (403)そのリソースまたは namespace の RBAC 権限が不足していますkubectl auth can-i --list --as=system:serviceaccount:<ns>:<sa-name> で確認し、不足分を付与します
x509: certificate signed by unknown authoritykubeconfig の certificate-authority-data が誤っているか未設定準備 P-2 に従い、Portal の kubeconfig から CA_B64 を取得し直します
CSR が Approved なのに証明書がないcluster の署名が完了していません数秒待ちます。長引く場合は kubectl get csr <名前> -o yaml で signerName が kubernetes.io/kube-apiserver-client か確認します
証明書の有効期限が要求より短いcluster 側で最長 30 日に制限されています仕様どおりです。より長い期限が必要な場合は方式 1 を使用します
kubectl create token の token が要求より短いこの種類の token は cluster 側で期限が制限されていますSecret 経由の失効しない token（方法 A）に切り替えます
メンテナンス後に kubeconfig が動作しないcluster が証明書をローテーションしましたCA_B64 と token を確認し、必要であれば作成し直します

8. Tips & Best Practices​

セキュリティ​

実施事項詳細
token は secret store に保管するVault、Jenkins Credentials、GitLab CI/CD Variables を使用し、平文で保存しません
git にコミットしない.gitignore に kubeconfig-*.yaml を追加します
漏洩が疑われたら即座に失効させるkubectl delete secret ${SA_NAME}-token -n ${NAMESPACE} を実行すると即時に無効になります
暗号化されていない経路で送らないSlack、平文メール、チャットでの送付は避けます

運用管理​

実施事項詳細
システムごとに ServiceAccount を分ける共用しません。失効させても他のシステムに影響しません
すべての credential に label を付けるkubectl label sa "$SA_NAME" -n "$NAMESPACE" managed-by=customer purpose=argocd
必要最小限の権限にするまず view または edit から始め、cluster-admin は本当に必要なときだけ使用します
credential の一覧は自分で管理する自分で作成した credential は Portal に表示されません
作成済みの credential を一覧するkubectl get sa -l managed-by=customer --all-namespaces

推奨フロー​

手順内容
1ServiceAccount を作成し、label を付けます
2必要最小限の権限を付与します
3token を取得します（有効期限付きを推奨）
4kubeconfig を作成し、kubectl auth can-i で確認します
5対象システムにインポートします
6有効期限付きの場合は更新のリマインダーを設定します

9. FAQ​

Portal から新しい kubeconfig をダウンロードすると、自分で作成した kubeconfig に影響しますか。
→ 影響しません。Portal の kubeconfig と自分で作成した credential は完全に独立しており、併用できます。

Kubernetes のアップグレード後も使えますか。
→ 使えます。アップグレードによって ServiceAccount、token、RBAC が失われることはありません。

ServiceAccount はいくつまで作成できますか。
→ 実用上の上限はありません。システムごとに 1 つという方針で作成し、使わなくなったら失効させてください。

使用中の token にどの権限があるか確認するには。
→ その token を含む kubeconfig で kubectl auth can-i --list を実行します。

cluster が証明書をローテーションした場合はどうなりますか。
→ certificate-authority-data と token の更新が必要になる場合があります。FPT Cloud からメンテナンス通知を受け取ったら、自分で作成した kubeconfig を確認してください。

cluster を削除して作り直した場合はどうなりますか。
→ 自分で作成した credential は cluster と一緒に失われます。新しい cluster で手順をやり直してください。

Portal の kubeconfig なしで証明書（方式 2）を更新できますか。
→ certificatesigningrequests の権限があれば可能です。期限内の古い kubeconfig を使用します。

本ドキュメントは FPT Managed Kubernetes Engine (M-FKE) — FPT Cloud に属します。
問題が発生した場合は FPT Cloud サポートチームにお問い合わせください。