name: k8s-manifest-generator description: 创建生产就绪的Kubernetes清单，用于Deployments、Services、ConfigMaps和Secrets，遵循最佳实践和安全标准。在生成Kubernetes YAML清单、创建K8s资源或实现生产级Kubernetes配置时使用。 version: 1.0.0 model: sonnet invoked_by: [devops] tools: [Read, Write, Edit, Bash, Glob, Grep] verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

Kubernetes清单生成器

逐步指导创建生产就绪的Kubernetes清单，包括Deployments、Services、ConfigMaps、Secrets和PersistentVolumeClaims。

目的

本技能提供生成结构良好、安全且生产就绪的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以获取详细部署选项

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以获取服务类型和网络详情

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
  # 用于配置文件
  app.properties: |
    server.port=8080
    server.host=0.0.0.0
    logging.level=INFO

最佳实践：

仅对非敏感数据使用ConfigMaps
组织相关配置在一起
使用有意义的键名
考虑每个组件使用一个ConfigMap
更改时版本化ConfigMaps

参考： 查看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'
  # 用于证书文件
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----

安全考虑：

绝不要将明文密钥提交到Git
使用Sealed Secrets、External Secrets Operator或Vault
定期轮换密钥
使用RBAC限制密钥访问
考虑使用Secret类型：kubernetes.io/tls用于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
使用ReadWriteOnce用于单Pod访问
使用ReadWriteMany用于多Pod共享存储
考虑备份策略
设置适当的保留策略

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: '应用描述'
    contact: 'team@example.com'
    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. 验证和测试

验证步骤：

# 客户端干运行验证
kubectl apply -f manifest.yaml --dry-run=client

# 服务端干运行验证
kubectl apply -f manifest.yaml --dry-run=server

# 使用kubeval验证
kubeval manifest.yaml

# 使用kube-score验证
kube-score score manifest.yaml

# 使用kube-linter检查
kube-linter lint manifest.yaml

测试检查清单：

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

常见模式

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

用例： 标准Web API或微服务

所需组件：

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

参考： 查看assets/deployment-template.yaml

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

用例： 数据库或持久存储应用

所需组件：

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

模式3：后台任务或Cron

用例： 计划任务或批处理

所需组件：

CronJob或Job
ConfigMap用于任务参数
Secret用于凭证
ServiceAccount带RBAC

模式4：多容器Pod

用例： 带边车容器的应用

所需组件：

带多个容器的Deployment
容器间共享卷
Init容器用于设置
Service（如果需要）

模板

以下模板可在assets/目录中找到：

deployment-template.yaml - 带最佳实践的标准部署
service-template.yaml - 服务配置（ClusterIP、LoadBalancer、NodePort）
configmap-template.yaml - ConfigMap示例带不同数据类型
secret-template.yaml - 密钥示例（待生成，不提交）
pvc-template.yaml - PersistentVolumeClaim模板

参考文档

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

最佳实践总结

始终设置资源请求和限制 - 防止资源饥饿
实现健康检查 - 确保Kubernetes能管理您的应用
使用特定镜像标签 - 避免不可预测的部署
应用安全上下文 - 以非root运行，丢弃权限
使用ConfigMaps和Secrets - 将配置与代码分离
为所有内容添加标签 - 启用筛选和组织
遵循命名约定 - 使用标准Kubernetes标签
在应用前验证 - 使用干运行和验证工具
版本化您的清单 - 在Git中使用版本控制
使用注解记录 - 为其他开发者添加上下文

故障排除

Pod未启动：

检查镜像拉取错误：kubectl describe pod <pod-name>
验证资源可用性：kubectl get nodes
检查事件：kubectl get events --sort-by='.lastTimestamp'

服务不可访问：

验证选择器匹配Pod标签：kubectl get endpoints <service-name>
检查服务类型和端口配置
从集群内测试：kubectl run debug --rm -it --image=busybox -- sh

ConfigMap/Secret未加载：

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

后续步骤

创建清单后：

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

内存协议（强制）

开始前：

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

假设中断：如果不在内存中，则未发生。

Kubernetes清单生成器Skill k8s-manifest-generator