容器与云原生 / 系统课时

部署多服务应用

部署多服务应用

本课把上一节的架构落地为可运行的 Kubernetes 资源:PostgreSQL 使用 StatefulSet 和持久卷,后端与前端使用 Deployment,Service 负责集群内发现,Ingress 提供统一入口。完成后可以验证页面、API 和数据库连通性。

学习目标

  • 编写并部署 Deployment、StatefulSet、Service、ConfigMap、Secret 和 Ingress。
  • 按依赖顺序检查滚动状态、服务发现和持久化资源。
  • 通过端到端请求定位入口、前端、后端或数据库链路中的问题。

前置检查

确认当前 kubectl 指向目标集群,并且集群存在默认 StorageClass。Ingress 仅在已安装 Ingress Controller 时生效;即使没有控制器,也可以通过端口转发完成核心链路验收。

bash
kubectl cluster-info
kubectl get storageclass

预期输出应包含 Kubernetes 控制面地址,并至少有一个 StorageClass 标记为默认。地址和名称因集群而异。

text
Kubernetes control plane is running at https://<CONTROL-PLANE>
NAME                 PROVISIONER               RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
<STORAGE-CLASS>      <PROVISIONER>             Delete          <MODE>              true                   <AGE>

如果没有默认 StorageClass,后面的 PostgreSQL PVC 会保持 Pending。此时应为 volumeClaimTemplates 明确填写可用的 storageClassName,或先安装存储提供器。

资源关系与部署顺序

多服务应用资源关系与部署顺序

部署顺序遵循依赖关系:先创建命名空间、配置和凭据,再等待数据库 Ready,然后启动后端、前端,最后创建 Ingress。Kubernetes 可以一次应用整份清单,但验收仍应按这个顺序观察,否则上游组件未就绪时会把暂时性错误误判为配置错误。

本例后端使用 Python 标准库实现最小 API,并检测 PostgreSQL 端口是否可达;前端使用 Nginx 提供页面并把 /api/ 代理到后端。这样无需额外构建镜像,也能验证完整服务链路。

编写完整资源清单

将以下内容保存为 shop-stack.yaml。示例中的数据库密码只用于本地练习,生产环境必须改用外部密钥系统或受控的 Secret 发布流程。

yaml
apiVersion: v1
kind: Namespace
metadata:
  name: shop
---
apiVersion: v1
kind: Secret
metadata:
  name: database-secret
  namespace: shop
type: Opaque
stringData:
  POSTGRES_DB: shop
  POSTGRES_USER: shop
  POSTGRES_PASSWORD: change-me-now
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-config
  namespace: shop
data:
  app.py: |
    import json
    import os
    import socket
    from http.server import BaseHTTPRequestHandler, HTTPServer

    DB_HOST = os.getenv("DATABASE_HOST", "postgres")
    DB_PORT = int(os.getenv("DATABASE_PORT", "5432"))

    def database_status():
        try:
            with socket.create_connection((DB_HOST, DB_PORT), timeout=1):
                return "reachable"
        except OSError:
            return "unreachable"

    class Handler(BaseHTTPRequestHandler):
        def do_GET(self):
            if self.path == "/healthz":
                status, payload = 200, {"status": "ok"}
            elif self.path.startswith("/api"):
                status = 200
                payload = {
                    "service": "backend",
                    "database": database_status(),
                }
            else:
                status, payload = 404, {"error": "not found"}

            body = json.dumps(payload).encode("utf-8")
            self.send_response(status)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(body)))
            self.end_headers()
            self.wfile.write(body)

        def log_message(self, format, *args):
            return

    if __name__ == "__main__":
        HTTPServer(("0.0.0.0", 8080), Handler).serve_forever()
  nginx.conf: |
    events {}
    http {
      server {
        listen 80;

        location = /healthz {
          return 200 'ok';
        }

        location /api/ {
          proxy_pass http://backend:8080;
        }

        location / {
          default_type text/html;
          return 200 '<!doctype html><html><body><h1>Shop Frontend</h1><p>Try /api/</p></body></html>';
        }
      }
    }
---
# 数据库:无头 Service 提供稳定 DNS,StatefulSet 绑定持久卷
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: shop
spec:
  clusterIP: None
  selector:
    app: postgres
  ports:
    - name: postgres
      port: 5432
      targetPort: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: shop
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:16-alpine
          envFrom:
            - secretRef:
                name: database-secret
          ports:
            - containerPort: 5432
              name: postgres
          readinessProbe:
            exec:
              command:
                - sh
                - -c
                - pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"
            initialDelaySeconds: 5
            periodSeconds: 5
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 1Gi
---
# 后端:挂载 Python 程序,通过 Service 名访问数据库
apiVersion: v1
kind: Service
metadata:
  name: backend
  namespace: shop
spec:
  selector:
    app: backend
  ports:
    - name: http
      port: 8080
      targetPort: 8080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  namespace: shop
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
        - name: backend
          image: python:3.12-alpine
          command:
            - python
            - /app/app.py
          env:
            - name: DATABASE_HOST
              value: postgres
            - name: DATABASE_PORT
              value: "5432"
          ports:
            - containerPort: 8080
              name: http
          readinessProbe:
            httpGet:
              path: /healthz
              port: http
            initialDelaySeconds: 2
            periodSeconds: 5
          resources:
            requests:
              cpu: 50m
              memory: 32Mi
            limits:
              cpu: 200m
              memory: 128Mi
          volumeMounts:
            - name: app
              mountPath: /app
              readOnly: true
      volumes:
        - name: app
          configMap:
            name: shop-config
            items:
              - key: app.py
                path: app.py
---
# 前端:Nginx 提供页面,并把 /api/ 转发给 backend Service
apiVersion: v1
kind: Service
metadata:
  name: frontend
  namespace: shop
spec:
  selector:
    app: frontend
  ports:
    - name: http
      port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: shop
spec:
  replicas: 2
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - name: frontend
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80
              name: http
          readinessProbe:
            httpGet:
              path: /healthz
              port: http
            initialDelaySeconds: 2
            periodSeconds: 5
          resources:
            requests:
              cpu: 20m
              memory: 16Mi
            limits:
              cpu: 100m
              memory: 64Mi
          volumeMounts:
            - name: nginx-config
              mountPath: /etc/nginx/nginx.conf
              subPath: nginx.conf
              readOnly: true
      volumes:
        - name: nginx-config
          configMap:
            name: shop-config
            items:
              - key: nginx.conf
                path: nginx.conf
---
# 入口:使用 nginx IngressClass;其他控制器需调整 ingressClassName
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: nginx
  rules:
    - host: shop.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend
                port:
                  number: 80

这份清单生效后,数据库数据写入 PVC;后端通过 postgres.shop.svc 的集群 DNS 访问数据库;前端通过 backend Service 转发 API;Ingress 把 shop.local 的请求送到前端 Service。

部署并检查滚动状态

应用清单后,按数据库、后端、前端的顺序等待就绪。

bash
kubectl apply -f shop-stack.yaml
kubectl -n shop rollout status statefulset/postgres
kubectl -n shop rollout status deployment/backend
kubectl -n shop rollout status deployment/frontend
kubectl -n shop get pods,svc,pvc,ingress

预期结果中,三个工作负载最终完成滚动,Pod 为 Running 且 Ready,PVC 为 Bound。<REVISION>、Pod 名称、ClusterIP、年龄等实际值会不同。

text
namespace/shop created
secret/database-secret created
configmap/shop-config created
service/postgres created
statefulset.apps/postgres created
service/backend created
deployment.apps/backend created
service/frontend created
deployment.apps/frontend created
ingress.networking.k8s.io/shop created
statefulset rolling update complete 1 pods at revision <REVISION>
deployment "backend" successfully rolled out
deployment "frontend" successfully rolled out
NAME                            READY   STATUS    RESTARTS   AGE
pod/backend-<ID>                1/1     Running   0          <AGE>
pod/frontend-<ID>               1/1     Running   0          <AGE>
pod/postgres-0                  1/1     Running   0          <AGE>
NAME                               STATUS   VOLUME        CAPACITY   ACCESS MODES   STORAGECLASS       AGE
persistentvolumeclaim/data-postgres-0   Bound    pvc-<ID>     1Gi        RWO            <STORAGE-CLASS>   <AGE>

如果 PostgreSQL 首次拉取镜像或创建卷较慢,后端 API 可能暂时返回 unreachable。应先等待 postgres-0 Ready,再重新测试,不要立即修改 Service 或 DNS 配置。

验证端到端访问

为避免依赖本地 DNS 和 Ingress Controller,先通过前端 Service 做端口转发,再分别访问页面和 API。下面的脚本会在验证后结束端口转发进程。

bash
kubectl -n shop port-forward service/frontend 8080:80 >/tmp/shop-port-forward.log 2>&1 &
PF_PID=$!
sleep 2
curl -s http://127.0.0.1:8080/
printf '\n'
curl -s http://127.0.0.1:8080/api/
printf '\n'
kill "$PF_PID"

预期输出如下。若数据库仍在初始化,第二行的 database 可能短暂显示 unreachable,待数据库 Ready 后应变为 reachable。

text
<!doctype html><html><body><h1>Shop Frontend</h1><p>Try /api/</p></body></html>
{"service": "backend", "database": "reachable"}

已安装 Nginx Ingress Controller 时,可把入口地址与 shop.local 写入本机 hosts 文件,再访问 http://shop.local/。若使用其他 IngressClass,应同步修改清单中的 ingressClassName。

典型失败处理

现象 优先检查 常见根因与修复
PVC 长时间 Pending kubectl get storageclass 与 kubectl describe pvc 没有默认 StorageClass;填写有效的 storageClassName 或安装存储提供器
Pod 为 ImagePullBackOff kubectl describe pod 的 Events 节点无法访问镜像仓库、镜像名错误或需要拉取凭据
API 返回 database: unreachable PostgreSQL Ready 状态、Service Endpoint 与后端日志 数据库仍在初始化、端口错误或 Service 选择器不匹配
Ingress 返回 404 IngressClass、Host、控制器日志 控制器未安装、类别不匹配或请求未携带 shop.local Host
Service 无 Endpoint kubectl get endpointslices -n shop Service 选择器与 Pod 标签不一致,或 Pod 尚未 Ready

排查时按“资源是否存在、Pod 是否 Ready、Service 是否有 Endpoint、调用方是否能解析并连接目标端口”的顺序推进。这个顺序比直接重建全部资源更快,也能避免掩盖真实根因。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

部署多服务应用

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通