Yuma 内部服务与 K3s 集群接入

证书身份

安装 Root CA

仅访问使用 Yuma 内部 PKI 的 HTTPS 服务时执行。只安装 Root 公共证书，不安装 Issuing CA 或任何私钥。Root CA 用于验证服务端证书，不能替代 Kubernetes Token 认证或延长其有效期。

curl -fsSLO https://trust.yuma.technology/install/linux.sh
less linux.sh
sudo sh linux.sh

curl -fsSLO https://trust.yuma.technology/install/macos.sh
less macos.sh
sudo sh macos.sh
export SSL_CERT_FILE='/Library/Application Support/Yuma/trust/ca-bundle.pem'

Invoke-WebRequest -UseBasicParsing `
  -Uri "https://trust.yuma.technology/install/windows.ps1" `
  -OutFile "$env:TEMP\install-yuma-ca.ps1"
notepad "$env:TEMP\install-yuma-ca.ps1"
Get-ExecutionPolicy -List
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& "$env:TEMP\install-yuma-ca.ps1"

K3s 集群访问配置

以下流程从 stable target catalog 加载明确声明的 developer identity。不要手工拼接凭据，也不要用环境名代替完整的 cluster target。

curl -fsSL https://center.devops.yuma.technology/install/cli/yuma-cluster-target-ops-cli.sh | sh
yuma-cluster-target-ops-cli --version

yuma-cluster-target-ops-cli targets sync --channel stable
yuma-cluster-target-ops-cli targets list

yuma-cluster-target-ops-cli sync-kubeconfig-set \
  --access live-deploy \
  --target hydros-cluster-testing \
  --target hydros-cluster-staging \
  --target hydros-cluster-production \
  --allow-production-deploy \
  --apply

yuma-cluster-target-ops-cli sync-kubeconfig-set \
  --access live-deploy \
  --target hydros-cluster-testing \
  --target hydros-cluster-staging \
  --apply

yuma-cluster-target-ops-cli sync-kubeconfig \
  hydros-cluster-production \
  --access readonly \
  --apply

验证连接

先确认 context 已写入，再用每个 identity 访问目标 namespace。不要仅凭能够访问另一个集群的入口判断当前 target 成功。

kubectl config get-contexts

kubectl --context hydros-cluster-testing-live-deploy -n hydros get pods
kubectl --context hydros-cluster-staging-live-deploy -n hydros get pods
kubectl --context hydros-cluster-production-live-deploy -n hydros get pods

• context 名称、cluster target 和 access 后缀一致。
• 命令仅访问预期集群与 namespace。
• production 的实际 access 与 target catalog 声明一致。

live-deploy / readonly 凭据过期

以下错误表示 Kubernetes 没有接受当前 identity，常见原因是 kubeconfig 内的短期 JWT 已过期，不能按 RBAC 问题处理：

the server has asked for the client to provide credentials
You must be logged in to the server

开发者：先预检，再重新同步同一 identity

yuma-cluster-target-ops-cli sync-kubeconfig \
  hydros-cluster-staging \
  --target-source catalog \
  --access live-deploy

# 仅当预检中的 credential expiry 和 API authentication 均为 ok 时写入
yuma-cluster-target-ops-cli sync-kubeconfig \
  hydros-cluster-staging \
  --target-source catalog \
  --access live-deploy \
  --apply

kubectl --context hydros-cluster-staging-live-deploy auth whoami
kubectl --context hydros-cluster-staging-live-deploy \
  -n hydros get deployments

请把示例 target 和 access 替换为实际授权。live-deploy 的常规授权范围是业务 namespace；不要用无权读取的 hydros-system 资源判断凭据是否有效。

production live-deploy 的预检与同步还必须显式传 --allow-production-deploy：

yuma-cluster-target-ops-cli sync-kubeconfig \
  hydros-cluster-production \
  --target-source catalog \
  --access live-deploy \
  --allow-production-deploy

Operator：重新签发并发布 stable

自 CLI 0.4.9 起，live-deploy / readonly 的默认有效期为 90 天（2160h），适用于 candidate / stable，不是三个自然月。先确认 target、access 和现有 RBAC。下面是 production live-deploy 故障恢复示例；production 访问仍需显式授权：

yuma-cluster-target-ops-cli kubeconfig publish-developer \
  hydros-cluster-production \
  --target-source deployment-local \
  --kube-context hydros-cluster-production-admin \
  --access-mode live-deploy \
  --allow-production-deploy \
  --channel stable \
  --token-duration 2160h \
  --skip-rbac \
  --artifact-center-url <artifact-center-url> \
  --apply \
  --json

--skip-rbac 只适用于现有 ServiceAccount 和 RBAC 绑定已验证、此次仅轮换凭据的场景。非默认命名必须显式传 --service-account <existing-service-account>。示例显式传入 --token-duration 2160h 以兼容旧 CLI。API Server 可能缩短请求期限，以发布后 consumer 预检输出的实际 credential expires at 为准。升级 CLI 不会延长已有凭据，必须重新签发、发布并同步同一 access。

发布后验证与轮换

yuma-cluster-target-ops-cli sync-kubeconfig \
  hydros-cluster-production \
  --target-source catalog \
  --access live-deploy \
  --allow-production-deploy \
  --json

• 必须看到新的 version/artifact ID、credential expiry: ok 和 API authentication: ok，再通知开发者执行带 --apply 的同步。
• target catalog 的 available 只表示存在 stable artifact 引用，不证明其中 JWT 尚未过期。
• operator 应在到期前 7 天、3 天和 1 天巡检并告警，在到期前完成新 stable 制品发布和 consumer 验证。

如何区分认证与 RBAC

• Unauthorized、provide credentials、You must be logged in：先处理凭据同步/重发。
• Forbidden：身份已经通过认证，但目标 namespace 的 RBAC 不足，请 operator 检查对应 ServiceAccount 和 RoleBinding。

Windows 与 WSL

Windows 原生终端与 WSL 使用不同的 home、Root CA trust store 和 kubeconfig。在哪个环境执行 kubectl，就必须在哪个环境安装信任并同步 kubeconfig；只更新其中一侧不会自动更新另一侧。

常见问题