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 用户应用安全上下文
• 使用标签进行组织和选择
• 根据可用性需求设置适当的副本数

参考： 请参阅 references/deployment-spec.md，了解详细的 Deployment 选项

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

参考： 请参阅 references/service-spec.md，了解 Service 类型和网络配置

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 用户运行
• 移除所有 capabilities
• 使用只读根文件系统
• 禁用权限提升
• 设置 seccomp 配置文件
• 使用 Pod Security Standards

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

测试清单：

• 清单通过 dry-run 验证
• 已包含所有必填字段
• 资源限制设置合理
• 已配置健康检查
• 已设置安全上下文
• 标签符合规范
• 命名空间已存在或已创建

常见模式

模式 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：后台任务或 Cron

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

所需组件：

• 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 用户运行，并移除 capabilities
5. 使用 ConfigMap 和 Secret - 将配置与代码分离
6. 为所有内容添加标签 - 便于筛选和整理
7. 遵循命名规范 - 使用标准 Kubernetes 标签
8. 应用前先验证 - 使用 dry-run 和验证工具
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. 添加监控和可观测性

相关技能

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