k8s-manifest-generator

Kubernetes 清单生成器

分步指导，帮助创建可用于生产环境的 Kubernetes 清单，包括 Deployment、Service、ConfigMap、Secret 和 PersistentVolumeClaim。

用途

此技能提供全面指导，帮助按照云原生最佳实践和 Kubernetes 约定，生成结构良好、安全且可用于生产环境的 Kubernetes 清单。

适用场景

在需要以下操作时使用此技能：

• 创建新的 Kubernetes Deployment 清单
• 定义用于网络连接的 Service 资源
• 生成用于配置管理的 ConfigMap 和 Secret 资源
• 为有状态工作负载创建 PersistentVolumeClaim 清单
• 遵循 Kubernetes 最佳实践和命名约定
• 实现资源限制、健康检查和安全上下文
• 设计适用于多环境部署的清单

分步工作流

1. 收集需求

了解工作负载：

• 应用类型（无状态/有状态）
• 容器镜像和版本
• 环境变量和配置需求
• 存储需求
• 网络暴露需求（内部/外部）
• 资源需求（CPU、内存）
• 扩缩容需求
• 健康检查端点

需要询问的问题：

• 应用名称和用途是什么？
• 将使用哪个容器镜像和标签？
• 应用是否需要持久化存储？
• 应用会暴露哪些端口？
• 是否需要任何密钥或配置文件？
• CPU 和内存需求是什么？
• 应用是否需要对外暴露？

2. 创建 Deployment 清单

遵循以下结构：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <app-name>
  namespace: <namespace>
  labels:
    app: <app-name>
    version: <version>
spec:
  replicas: 3
  selector:
    matchLabels:
      app: <app-name>
  template:
    metadata:
      labels:
        app: <app-name>
        version: <version>
    spec:
      containers:
        - name: <container-name>
          image: <image>:<tag>
          ports:
            - containerPort: <port>
              name: http
          resources:
            requests:
              memory: '256Mi'
              cpu: '250m'
            limits:
              memory: '512Mi'
              cpu: '500m'
          livenessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: http
            initialDelaySeconds: 5
            periodSeconds: 5
          env:
            - name: ENV_VAR
              value: 'value'
          envFrom:
            - configMapRef:
                name: <app-name>-config
            - secretRef:
                name: <app-name>-secret

应采用的最佳实践：

• 始终设置资源请求和限制
• 同时实现存活探针和就绪探针
• 使用明确指定的镜像标签（绝不使用 :latest）
• 为非 root 用户设置安全上下文
• 使用标签进行组织和选择
• 根据可用性需求设置适当的副本数

参考： 详细的 Deployment 选项请参见 references/deployment-spec.md

3. 创建 Service 清单

选择合适的 Service 类型：

ClusterIP（仅限内部访问）：

apiVersion: v1
kind: Service
metadata:
  name: <app-name>
  namespace: <namespace>
  labels:
    app: <app-name>
spec:
  type: ClusterIP
  selector:
    app: <app-name>
  ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP

LoadBalancer（外部访问）：

apiVersion: v1
kind: Service
metadata:
  name: <app-name>
  namespace: <namespace>
  labels:
    app: <app-name>
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: nlb
spec:
  type: LoadBalancer
  selector:
    app: <app-name>
  ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP

参考： 关于 Service 类型和网络的说明，请参见 references/service-spec.md

4. 创建 ConfigMap

用于应用配置：

apiVersion: v1
kind: ConfigMap
metadata:
  name: <app-name>-config
  namespace: <namespace>
data:
  APP_MODE: production
  LOG_LEVEL: info
  DATABASE_HOST: db.example.com
  # For config files
  app.properties: |
    server.port=8080
    server.host=0.0.0.0
    logging.level=INFO

最佳实践：

• ConfigMap 仅用于非敏感数据
• 将相关配置放在一起
• 为键使用有意义的名称
• 考虑为每个组件使用一个 ConfigMap
• 更改时对 ConfigMap 进行版本管理

参考： 示例请参见 assets/configmap-template.yaml

5. 创建 Secret

用于敏感数据：

apiVersion: v1
kind: Secret
metadata:
  name: <app-name>-secret
  namespace: <namespace>
type: Opaque
stringData:
  DATABASE_PASSWORD: 'changeme'
  API_KEY: 'secret-api-key'
  # For certificate files
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----

安全注意事项：

• 切勿以明文形式将密钥提交到 Git
• 使用 Sealed Secrets、External Secrets Operator 或 Vault
• 定期轮换密钥
• 使用 RBAC 限制对密钥的访问
• TLS 密钥可考虑使用 Secret 类型：kubernetes.io/tls

6. 创建 PersistentVolumeClaim（如有需要）

用于有状态应用：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <app-name>-data
  namespace: <namespace>
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp3
  resources:
    requests:
      storage: 10Gi

在 Deployment 中挂载：

spec:
  template:
    spec:
      containers:
        - name: app
          volumeMounts:
            - name: data
              mountPath: /var/lib/app
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: <app-name>-data

存储注意事项：

• 根据性能需求选择合适的 StorageClass
• 单 Pod 访问时使用 ReadWriteOnce
• 多 Pod 共享存储时使用 ReadWriteMany
• 考虑备份策略
• 设置适当的保留策略

7. 应用安全最佳实践

向 Deployment 添加安全上下文：

spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: app
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL

安全检查清单：

• 以非 root 用户运行
• 删除所有功能
• 使用只读根文件系统
• 禁用权限提升
• 设置 seccomp 配置文件
• 使用 Pod 安全标准

8. 添加标签和注释

标准标签（推荐）：

metadata:
  labels:
    app.kubernetes.io/name: <app-name>
    app.kubernetes.io/instance: <instance-name>
    app.kubernetes.io/version: '1.0.0'
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: <system-name>
    app.kubernetes.io/managed-by: kubectl

实用注释：

metadata:
  annotations:
    description: 'Application description'
    contact: '[email protected]'
    prometheus.io/scrape: 'true'
    prometheus.io/port: '9090'
    prometheus.io/path: '/metrics'

9. 组织多资源清单

文件组织方式：

选项 1：使用 --- 分隔符的单个文件

# app-name.yaml
---
apiVersion: v1
kind: ConfigMap
...
---
apiVersion: v1
kind: Secret
...
---
apiVersion: apps/v1
kind: Deployment
...
---
apiVersion: v1
kind: Service
...

选项 2：分开的文件

manifests/
├── configmap.yaml
├── secret.yaml
├── deployment.yaml
├── service.yaml
└── pvc.yaml

选项 3：Kustomize 结构

base/
├── kustomization.yaml
├── deployment.yaml
├── service.yaml
└── configmap.yaml
overlays/
├── dev/
│   └── kustomization.yaml
└── prod/
    └── kustomization.yaml

10. 验证和测试

验证步骤：

# Dry-run validation
kubectl apply -f manifest.yaml --dry-run=client

# Server-side validation
kubectl apply -f manifest.yaml --dry-run=server

# Validate with kubeval
kubeval manifest.yaml

# Validate with kube-score
kube-score score manifest.yaml

# Check with kube-linter
kube-linter lint manifest.yaml

测试清单：

• 清单通过试运行验证
• 已填写所有必需字段
• 资源限制设置合理
• 已配置健康检查
• 已设置安全上下文
• 标签符合约定
• 命名空间已存在或已创建

常见模式

模式 1：简单的无状态 Web 应用

适用场景： 标准 Web API 或微服务

所需组件：

• Deployment（3 个副本以实现高可用）
• ClusterIP Service
• 用于配置的 ConfigMap
• 用于 API 密钥的 Secret
• HorizontalPodAutoscaler（可选）

参考： 请参阅 assets/deployment-template.yaml

模式 2：有状态数据库应用

适用场景： 数据库或持久化存储应用

所需组件：

• StatefulSet（而非 Deployment）
• Headless Service
• PersistentVolumeClaim 模板
• 用于数据库配置的 ConfigMap
• 用于凭据的 Secret

模式 3：后台任务或定时任务

适用场景： 定时任务或批处理

所需组件：

• CronJob 或 Job
• 用于任务参数的 ConfigMap
• 用于凭据的 Secret
• 配置了 RBAC 的 ServiceAccount

模式 4：多容器 Pod

适用场景： 包含 Sidecar 容器的应用

所需组件：

• 包含多个容器的 Deployment
• 容器间共享的卷
• 用于初始化的 Init 容器
• Service（如有需要）

模板

assets/ 目录中提供了以下模板：

• deployment-template.yaml - 遵循最佳实践的标准 Deployment
• service-template.yaml - Service 配置（ClusterIP、LoadBalancer、NodePort）
• configmap-template.yaml - 不同数据类型的 ConfigMap 示例
• secret-template.yaml - Secret 示例（应生成，不应提交）
• pvc-template.yaml - PersistentVolumeClaim 模板

参考文档

• references/deployment-spec.md - Deployment 详细规范
• references/service-spec.md - Service 类型和网络详情

最佳实践摘要

1. 始终设置资源请求和限制 - 防止资源耗尽
2. 实施健康检查 - 确保 Kubernetes 能够管理应用
3. 使用明确的镜像标签 - 避免不可预测的部署
4. 应用安全上下文 - 以非 root 用户运行，并删除权限
5. 使用 ConfigMap 和 Secret - 将配置与代码分离
6. 为所有内容添加标签 - 便于筛选和整理
7. 遵循命名约定 - 使用标准 Kubernetes 标签
8. 应用前进行验证 - 使用试运行和验证工具
9. 为清单进行版本管理 - 将清单存储在 Git 中并进行版本控制
10. 使用注释编写文档 - 为其他开发者补充背景信息

故障排除

Pod 无法启动：

• 检查镜像拉取错误：kubectl describe pod <pod-name>
• 确认资源是否可用：kubectl get nodes
• 检查事件：kubectl get events --sort-by='.lastTimestamp'

Service 无法访问：

• 确认选择器与 Pod 标签匹配：kubectl get endpoints <service-name>
• 检查 Service 类型和端口配置
• 在集群内测试：kubectl run debug --rm -it --image=busybox -- sh

ConfigMap/Secret 未加载：

• 确认 Deployment 中的名称匹配
• 检查命名空间
• 确保资源存在：kubectl get configmap,secret

后续步骤

创建清单后：

1. 存储在 Git 仓库中
2. 设置用于部署的 CI/CD 流水线
3. 考虑使用 Helm 或 Kustomize 进行模板化
4. 使用 ArgoCD 或 Flux 实施 GitOps
5. 添加监控和可观测性

铁律

1. 始终为每个容器设置 CPU 和内存资源 requests 和 limits——未设置资源限制的 Pod 会无限消耗节点资源，导致节点压力驱逐，并挤占相邻工作负载的资源。
2. 绝不要在生产环境中以 root 身份运行容器（runAsNonRoot: false 或未设置）——root 容器可能利用内核漏洞逃逸容器隔离；务必设置 securityContext.runAsNonRoot: true，并指定具体的 runAsUser。
3. 始终为每个工作负载定义存活探针和就绪探针——没有探针，Kubernetes 无法区分死锁容器和健康容器；探针失败会错误地阻止部署和流量。
4. 绝不要将密钥存储在 ConfigMap 中——ConfigMap 以明文形式存储在 etcd 中；请使用 Kubernetes Secret（并启用 etcd 静态加密）或外部密钥管理器（Vault、AWS Secrets Manager）。
5. 始终为生产工作负载设置 PodDisruptionBudget——没有 PDB，升级期间的节点清空可能同时终止所有副本，导致服务完全中断。

反模式

反模式	失败原因	正确做法
未设置资源限制	Pod 会耗尽节点内存；节点 OOM 会终止其他 Pod；集群不稳定	为每个容器设置 CPU 和内存的 requests（调度）与 limits（强制限制）
以 root 身份运行	内核漏洞可能导致容器逃逸；以 root 身份写入文件系统会损坏主机	设置 runAsNonRoot: true、runAsUser: 1000、readOnlyRootFilesystem: true
缺少存活探针/就绪探针	死锁的 Pod 仍会处理流量；新 Pod 尚未就绪就会接收流量	添加 /health 存活探针和 /ready 就绪探针，并设置适当的 initialDelaySeconds
将密钥存储在 ConfigMap 中	在 etcd 中以明文存储；通过 kubectl get configmap 可见；审计日志会暴露其值	使用带 Base64 编码的 kind: Secret；启用 etcd 加密；优先使用外部密钥管理器
生产环境仅运行一个副本	Pod 重启会导致服务中断；无法容忍节点故障	至少运行 2 个副本 + PodAntiAffinity 规则以分散到不同节点；设置 PodDisruptionBudget

相关技能

• helm-chart-scaffolding - 用于模板化和打包
• gitops-workflow - 用于自动化部署
• k8s-security-policies - 用于高级安全配置

记忆协议（强制）

开始前：

cat C:\dev\projects\agent-studio\.claude\context\memory\learnings.md

完成后：

• 新模式 -> C:\dev\projects\agent-studio\.claude\context\memory\learnings.md
• 发现问题 -> C:\dev\projects\agent-studio\.claude\context\memory\issues.md
• 做出决策 -> C:\dev\projects\agent-studio\.claude\context\memory\decisions.md

假定可能会被中断：如果没有记录在记忆中，就等于没有发生。