YAML 与声明式配置

DevOps

Kubernetes

YAML 与声明式配置

Kubernetes 对象 YAML 配置规范：基本语法、资源对象结构、Label 与 Selector 用法。

1. YAML 语法基础

语法	说明
缩进	表示上下级关系，不允许 Tab，通常缩进 2 个空格
`:`	键值对，冒号后必须有空格
`-`	列表项，连字符后必须有空格
`[]`	内联数组
`{}`	内联对象
`#`	注释
`\|`	多行文本块（保留换行）
`>`	多行文本块（折叠换行）
`---`	文档分隔符，用于在单文件中定义多个资源

2. K8s 资源对象结构

每个 K8s 对象的 YAML 文件必须包含以下四个字段：

apiVersion: <API 版本>
kind: <资源类型>
metadata:
  name: <名称>
  namespace: <命名空间>   # 可选，默认 default
  labels:                 # 可选
    key: value
spec:
  # 期望状态的规约

字段	说明	是否必填
`apiVersion`	K8s API 的版本（如 `v1`、`apps/v1`）	✅
`kind`	资源类型（Pod、Deployment、Service 等）	✅
`metadata`	描述对象的元数据（name、namespace、labels 等）	✅
`spec`	期望状态的详细定义	✅

2.1 常用 apiVersion 对照

Kind	apiVersion
Pod, Service, ConfigMap, Secret	`v1`
Deployment, ReplicaSet, StatefulSet, DaemonSet	`apps/v1`
Ingress	`networking.k8s.io/v1`
HPA	`autoscaling/v2`
PVC, PV	`v1`
StorageClass	`storage.k8s.io/v1`

3. 基础示例

3.1 Pod

# my-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  containers:
    - name: nginx
      image: nginx:1.22
      ports:
        - containerPort: 80

3.2 Deployment

# my-deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deploy
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.22
          ports:
            - containerPort: 80

🚨 注意：spec.selector.matchLabels 必须与 spec.template.metadata.labels 匹配，否则 Deployment 创建会失败。

3.3 Service

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  type: ClusterIP
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80

3.4 多资源单文件

使用 --- 分隔多个资源定义：

apiVersion: v1
kind: Namespace
metadata:
  name: dev
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: dev
spec:
  # ...
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-svc
  namespace: dev
spec:
  # ...

4. Labels（标签）

Label 是附加到对象上的键值对，用于标识和选择对象。

4.1 格式约束

约束	前缀部分	名称部分
最大长度	253 字符	63 字符
允许字符	DNS 子域	字母数字 + `-` `_` `.`
起始/结束	字母数字	字母数字

4.2 使用示例

metadata:
  labels:
    app: nginx              # 应用名
    environment: production # 环境
    version: "1.22"         # 版本
    tier: frontend          # 层级

4.3 常用 Label 约定（💡 最佳实践）

标签	示例值	说明
`app.kubernetes.io/name`	`mysql`	应用名称
`app.kubernetes.io/instance`	`mysql-abcxzy`	实例唯一标识
`app.kubernetes.io/version`	`5.7.21`	应用版本
`app.kubernetes.io/component`	`database`	组件类型
`app.kubernetes.io/part-of`	`wordpress`	所属应用
`app.kubernetes.io/managed-by`	`helm`	管理工具

4.4 查看标签

# 显示所有 Pod 的标签
kubectl get pod --show-labels

# 按标签过滤
kubectl get pod -l "app=nginx,environment=production"
# 逗号表示 AND 关系

# 按标签表达式过滤
kubectl get pod -l "environment in (production,staging)"
kubectl get pod -l "environment notin (dev,test)"

5. Selector（选择器）

Label Selector 用于选择一组对象。最常用于 Service 选择后端 Pod。

5.1 两种选择方式

基于等值（Equality-based）

selector:
  matchLabels:
    component: redis
    version: "7.0"
# 等价于：component=redis AND version=7.0

基于集合（Set-based）

selector:
  matchExpressions:
    - {key: tier, operator: In, values: [cache, backend]}
    - {key: environment, operator: NotIn, values: [dev, prod]}
# 等价于：tier in (cache, backend) AND environment not in (dev, prod)

操作符	说明
`In`	值在给定列表中
`NotIn`	值不在给定列表中
`Exists`	标签存在（不需要 values）
`DoesNotExist`	标签不存在（不需要 values）

5.2 多条件组合

多个选择条件用逗号分隔，等价于 AND 运算。K8s 不支持 OR 运算。

5.3 Service 与 Selector

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  type: NodePort
  selector:
    app: nginx             # 选择 app=nginx 的所有 Pod
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30007

Service 通过 selector 自动发现后端 Pod，并将其 IP 写入 Endpoints 对象。可以通过 kubectl get endpoints 验证绑定是否正确。

# 查看 Service 的 Endpoints
kubectl get ep my-service

# 核对 Endpoints 中的 IP 与 Pod IP 是否一致
kubectl get pod -l "app=nginx" -owide

Kubectl 命令行操作容器运行时与镜像管理