K8s YAML 编写指南：Deployment 与 Service

一、核心概念

K8s 中部署一个应用，通常需要两个 YAML 文件：

文件	作用	类比
Deployment	定义”跑什么”（镜像、副本数、容器配置）	决定开几家店
Service	定义”怎么访问”（端口映射、网络暴露）	决定怎么找到店

1
用户请求 → Service (端口映射) → Pod (容器运行应用)

二、Deployment 编写详解

2.1 完整模板

1
apiVersion: apps/v1          # API 版本（Deployment 固定写 apps/v1）
2
kind: Deployment             # 资源类型
3
metadata:                    # 元数据（名称、标签等）
4
  name: java-chains          # Deployment 名称（全局唯一）
5
  labels:                    # Deployment 级别的标签
6
    app: java-chains
7
spec:                        # 规格说明
8
  replicas: 1                # 运行几个 Pod 副本
9
  selector:                   # 选择器（匹配哪些 Pod 属于这个 Deployment）
10
    matchLabels:
11
      app: java-chains       # 必须与 template.metadata.labels 一致
12
  template:                   # Pod 模板（定义 Pod 的内容）
13
    metadata:
14
      labels:
15
        app: java-chains     # Pod 的标签（selector 通过这个匹配）
16
    spec:                    # Pod 的规格
17
      containers:
18
        - name: java-chains  # 容器名称
19
          image: java-chains-1.4.1:latest  # 镜像名称:标签
20
          imagePullPolicy: IfNotPresent    # 镜像拉取策略
21
          ports:
22
            - containerPort: 8011         # 容器监听的端口

2.2 各字段详解

metadata（元数据）

1
metadata:
2
  name: java-chains    # 名称，kubectl get/deploy/logs 时用这个名字
3
  labels:              # 键值对标签，用于 Service 选择和分类
4
    app: java-chains   # 自定义标签名，通常用 app=<应用名>
5
  namespace: default   # 可选，指定命名空间，默认 default

spec（规格）

1
spec:
2
  replicas: 1          # Pod 副本数量，高可用设为 3
3
  selector:             # Pod 选择器，必须与 template.labels 匹配
4
    matchLabels:
5
      app: java-chains

template（Pod 模板）

1
  template:
2
    metadata:
3
      labels:
4
        app: java-chains     # ⚠️ 必须与 selector.matchLabels 一致
5
    spec:
6
      containers:
7
        - name: java-chains
8
          image: java-chains-1.4.1:latest
9
          imagePullPolicy: IfNotPresent
10
          ports:
11
            - containerPort: 8011

2.3 imagePullPolicy 镜像拉取策略

策略	含义	适用场景
`IfNotPresent`	本地有就用本地的，没有才拉取	本地开发的镜像
`Always`	每次创建 Pod 都拉取最新镜像	使用 `latest` 标签时
`Never`	从不拉取，只用本地镜像	离线环境

2.4 多容器示例

一个 Pod 可以运行多个容器（通常一个主容器 + 多个边车容器）：

1
spec:
2
  containers:
3
    - name: java-chains
4
      image: java-chains-1.4.1:latest
5
      ports:
6
        - containerPort: 8011
7
    - name: log-collector    # 边车容器：收集日志
8
      image: log-collector:latest
9
      volumeMounts:
10
        - name: logs
11
          mountPath: /app/logs
12
  volumes:
13
    - name: logs
14
      emptyDir: {}

三、Service 编写详解

3.1 Service 类型对比

类型	外部可访问	适用场景
`ClusterIP`	❌ 仅集群内部	微服务间通信、内部 API
`NodePort`	✅ 通过 `节点IP:端口`	开发测试、简单对外暴露
`LoadBalancer`	✅ 通过云厂商负载均衡	生产环境（需要云支持）

3.2 ClusterIP（默认，仅内部访问）

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: java-chains
5
spec:
6
  type: ClusterIP             # 默认值，可省略
7
  selector:
8
    app: java-chains           # 通过标签选择 Pod
9
  ports:
10
    - port: 8011               # Service 对外暴露的端口
11
      targetPort: 8011         # 转发到 Pod 的 containerPort

访问方式：集群内其他 Pod 通过 java-chains.default.svc.cluster.local:8011 访问。

3.3 NodePort（对外暴露端口）

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: java-chains
5
spec:
6
  type: NodePort
7
  selector:
8
    app: java-chains
9
  ports:
10
    - port: 8011               # 集群内部访问端口
11
      targetPort: 8011         # Pod 容器端口
12
      nodePort: 30011          # 外部访问端口（范围 30000-32767）

访问方式：浏览器通过 http://localhost:30011 访问。

3.4 多端口 Service

一个 Service 可以暴露多个端口：

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: java-chains
5
spec:
6
  type: NodePort
7
  selector:
8
    app: java-chains
9
  ports:
10
    - name: http               # 端口名称（必须）
11
      port: 8011
12
      targetPort: 8011
13
      nodePort: 30011
14
    - name: metrics            # 第二个端口
15
      port: 9090
16
      targetPort: 9090
17
      nodePort: 30090

⚠️ 多端口时，每个端口必须有 name 字段。

3.5 多个 Service 合并写法

多个 Service 可以写在同一个 YAML 文件中，用 --- 分隔：

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: java-chains
5
spec:
6
  type: NodePort
7
  selector:
8
    app: java-chains
9
  ports:
10
    - port: 8011
11
      targetPort: 8011
12
      nodePort: 30011
13
---
14
apiVersion: v1
15
kind: Service
16
metadata:
17
  name: java-sec-code
18
spec:
19
  type: ClusterIP
20
  selector:
21
    app: java-sec-code
22
  ports:
23
    - port: 8080
24
      targetPort: 8080

四、端口映射详解

4.1 三层端口关系

1
外部请求 → nodePort → port → targetPort → containerPort → 应用
2
(浏览器)   (宿主机)   (Service)  (转发规则)   (容器内)    (监听)

字段	在哪定义	谁在使用	是否必须
`containerPort`	Deployment	容器内的应用	建议填写（文档作用）
`targetPort`	Service	Service 转发目标	✅ 必须
`port`	Service	集群内其他 Pod	✅ 必须
`nodePort`	Service	外部浏览器	仅 NodePort 类型

4.2 port 和 targetPort 可以不同

1
ports:
2
  - port: 80           # 集群内访问 :80
3
    targetPort: 8011   # 实际转发到容器的 8011
4
    nodePort: 30080    # 外部访问 :30080

这样：

集群内：curl java-chains:80 → 转发到容器 8011
集群外：curl localhost:30080 → 转发到容器 8011

4.3 nodePort 端口范围

默认范围是 30000-32767，超出范围会报错。

如果需要使用范围外的端口（如 18011），有两种方式：

方式一：修改 kube-apiserver 参数（不推荐）

Docker Desktop 可以在设置中修改，但不建议。

方式二：使用 port-forward（推荐，临时方案）

1
# 将本地 18011 映射到 Service 的 8011
2
kubectl port-forward svc/java-chains 18011:8011
3

4
# 然后浏览器访问 http://localhost:18011

方式三：使用 docker run 的 -p 参数（Docker Desktop 特有）

1
# 不需要改 YAML，直接映射
2
kubectl port-forward svc/java-chains 18011:8011 --address 0.0.0.0

五、完整操作流程

5.1 从零部署一个应用

1
# ===== 第一步：构建镜像 =====
2
cd demo/java-chains-1.4.1/
3
docker build -t java-chains-1.4.1:latest .
4

5
# ===== 第二步：加载镜像到 K8s =====
6
# Docker Desktop 内置 K8s 可以直接使用 docker build 的镜像
7
# Minikube 需要额外加载：
8
# minikube image load java-chains-1.4.1:latest
9

10
# ===== 第三步：部署 Deployment =====
11
kubectl apply -f java-chains-deploy.yaml
12

13
# ===== 第四步：创建 Service =====
14
kubectl apply -f services.yaml
15

16
# ===== 第五步：验证 =====
17
kubectl get pods -l app=java-chains
18
kubectl get svc java-chains
19

20
# ===== 第六步：访问 =====
21
# ClusterIP 类型（仅内部）
22
kubectl port-forward svc/java-chains 8011:8011
23
# 浏览器访问 http://localhost:8011
24

25
# NodePort 类型（直接访问）
26
# 浏览器访问 http://localhost:30011

5.2 修改端口映射

1
# 1. 编辑 services.yaml，修改 port/targetPort/nodePort
2
vi services.yaml
3

4
# 2. 重新 apply（K8s 会自动更新）
5
kubectl apply -f services.yaml
6

7
# 3. 验证
8
kubectl get svc java-chains

5.3 修改镜像版本

1
# 1. 修改 deploy.yaml 中的 image 字段
2
#    image: java-chains-1.4.1:latest
3
#    改为
4
#    image: java-chains-1.4.2:latest
5

6
# 2. 重新 apply
7
kubectl apply -f java-chains-deploy.yaml
8

9
# 3. 查看 Pod 是否重建（新镜像会触发滚动更新）
10
kubectl get pods -l app=java-chains -w

5.4 扩缩容

1
# 方式一：修改 deploy.yaml 中 replicas 字段后 apply
2

3
# 方式二：命令行直接扩缩
4
kubectl scale deployment java-chains --replicas=3
5

6
# 查看副本数
7
kubectl get pods -l app=java-chains

5.5 删除资源

1
# 删除 Service
2
kubectl delete -f services.yaml
3

4
# 删除 Deployment
5
kubectl delete -f java-chains-deploy.yaml
6

7
# 或按名称删除
8
kubectl delete svc java-chains
9
kubectl delete deployment java-chains

六、常用排查命令

1
# 查看 Pod 状态
2
kubectl get pods -l app=java-chains
3

4
# 查看 Pod 详情（包括事件）
5
kubectl describe pod <pod-name>
6

7
# 查看 Pod 日志
8
kubectl logs <pod-name>
9
kubectl logs <pod-name> -f          # 实时日志
10
kubectl logs <pod-name> --tail 50   # 最后50行
11

12
# 查看 Service 详情
13
kubectl describe svc java-chains
14

15
# 查看 Service 端点（Pod 是否被正确关联）
16
kubectl get endpoints java-chains
17

18
# 进入容器
19
kubectl exec -it <pod-name> -- sh
20

21
# 端口转发（临时暴露）
22
kubectl port-forward svc/java-chains 8011:8011
23

24
# 查看 Pod 所在节点
25
kubectl get pods -l app=java-chains -o wide

七、常见问题

Q1: Service 创建了但 Endpoints 为空？

1
kubectl get endpoints java-chains
2
# 如果显示 <none>，说明 selector 没有匹配到任何 Pod

原因：Service 的 selector.app 与 Pod 的 labels.app 不一致。

排查：

1
kubectl get pods --show-labels | grep java-chains

Q2: 修改了 YAML 但没有生效？

1
# 检查是否有语法错误（dry-run 不实际执行）
2
kubectl apply -f services.yaml --dry-run=client
3

4
# 查看当前实际生效的配置
5
kubectl get svc java-chains -o yaml

Q3: NodePort 端口冲突？

1
The Service "java-chains" is invalid: spec.ports[0].nodePort: Invalid value: 30011: provided port is already allocated

说明 30011 已被其他 Service 占用。换一个端口即可。

Q4: Pod 一直 CrashLoopBackOff？

1
kubectl logs <pod-name>           # 查看应用日志
2
kubectl describe pod <pod-name>   # 查看事件（可能有镜像拉取失败等信息）

常见原因：镜像不存在、应用启动报错、端口被占用。

Q5: 如何查看当前集群所有端口映射？

1
kubectl get svc --all-namespaces
2
# 或更详细
3
kubectl get svc -o wide --all-namespaces

dacj4n's