Kubernetes YAML 配置文件编写教程
Kubernetes 使用 YAML（或 JSON）文件以声明式方式定义资源对象。本教程将带你了解常见 K8s 资源的 YAML 结构、每个字段的含义及实际示例。
一、YAML 文件通用结构
所有 K8s 资源 YAML 文件都包含以下四个核心字段：
yaml
apiVersion: <API组/版本> # 使用的 API 版本
kind: <资源类型> # 资源类型，如 Deployment、Service 等
metadata: # 元数据：名称、命名空间、标签等
spec: # 资源的具体配置（核心内容）✅ 注意 ：
status字段由 K8s 自动维护，不要手动写入 YAML。
二、常用资源类型详解
1. Pod（最小调度单元）
Pod 是 K8s 中最小的运行单元，通常不直接创建，而是由控制器（如 Deployment）管理。
字段说明
| 字段 | 说明 |
|---|---|
apiVersion |
v1（Pod 属于 core API 组） |
kind |
Pod |
metadata.name |
Pod 名称 |
spec.containers |
容器列表，每个容器需指定 name 和 image |
spec.containers.image |
镜像地址（如 nginx:1.25） |
spec.containers.ports |
容器暴露的端口（仅声明，不发布） |
示例
yaml
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
labels:
app: nginx
spec:
containers:
- name: nginx-container
image: nginx:1.25
ports:
- containerPort: 80💡 适用场景：调试、临时任务。生产环境建议使用 Deployment。
2. Deployment（管理无状态应用）
用于声明 Pod 的期望状态（副本数、更新策略等），自动创建和管理 ReplicaSet。
字段说明
| 字段 | 说明 |
|---|---|
apiVersion |
apps/v1 |
kind |
Deployment |
metadata.name |
Deployment 名称 |
spec.replicas |
期望的 Pod 副本数（默认 1） |
spec.selector.matchLabels |
选择器，匹配 Pod 的标签 |
spec.template |
Pod 模板（内容与 Pod 的 spec 相同） |
spec.template.metadata.labels |
必须 与 selector.matchLabels 一致 |
示例
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80✅
selector.matchLabels和template.metadata.labels必须匹配，否则创建失败！
3. Service（服务发现与负载均衡）
为一组 Pod 提供稳定的网络访问入口。
字段说明
| 字段 | 说明 |
|---|---|
apiVersion |
v1 |
kind |
Service |
spec.type |
类型：ClusterIP（默认）、NodePort、LoadBalancer |
spec.selector |
匹配后端 Pod 的标签 |
spec.ports |
端口映射：port（Service 端口）、targetPort（Pod 端口） |
示例（ClusterIP）
yaml
apiVersion: v1
kind: Service
metadata:
name: nginx-service
spec:
type: ClusterIP
selector:
app: nginx
ports:
- protocol: TCP
port: 80 # Service 监听端口
targetPort: 80 # 转发到 Pod 的端口示例（NodePort，外部可访问）
yaml
spec:
type: NodePort
ports:
- port: 80
targetPort: 80
nodePort: 30080 # 可选，范围 30000-327674. ConfigMap（非敏感配置）
存储配置数据，可挂载为文件或环境变量。
示例：从字面量创建
yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
LOG_LEVEL: "info"
config.yaml: |
port: 8080
debug: false在 Pod 中使用（作为环境变量）
yaml
env:
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: app-config
key: LOG_LEVEL5. Secret（敏感信息）
存储密码、token 等，Base64 编码（不是加密！ ）
示例（Opaque 类型）
yaml
apiVersion: v1
kind: Secret
metadata:
name: db-secret
type: Opaque
data:
username: YWRtaW4= # echo -n "admin" | base64
password: MWYyZDFlMmU2N2Rm🔐 实际使用中建议配合
kubectl create secret命令生成，避免明文写入文件。
6. PersistentVolumeClaim（PVC，存储申请）
用户对持久化存储的"请求"。
示例
yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi在 Pod 中挂载：
yaml
volumes:
- name: storage
persistentVolumeClaim:
claimName: my-pvc三、编写 YAML 的最佳实践
-
使用
kubectl explain查看字段说明kubectl explain deployment.spec.replicas -
验证 YAML 语法
inikubectl apply -f app.yaml --dry-run=client -
标签（labels）要一致
Deployment 的
selector.matchLabels必须与 Pod 模板的labels完全匹配。 -
不要手动管理 Pod
优先使用 Deployment、StatefulSet 等控制器。
-
敏感信息用 Secret，非敏感用 ConfigMap
四、完整示例：部署一个 Web 应用
yaml
---
# Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: web-app
spec:
replicas: 2
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:1.25
ports:
- containerPort: 80
---
# Service
apiVersion: v1
kind: Service
metadata:
name: web-service
spec:
type: NodePort
selector:
app: web
ports:
- port: 80
targetPort: 80
nodePort: 30080应用部署：
kubectl apply -f web-app.yaml访问：http://<NodeIP>:30080
五、附录：常用 apiVersion 对照表
| 资源类型 | apiVersion |
|---|---|
| Pod, Service, ConfigMap, Secret | v1 |
| Deployment, DaemonSet, ReplicaSet | apps/v1 |
| Ingress | networking.k8s.io/v1 |
| PersistentVolumeClaim | v1 |
| Job | batch/v1 |
| CronJob | batch/v1 |
📌 提示：YAML 对缩进和格式非常敏感！建议使用 VS Code + YAML 插件进行语法高亮和校验。
通过本教程，你应该能够理解 K8s YAML 的基本结构，并编写常见的资源定义。动手实践是掌握 K8s 的关键！