gke-manifest-generation

GKE 清单生成技能

此技能提供指南、工具集成和模板，用于将自然语言描述或应用代码更改转化为安全、合规且经济高效的 Kubernetes YAML 清单，并针对 GKE Autopilot 和 GKE Standard 集群进行优化。

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读 使用归属信息。对于直接在终端中执行的命令（绝不能放入生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-manifest-generation)"，并在 User-Agent 标头中追加 agent-skills/1.0 (skill:gke-manifest-generation)。

核心规则与验证

生成或更新 YAML 清单时，必须严格遵守以下规则：

1. 命名空间与资源隔离

• 显式指定命名空间：始终在每个资源（Deployments、Services、ConfigMaps、Secrets、PVCs、Roles、bindings）的元数据中显式声明 namespace: {namespace}。将其映射到当前 SETTINGS.md 中配置的命名空间。绝不能省略命名空间。
• 专用 ServiceAccount：避免使用命名空间的 default ServiceAccount。始终为每个微服务创建并引用专用的 ServiceAccount（例如 devteam-agent-sa）。

2. GKE 资源调优（Autopilot 和 Standard）

• 资源请求与限制：始终为所有容器指定 CPU 和内存请求与限制。

  • GKE Autopilot：请求直接决定 Pod 计费；请求与限制必须相等。如果二者不同，Autopilot 会自动提高请求，使其与限制相等，这可能会显著增加成本。
  • GKE Standard：请求可确保调度和资源装箱保持稳定；限制则可防止资源耗尽或“吵闹邻居”问题。

• 密度默认值：对于 GKE Standard 上的无状态应用或 sidecar，默认使用保守的请求值（例如 requests.cpu: "100m" 或 "200m"、requests.memory: "256Mi" 或 "512Mi"），并设置可突发的限制。限制应采用合理的超额配置比例（例如请求的 2 倍到 4 倍，如 limits.cpu: "400m" 到 "800m"，以及 limits.memory: "512Mi" 到 "1Gi"）。避免设置过高的超额配置限制（例如对 100m 请求设置 limits.cpu: "4"），以防在高负载调度期间出现严重的 CPU 限流和延迟下降，尤其是在没有保证节点份额的环境中。

• 用于预发布和开发环境的 Spot VM：对于非生产工作负载（例如命名空间名称包含 -test、-dev 或 -staging），或者用户要求优化成本时，自动将目标设为 GKE Spot VM。必须同时注入用于指定 Spot VM 的 nodeSelector，以及用于容忍 Spot VM 污点的对应 toleration：

  nodeSelector:
    cloud.google.com/gke-spot: "true"
  tolerations:
    - key: "cloud.google.com/gke-spot"
      operator: "Equal"
      value: "true"
      effect: "NoSchedule"
  

  （在 GKE Standard 上，这要求已配置 Spot 节点池。）

3. 容器安全加固（Pod 安全标准）

• 以非 root 用户运行：始终在 Pod 级别配置 securityContext（如需覆盖，也要在容器级别配置），以非 root 用户运行（例如，runAsNonRoot: true、runAsUser: 10000、runAsGroup: 10000、fsGroup: 10000）。GKE Autopilot 会严格强制执行此要求，而这也是 GKE Standard 的关键安全基线。
• 最小权限：始终设置 allowPrivilegeEscalation: false 和 seccompProfile: {type: RuntimeDefault}。
• 根文件系统只读：设置 readOnlyRootFilesystem: true，防止修改容器镜像文件系统。
  • 可写目录回退方案：如果启用了 readOnlyRootFilesystem，请将本地 emptyDir 卷挂载到 /tmp 或 /var/run/，以便应用（如 Java/Nginx）写入临时文件而不会崩溃。
• 挂载 Secret 卷：优先将 Secret 挂载为只读文件（在 volumes 规范中配置 defaultMode: 0400），而不是将其映射为环境变量；除非应用框架仅支持基于环境变量的配置。这样可以防止 Secret 泄漏到应用日志中。

4. 健康检查（必需的探针）

• 存活探针和就绪探针：每个 Deployment 容器都必须定义 livenessProbe 和 readinessProbe。

  • Web/API：使用 httpGet 探针。
  • TCP 服务：使用 tcpSocket 探针。
  • 数据库/缓存：使用基于命令的 exec 探针（例如， exec.command: ["redis-cli", "ping"]）。

• 为启动较慢的应用配置启动探针：对于启动时间较长的应用（例如，Java Spring Boot、复杂的 Python 脚本、LLM 模型服务），还必须定义 startupProbe。定义 startupProbe 后，在其成功之前，存活探针和就绪探针会处于禁用状态，从而防止 Kubernetes 在启动期间过早终止 Pod：

  startupProbe:
    httpGet:
      path: /healthz
      port: 8080
    failureThreshold: 30
    periodSeconds: 10
  

• 合理的默认值：根据启动时间设置 initialDelaySeconds: 5 到 15（例如，Java 所需的延迟时间比 Go/Nginx 更长）。

5. 服务与 Ingress 路由

• 内部 ClusterIP：默认将所有内部微服务设为 type: ClusterIP。除非工作负载明确需要从互联网公开访问，否则切勿使用 type: LoadBalancer 或 NodePort。
• 端口命名：始终为服务端口和容器端口指定清晰、标准的名称（例如，name: http-web 或 name: grpc-api），以启用自动协议发现、跟踪和 Web App 路由。
• 优先使用 Gateway API：对外公开 API 时，优先使用 GKE Gateway API（Gateway 和 HTTPRoute 资源），而不是旧版 Ingress 对象，以启用高级 L7 路由和安全功能（例如，Cloud Armor）。

6. 卷挂载、StorageClass 与 subPath 安全性

• 避免覆盖目录：将 ConfigMap 或 Secret 挂载到包含其他文件的应用目录（例如 Nginx 公共目录）时，务必使用 subPath，仅覆盖指定文件。 注意：使用 subPath 卷挂载的容器，在底层 ConfigMap 或 Secret 修改后不会自动收到配置更新；必须手动重启 Pod 才能获取更改。
• StorageClass 选择：在 PersistentVolumeClaims 中使用正确的 GKE 存储类：
  • CSI 驱动集群（Autopilot 和现代 Standard）：使用 standard-rwo （默认平衡型 PD）或 premium-rwo（SSD PD）。
  • 旧版 Standard 集群：如果未配置 standard-rwo/premium-rwo，则使用 standard（默认 PD）或 premium （SSD PD）。
  • 数据库规则：仅当提示词明确要求高 IOPS、低延迟或数据库存储时，才使用 SSD 存储类（premium-rwo 或 premium）。

7. GKE 高可用性

• 拓扑分布：对于副本数 >1 的部署，使用 podAntiAffinity 或 topologySpreadConstraints，并将 topologyKey: "kubernetes.io/hostname" 用于在 GKE 节点和可用区之间分布 Pod。
• PodDisruptionBudget：对于副本数 >1 的部署，声明 PodDisruptionBudget，以确保在 GKE 节点自愿升级和维护期间最低副本数仍可用。

8. 更新与服务端应用协调

• 稳定的列表键：在 Kubernetes 服务端应用（SSA）中，关联列表（例如卷、卷挂载、端口和容器定义）中的元素会根据其唯一标识键（通常为 name）进行匹配和合并。修改现有列表项的属性时，必须保持 name 键稳定。重命名 name 键会导致 SSA 创建一个全新的条目，并保留旧条目（使其成为孤立条目），而不是修改旧条目。
• 最小差异：仅进行所请求的更改。严格遵循现有标签、注释和惯例。

---

专用工作负载：GKE AI/推理服务（vLLM、TGI 等）

对于模型服务工作负载，优先使用 GKE Inference Quickstart 等优化工具（如有）。如需手动生成：

1. GPU 请求与分配：
   • 始终在 requests 和 limits 中请求 nvidia.com/gpu。
   • 添加 nodeSelector 或节点亲和性，以指定目标 GKE 加速器标签（例如 cloud.google.com/gke-accelerator: nvidia-l4）。
2. 共享内存增强：
   • 模型服务需要较大的共享内存（/dev/shm）用于进程间通信。始终声明一个 emptyDir 卷，并将其 medium: Memory 挂载到 /dev/shm。
3. 权重加载优化：
   • 使用 GKE GCS Fuse CSI 驱动（csi.storage.gke.io）挂载模型权重目录（例如 GCS 存储桶），并设置 readOnly: true，以加快冷启动。

---

工具使用与依据指南

生成清单时，应使用以下工具，减少幻觉并优化配置：

1. 推理工作负载（GKE Inference Quickstart CLI）：

   • 确保已安装 Google Cloud SDK。

   • 对于所有 AI/LLM 推理工作负载（例如模型服务），必须 优先使用 gcloud CLI GKE Inference Quickstart 命令生成优化后的清单， 而不是手动编写：

     gcloud container ai profiles manifests create \
       --model={model_name} \
       --model-server={server_name} \
       --accelerator-type={accelerator_type} \
       --output=manifest \
       --output-path={output_file_path}
     

   • 限制：必须包含此命令返回的所有资源 （Deployments、Services、PodMonitoring 等），不得筛选。

2. 依据官方文档（Developer Knowledge API）：

   • 对于 GKE 特定功能、API 默认值、清单示例或安全上下文， 必须查询 Google 的开发者知识库，以获取官方 GKE 文档：
     • answer_query：用于提出直接问题（例如 “如何在 GKE 中配置 GCS Fuse CSI 驱动程序”）。对于一般查询， 首选此工具。
     • search_documents：在没有具体问题时，用于搜索相关的 GKE 指南 或示例。
     • get_document：在有特定文档 ID 时，用于获取完整文档内容。

---

参考示例

如需详细且可用于生产环境的清单模板，请参阅以下参考指南：

• 基础加固型 Nginx 工作负载： 可用于生产环境的部署，包含专用服务账号、安全上下文、探针、 反亲和性和 PodDisruptionBudget。
• 网络策略：默认拒绝入站流量的 网络策略，以及针对特定应用选择性允许入站流量。
• AI/LLM 推理工作负载：GPU 资源 分配、Workload Identity、GCS FUSE CSI 驱动程序挂载、/dev/shm 共享内存增强，以及启动探针。
• GKE Gateway API 路由：使用 GKE L7 Gateway API （Gateway 和 HTTPRoute 资源）对外暴露工作负载。