访问 Sutroplanet Kubernetes 集群

本文档将指导您如何通过 OIDC 认证访问 Sutroplanet 的 Kubernetes 集群。

前提条件

已连接 Sutroplanet VPN（参考 VPN 连接教程）
已安装 kubectl

管理员配置：Authentik OAuth2/OIDC Provider

Kubernetes CLI 属于无法安全保存共享客户端密钥的本地应用。Authentik 中的 Kubernetes Provider 应使用以下配置：

Client Type：Public
Grant Types：只启用 Authorization Code 和 Refresh token
Redirect URIs：http://localhost:8000、http://localhost:18000
Scopes：openid、profile、groups、offline_access，以及下方自定义的 email Scope Mapping

请勿启用 Implicit、Hybrid、Client credentials 或 Password Grant。只有明确采用 Device Authorization Flow 时才启用 Device-code。

由于 Kubernetes API Server 使用邮箱作为 OIDC 用户名，需要创建名为 Kubernetes verified email、Scope name 为 email 的 Scope Mapping：

return {
    "email": request.user.email,
    "email_verified": True,
}

仅当注册或身份源确实验证了用户邮箱时，才应返回 email_verified: True。在 Provider 的 Scopes 中使用此 Mapping 替换 Authentik 默认的 OpenID 'email' Mapping。

Public Client 通过 PKCE 保护 Authorization Code Flow，因此不需要向用户分发 client_secret。如果 Provider 以前使用 Confidential Client，应轮换或作废旧 secret，并从 kubeconfig、文档及 Git 历史中移除。

第一步：注册 Authentik 账号

打开 authentik.sutroplanet.com
点击登录页底部的 Sign up 链接
填写用户名、邮箱和密码，提交注册
检查您的邮箱，点击验证链接完成注册
联系管理员 (fhan0520@gmail.com) 将您的账号加入对应的 Kubernetes 用户组（如 k8s-users、k8s-agentforge、k8s-storyorbit 等），否则您将无法访问集群资源

第二步：安装 kubectl（如未安装）

如果您还没有安装 kubectl：

macOS:

brew install kubectl

Linux:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

Windows:

下载 kubectl.exe，放到 PATH 目录中。

第三步：安装 kubelogin 插件

kubelogin 是 kubectl 的 OIDC 认证插件，用于通过浏览器登录获取令牌，并使用缓存的刷新令牌自动续期。

macOS:

brew install int128/kubelogin/kubelogin

Linux:

curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip
unzip kubelogin_linux_amd64.zip
sudo mv kubelogin /usr/local/bin/kubectl-oidc_login

Windows:

从 kubelogin releases 下载 kubelogin_windows_amd64.zip，解压后将 kubelogin.exe 重命名为 kubectl-oidc_login.exe，放到 PATH 目录中。

安装完成后验证：

kubectl oidc-login --help

第四步：配置 kubeconfig

将以下内容保存为 ~/.kube/config（如果已有其他集群配置，可以保存为 ~/.kube/sutro-config 并通过 KUBECONFIG 环境变量指定）：

apiVersion: v1
kind: Config
clusters:
- cluster:
    server: https://sutroplanet.com:6443
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJkekNDQVIyZ0F3SUJBZ0lCQURBS0JnZ3Foa2pPUFFRREFqQWpNU0V3SHdZRFZRUUREQmhyTTNNdGMyVnkKZG1WeUxXTmhRREUzTmpBM05EY3hNak13SGhjTk1qVXhNREU0TURBeU5USXpXaGNOTXpVeE1ERTJNREF5TlRJegpXakFqTVNFd0h3WURWUVFEREJock0zTXRjMlZ5ZG1WeUxXTmhRREUzTmpBM05EY3hNak13V1RBVEJnY3Foa2pPClBRSUJCZ2dxaGtqT1BRTUJCd05DQUFSYzVIcjl3SlVFSlJBVndyaVF3N2w5YXc5bEdtVFM2QXIrbGZzT3BkKzkKeENiVUE0TUpUWFY4cjBza2FIVUczUm5qVkVmUExIVVZLOEV6ZnlmYTRoNVFvMEl3UURBT0JnTlZIUThCQWY4RQpCQU1DQXFRd0R3WURWUjBUQVFIL0JBVXdBd0VCL3pBZEJnTlZIUTRFRmdRVWpoY3RuQVQwTlBieFdqMzgzamhZCkdTUnlUK1F3Q2dZSUtvWkl6ajBFQXdJRFNBQXdSUUlnVUJDSGYxNWFrNEI2NlpxbUlyY0d3SzJFcDYvL3V6RnQKK09XSWUyMm1KT2tDSVFEQVdRRHpFVXBmdnVIRWMrNEpPZkhFT0h6OS9YRVNtcFhoV24vYmZwUkliQT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
  name: sutro-cluster
contexts:
- context:
    cluster: sutro-cluster
    user: oidc-user
    namespace: storyorbit
  name: sutro
current-context: sutro
users:
- name: oidc-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: kubectl
      args:
        - oidc-login
        - get-token
        - --oidc-issuer-url=https://authentik.sutroplanet.com/application/o/kubernetes/
        - --oidc-client-id=bszmEYTqWfb0B7A9M6GfiWgXYpvpWn9wcB0eIhNn
        - --grant-type=authcode
        - --oidc-pkce-method=S256
        - --oidc-extra-scope=email
        - --oidc-extra-scope=profile
        - --oidc-extra-scope=groups
        - --oidc-extra-scope=offline_access
        - --token-cache-storage=keyring
      interactiveMode: IfAvailable

此配置使用 Public Client + PKCE，不包含也不需要 client_secret。Client ID 不是秘密，可以包含在文档和 kubeconfig 中。示例默认使用 storyorbit 命名空间；如果管理员分配了其他命名空间（例如 agentforge），请相应修改 namespace。

如果保存为单独文件，使用前设置环境变量：

export KUBECONFIG=~/.kube/sutro-config
chmod 600 ~/.kube/sutro-config

第五步：登录并验证

运行任意 kubectl 命令触发登录：

kubectl get pods

首次登录时浏览器会自动打开 Authentik 登录页面。登录成功后，kubelogin 会缓存刷新令牌；5 分钟的访问令牌过期后会自动续期，正常情况下无需每 5 分钟重新登录。刷新令牌过期或被撤销后，下一次 kubectl 命令会再次要求浏览器登录。

示例将 token 缓存保存在操作系统 Keychain 中。如果当前系统没有可用的 Keychain/Secret Service，可删除 kubeconfig 中的 --token-cache-storage=keyring，回退到 kubelogin 默认的磁盘缓存；此时务必保护 ~/.kube/cache/oidc-login 的访问权限。

验证您的权限：

# 列出命名空间（需要 k8s-users 用户组）
kubectl get namespaces

# 查看 StoryOrbit 命名空间的 Pod
kubectl get pods -n storyorbit

# 查看当前用户及 OIDC 用户组
kubectl auth whoami -o json

# 验证 StoryOrbit 部署权限
kubectl auth can-i create deployments.apps -n storyorbit

权限说明

您的访问权限由管理员在 Authentik 中分配的用户组决定：

用户组	权限范围
`k8s-users`	可以列出集群中的命名空间（只读）
`k8s-agentforge`	在 `agentforge` 命名空间内拥有完整的管理权限
`k8s-storyorbit`	在 `storyorbit` 命名空间内拥有管理权限

如果您在执行操作时收到 Forbidden 错误，说明您的账号没有对应资源的权限，请联系管理员。

常见问题

登录后仍然报 Unauthorized

清除本地缓存的 token 后重试：

kubectl oidc-login clean
kubectl get pods -n storyorbit

如果管理员刚将 Provider 从 Confidential Client 改为 Public Client，也必须先清理旧缓存，并确认 kubeconfig 中已经删除 --oidc-client-secret。

浏览器没有自动打开

手动复制终端中显示的 URL 到浏览器中打开。

Token 过期或需要强制重新登录

kubelogin 会使用缓存的刷新令牌自动续期，无需手动操作。刷新令牌过期或被撤销后，重新运行 kubectl 命令并按提示登录。需要强制重新登录时：

kubectl oidc-login clean
kubectl get pods -n storyorbit

刷新令牌是有效期较长的凭据。请勿共享 kubeconfig 或 ~/.kube/cache/oidc-login；在共享设备上使用完毕后请运行 kubectl oidc-login clean。

连接超时

确保 VPN 已连接，并且可以访问 sutroplanet.com:6443：

curl -k https://sutroplanet.com:6443/healthz

联系管理员

如有问题请联系: Fang Han fhan0520@gmail.com

Sutroplanet Datacenter Wiki (Public)