gke-manifest-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GKE Manifest Generation Skill

GKE清单生成技能

This skill provides guidelines, tooling integration, and templates to translate natural language descriptions or application code changes into secure, compliant, and cost-effective Kubernetes YAML manifests optimized for both GKE Autopilot and GKE Standard clusters.

本技能提供指南、工具集成和模板，可将自然语言描述或应用代码变更转换为针对GKE Autopilot和GKE Standard集群优化的、安全合规且具成本效益的Kubernetes YAML清单。

Core Rules & Verification

核心规则与验证

When generating or updating YAML manifests, you must strictly adhere to the following rules:

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

1. Namespace & Resource Isolation

1. 命名空间与资源隔离

Explicit Namespace: Always declare
```
namespace: {namespace}
```
explicitly in the metadata of every resource (Deployments, Services, ConfigMaps, Secrets, PVCs, Roles, bindings). Map it to the namespace configured in your active
```
SETTINGS.md
```
. Never omit the namespace.
Dedicated ServiceAccount: Avoid using the namespace's
```
default
```
ServiceAccount. Always create and reference a dedicated
```
ServiceAccount
```
(e.g.,
```
devteam-agent-sa
```
) for each microservice.

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

2. GKE Resource Tuning (Autopilot & Standard)

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

Resources Requests & Limits: Always specify CPU and Memory requests and limits for all containers.
- GKE Autopilot: Requests determine pod billing directly; requests and limits must be equal. If they differ, Autopilot will automatically scale requests up to match limits, which can significantly increase costs.
- GKE Standard: Requests ensure stable scheduling and bin-packing; limits prevent resource starvation/noisy-neighbor issues.
Density Defaults: For stateless apps or sidecars on GKE Standard, default to conservative requests (e.g.,
```
requests.cpu: "100m"
```
or
```
"200m"
```
,
```
requests.memory: "256Mi"
```
or
```
"512Mi"
```
) with burstable limits. Use a reasonable overcommit ratio for limits (e.g., 2x to 4x requests, like
```
limits.cpu: "400m"
```
to
```
"800m"
```
, and
```
limits.memory: "512Mi"
```
to
```
"1Gi"
```
). Avoid excessive overcommit limits (like
```
limits.cpu: "4"
```
for a
```
100m
```
request) to prevent severe CPU throttling and latency degradation under heavy scheduling load, particularly in environments without guaranteed node shares.
Spot VMs for Staging/Dev: For non-production workloads (e.g., namespaces containing
```
-test
```
,
```
-dev
```
, or
```
-staging
```
), or if the user requests cost optimization, automatically target GKE Spot VMs. This requires injecting both the
```
nodeSelector
```
targeting Spot VMs AND the corresponding toleration to tolerate the Spot VM taint:
yaml
```
nodeSelector:
  cloud.google.com/gke-spot: "true"
tolerations:
  - key: "cloud.google.com/gke-spot"
    operator: "Equal"
    value: "true"
    effect: "NoSchedule"
```
(On GKE Standard, this assumes a Spot node pool is configured).

资源请求与限制：始终为所有容器指定CPU和内存的请求（requests）与限制（limits）。
- GKE Autopilot：请求值直接决定Pod计费；请求值与限制值必须相等。若两者不同，Autopilot会自动将请求值扩容至与限制值匹配，这可能大幅增加成本。
- GKE Standard：请求值确保调度稳定和资源打包效率；限制值可防止资源耗尽或“噪声邻居”问题。
密度默认值：针对GKE Standard上的无状态应用或边车容器，默认使用保守的请求值（例如
```
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
```
和对应的容忍度（toleration），以容忍Spot VM的污点：
yaml
```
nodeSelector:
  cloud.google.com/gke-spot: "true"
tolerations:
  - key: "cloud.google.com/gke-spot"
    operator: "Equal"
    value: "true"
    effect: "NoSchedule"
```
（在GKE Standard上，此配置假设已配置Spot节点池）。

3. Container Security Hardening (Pod Security Standards)

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

Non-Root Execution: Always configure
```
securityContext
```
at the Pod level (and container level if overriding) to run as a non-root user (e.g.,
```
runAsNonRoot: true
```
,
```
runAsUser: 10000
```
,
```
runAsGroup: 10000
```
,
```
fsGroup: 10000
```
). This is strictly enforced on GKE Autopilot and is a critical security baseline for GKE Standard.

Minimal Privileges: Always set

allowPrivilegeEscalation: false

and

seccompProfile: {type: RuntimeDefault}

Read-Only Root Filesystem: Set
```
readOnlyRootFilesystem: true
```
to prevent modifications to the container image filesystem.
- Writable Directory Fallback: If
```
readOnlyRootFilesystem
```
  is enabled, mount a local
```
emptyDir
```
  volume to
```
/tmp
```
  or
```
/var/run/
```
  to allow applications (like Java/Nginx) to write temp files without crashing.
Secret Volume Mounting: Prefer mounting Secrets as read-only files (configured in the
```
volumes
```
spec with
```
defaultMode: 0400
```
) instead of mapping them as environment variables, unless the application framework exclusively supports env-var based configuration. This prevents secrets leaking into application logs.

非根用户执行：始终在Pod级别（若需覆盖则在容器级别）配置
```
securityContext
```
，以非根用户身份运行（例如
```
runAsNonRoot: true
```
，
```
runAsUser: 10000
```
，
```
runAsGroup: 10000
```
，
```
fsGroup: 10000
```
）。这在GKE Autopilot上是强制要求，也是GKE Standard的关键安全基线。

最小权限：始终设置

allowPrivilegeEscalation: false

和

seccompProfile: {type: RuntimeDefault}

。

只读根文件系统：设置
```
readOnlyRootFilesystem: true
```
以防止修改容器镜像文件系统。
- 可写目录 fallback：若启用
```
readOnlyRootFilesystem
```
  ，需挂载本地
```
emptyDir
```
  卷到
```
/tmp
```
  或
```
/var/run/
```
  ，以允许应用（如Java/Nginx）写入临时文件而不崩溃。
密钥卷挂载：优先将Secrets以只读文件形式挂载（在
```
volumes
```
配置中设置
```
defaultMode: 0400
```
），而非映射为环境变量，除非应用框架仅支持基于环境变量的配置。这可防止密钥泄露到应用日志中。

4. Health Checking (Mandatory Probes)

4. 健康检查（强制探针）

Liveness & Readiness Probes: Every Deployment container must define both
```
livenessProbe
```
and
```
readinessProbe
```
.
- Web/API: Use
```
httpGet
```
  probes.
- TCP Services: Use
```
tcpSocket
```
  probes.
- Databases/Caches: Use command-based
```
exec
```
  probes (e.g.,
```
exec.command: ["redis-cli", "ping"]
```
  ).
Startup Probes for Slow-Starting Apps: For applications with slow boot times (e.g., Java spring boot, complex Python scripts, LLM model servers), you must also define a
```
startupProbe
```
. When a
```
startupProbe
```
is defined, the liveness and readiness probes are disabled until it succeeds, preventing Kubernetes from prematurely killing the pod during startup:
yaml
```
startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30
  periodSeconds: 10
```
Sensible Defaults: Set
```
initialDelaySeconds: 5
```
to
```
15
```
depending on startup time (e.g., Java requires a longer delay than Go/Nginx).

存活与就绪探针：每个Deployment容器必须同时定义
```
livenessProbe
```
和
```
readinessProbe
```
。
- Web/API：使用
```
httpGet
```
  探针。
- TCP服务：使用
```
tcpSocket
```
  探针。
- 数据库/缓存：使用基于命令的
```
exec
```
  探针（例如
```
exec.command: ["redis-cli", "ping"]
```
  ）。
慢启动应用的启动探针：针对启动时间较长的应用（如Java Spring Boot、复杂Python脚本、LLM模型服务器），必须同时定义
```
startupProbe
```
。当定义
```
startupProbe
```
后，存活和就绪探针会在其成功前禁用，防止Kubernetes在启动阶段过早终止Pod：
yaml
```
startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30
  periodSeconds: 10
```
合理默认值：根据启动时间设置
```
initialDelaySeconds: 5
```
至
```
15
```
（例如Java所需延迟比Go/Nginx更长）。

5. Services & Ingress Routing

5. 服务与Ingress路由

Internal ClusterIP: Default all internal microservices to
```
type: ClusterIP
```
. Never use
```
type: LoadBalancer
```
or
```
NodePort
```
unless the workload is explicitly intended to be publicly accessible from the internet.
Port Naming: Always assign clear, standard names to service and container ports (e.g.,
```
name: http-web
```
or
```
name: grpc-api
```
) to enable automatic protocol discovery, tracing, and Web App routing.
Prefer Gateway API: When exposing APIs externally, prioritize using GKE Gateway API (
```
Gateway
```
and
```
HTTPRoute
```
resources) over legacy
```
Ingress
```
objects to enable advanced L7 routing and security features (e.g., Cloud Armor).

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

6. Volume Mounts, StorageClasses & subPath Safety

6. 卷挂载、StorageClass与subPath安全

Avoid Directory Overwrites: When mounting a
```
ConfigMap
```
or
```
Secret
```
to an application directory containing other files (like Nginx public directories), always use
```
subPath
```
to overlay only the specific file. Caveat: Note that containers using
```
subPath
```
volume mounts do not receive automatic configuration updates if the underlying ConfigMap or Secret is modified; pods must be restarted manually to pick up changes.
StorageClass Selection: Use the correct GKE storage class in PersistentVolumeClaims:
- CSI Driver Clusters (Autopilot & Modern Standard): Use
```
standard-rwo
```
  (default balanced PD) or
```
premium-rwo
```
  (SSD PD).
- Legacy Standard Clusters: Use
```
standard
```
  (default PD) or
```
premium
```
  (SSD PD) if
```
standard-rwo
```
  /
```
premium-rwo
```
  are not configured.
- Database rule: Use SSD storage classes (
```
premium-rwo
```
  or
```
premium
```
  ) only when the prompt explicitly requests high IOPS, low latency, or database storage.

避免目录覆盖：将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. High Availability on GKE

7. GKE高可用性

Topology Spread: For deployments with >1 replica, use
```
podAntiAffinity
```
or
```
topologySpreadConstraints
```
with
```
topologyKey: "kubernetes.io/hostname"
```
to distribute pods across GKE nodes and availability zones.
PodDisruptionBudget: For deployments with >1 replica, declare a
```
PodDisruptionBudget
```
to guarantee minimum replica availability during voluntary GKE node upgrades and maintenance cycles.

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

8. Updates & Server-Side Apply Reconciliations

8. 更新与Server-Side Apply协调

Stable List Keys: Under Kubernetes Server-Side Apply (SSA), elements in associative lists (like volumes, volume mounts, ports, and container definitions) are matched and merged by their unique identifier keys (typically
```
name
```
). You must keep the
```
name
```
key stable when modifying properties of an existing list item. Renaming the
```
name
```
key will cause SSA to create a brand new entry and leave the old entry intact (orphaned) rather than modifying it.
Minimal Diff: Make only the changes requested. Adhere closely to existing labels, annotations, and conventions.

稳定列表键：在Kubernetes Server-Side Apply（SSA）下，关联列表（如volumes、volume mounts、ports和container定义）中的元素通过其唯一标识键（通常为
```
name
```
）进行匹配和合并。修改现有列表项的属性时，必须保持
```
name
```
键稳定。重命名
```
name
```
键会导致SSA创建全新条目并保留旧条目（孤立），而非修改原有条目。
最小差异：仅进行请求的变更。严格遵循现有标签、注解和约定。

Specialty Workloads: GKE AI/Inference Serving (vLLM, TGI, etc.)

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

For model serving workloads, prioritize using optimized tooling like GKE Inference Quickstart if available. If generating manually:

GPU Request & Allocation:
- Always request
```
nvidia.com/gpu
```
  in both
```
requests
```
  and
```
limits
```
  .
- Add a
```
nodeSelector
```
  or node affinity targeting the desired GKE accelerator tag (e.g.,
```
cloud.google.com/gke-accelerator: nvidia-l4
```
  ).
Shared Memory Boost:
- Model servers require high shared memory (
```
/dev/shm
```
  ) for inter-process communications. Always declare and mount an
```
emptyDir
```
  volume with
```
medium: Memory
```
  to
```
/dev/shm
```
  .
Weight Loading Optimization:
- Mount model weight directories (like GCS buckets) using the GKE GCS Fuse CSI driver (
```
csi.storage.gke.io
```
  ) as
```
readOnly: true
```
  for efficient cold-starts.

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

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

Tooling & Grounding Guidelines

工具与参考指南

When generating manifests, you should leverage the following tooling to reduce hallucinations and optimize configurations:

Inference Workloads (GKE Inference Quickstart CLI):
- Make sure you have the Google Cloud SDK installed.
- For all AI/LLM inference workloads (e.g. model serving), you must prioritize using the
```
gcloud
```
  CLI GKE Inference Quickstart command to generate the optimized manifests instead of writing them manually:
  bash
```
gcloud container ai profiles manifests create \
  --model={model_name} \
  --model-server={server_name} \
  --accelerator-type={accelerator_type} \
  --output=manifest \
  --output-path={output_file_path}
```
- Constraint: You must include all resources returned by this command (Deployments, Services, PodMonitoring, etc.) without filtering.
Grounding in Official Documentation (Developer Knowledge API):
- For GKE-specific features, API defaults, manifest examples, or security contexts, you must query Google's developer knowledge base to retrieve official GKE documentation:
  - answer_query
    : Use this to ask direct questions (e.g., "How to configure GCS Fuse CSI driver in GKE"). This is the preferred tool for general queries.
  - search_documents
    : Use this to search for relevant GKE guides or examples when you don't have a specific question.
  - get_document
    : Use this to fetch full document contents when you have a specific document ID.

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

推理工作负载（GKE Inference Quickstart CLI）:
- 确保已安装Google Cloud SDK。
- 针对所有AI/LLM推理工作负载（如模型服务），必须优先使用
```
gcloud
```
  CLI的GKE Inference Quickstart命令生成优化清单，而非手动编写：
  bash
```
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等），不得过滤。
官方文档参考（开发者知识API）:
- 针对GKE特定功能、API默认值、清单示例或安全上下文，必须查询Google开发者知识库以获取官方GKE文档：
  - answer_query
    ：用于直接提问（例如*"如何在GKE中配置GCS Fuse CSI驱动"*）。这是通用查询的首选工具。
  - search_documents
    ：当没有特定问题时，用于搜索相关GKE指南或示例。
  - get_document
    ：当拥有特定文档ID时，用于获取完整文档内容。

Reference Examples

参考示例

For detailed, production-ready manifest templates, consult the following reference guides:

Basic Hardened Nginx Workload: Production-ready deployment with dedicated service account, security contexts, probes, anti-affinity, and PodDisruptionBudget.
Network Policy: Default-deny ingress network policy and selective ingress allowance for specific apps.
AI/LLM Inference Workload: GPU resource allocation, Workload Identity, GCS FUSE CSI driver mounting,
```
/dev/shm
```
shared memory boost, and startup probes.
GKE Gateway API Routing: Exposing workloads using GKE L7 Gateway API (
```
Gateway
```
and
```
HTTPRoute
```
resources).

如需详细的生产就绪清单模板，请查阅以下参考指南：

基础加固Nginx工作负载：包含专用ServiceAccount、安全上下文、探针、反亲和性和PodDisruptionBudget的生产就绪部署。
网络策略：默认拒绝Ingress的网络策略，以及针对特定应用的选择性Ingress允许规则。
AI/LLM推理工作负载：GPU资源分配、Workload Identity、GCS FUSE CSI驱动挂载、
```
/dev/shm
```
共享内存优化和启动探针。
GKE Gateway API路由：使用GKE L7 Gateway API（
```
Gateway
```
和
```
HTTPRoute
```
资源）暴露工作负载。