huawei-cloud-kubectl-cce-installer

用途

本技能用于通过 kubectl cce 检索华为云 CCE 集群中的特定 Kubernetes 资源。资源访问是主要任务；本地安装仅在 kubectl 或 kubectl-cce 插件不可用时作为前置恢复步骤。

主要能力

使用 kubectl cce 查询资源，不使用直接的 Kubernetes API 客户端。
仅限只读命令：get、describe、logs。
禁止使用 -A、--all-namespaces 或其他全集群资源查询。
对于命名空间级资源，要求提供 --namespace <namespace>，并在可行时指定具体资源名。
对于集群级资源（如 node、namespace、persistentvolume、storageclass），要求提供精确资源名，不得列出全部实例。
禁止运行 apply、create、delete、edit、patch、replace、scale、rollout、cordon、drain、exec。
不得打印凭据、令牌、kubeconfig 内容或 Secret 数据。

使用方式

前置条件与必需上下文

cluster_id：必需，标准 UUID。可用 hcloud CCE ListClusters 解析精确名称，但在解析为单个 UUID 之前不得运行 kubectl cce。
region：必需。从请求或当前上下文获取，然后使用 HW_REGION_NAME；否则询问用户。
资源类型：必需，例如 pod、deployment、service、configmap 或 node。
命名空间或精确名称：至少提供其一。命名空间级资源需要命名空间；集群级资源需要精确名称。
凭据遵循 plugin-usage.md 中的插件规则。仅当调用方提供时，才使用显式的 --cli-access-key、--cli-secret-key 以及可选的 --cli-security-token；此时不得回退到其他凭据。

工作流程

在任何资源查询之前，验证目标 region 和 cluster ID。如果任一缺失，或 cluster ID 无法在该 region 中解析为单个已存在的 UUID，则不要运行 kubectl cce；请用户提供正确的 region 和 cluster ID。
确认资源类型、命名空间，以及需要时的精确资源名。
检查本地前置条件：

bash scripts/install_kubectl_cce.sh --check

当 kubectl 和 kubectl-cce 均可用时，查询所请求的资源。
当任一可执行文件缺失时，阅读 installation.md，然后展示安装计划。安装或替换属于 R1 本地变更，需要显式确认：

bash scripts/install_kubectl_cce.sh --bin-dir <directory>
sudo bash scripts/install_kubectl_cce.sh --execute --bin-dir <directory>

使用 kubectl version --client 和 kubectl plugin list 验证安装，然后仅运行所请求的只读资源查询。

核心命令

每次命名空间级查询使用一个显式命名空间：

kubectl cce --cluster-id <cluster-id> --region <region> \
  get pod <pod-name> --namespace <namespace> -o yaml

kubectl cce --cluster-id <cluster-id> --region <region> \
  describe deployment <deployment-name> --namespace <namespace>

kubectl cce --cluster-id <cluster-id> --region <region> \
  get service <service-name> --namespace <namespace> -o yaml

对于集群级资源，使用精确名称：

kubectl cce --cluster-id <cluster-id> --region <region> \
  get node <node-name> -o yaml

关于凭据模式、命令形式和 x509 重试行为，请阅读 plugin-usage.md。关于 Windows 使用和安装回退，请阅读 installation.md。如果命令因 x509 上游 TLS 验证错误失败，请在 cce 之后立即使用 --cce-insecure-upstream-tls=true 重试同一命令一次。

风险等级

资源查询和本地前置条件检查：R3，可自动运行。
本地二进制安装、源码构建或插件替换：R1，先预览，并在 --execute 前要求显式确认。

输出格式

返回 cluster ID、region、资源类型、适用时的命名空间、资源名称，以及所请求的状态或字段。明确说明资源是未找到、访问被拒绝、缺少前置条件，还是需要安装确认。

参数与确认

在发出查询前，确认 cluster_id、region、资源类型、命名空间和精确资源名。如果 cluster_id 缺失或无法在提供的 region 中解析，停止并请用户提供正确的 region 和 cluster ID。在任何 --execute 操作前确认目标安装目录。

验证

安装后，运行 kubectl version --client 和 kubectl plugin list；查询后，验证返回的资源身份与所请求的集群、命名空间和名称匹配。

适用场景

需要查看、描述或检查 CCE 集群中特定 Pod、Deployment、Service、ConfigMap、Node 等资源的详细信息。
需要获取特定资源的日志。
本地缺少 kubectl 或 kubectl-cce 插件，需要按流程安装或替换。

限制

仅限只读操作，禁止任何写操作或执行命令。
禁止全集群范围查询，必须限定命名空间或精确资源名。
不得输出敏感凭据或 Secret 数据。
当请求的资源无法限定到命名空间或精确名称时，应请用户缩小目标，而不是扩大为集群范围查询。
安装或替换本地二进制需要显式确认。

参考文档

Plugin Usage：凭据、命令形式和 x509 重试。
Installation：本地前置条件、安装器参数、Windows 使用、源码回退、确认和故障排除。
Acceptance Criteria：资源查询和安装验收检查。