容器与云原生 / 系统课时
部署多服务应用
部署多服务应用
本课把上一节的架构落地为可运行的 Kubernetes 资源:PostgreSQL 使用 StatefulSet 和持久卷,后端与前端使用 Deployment,Service 负责集群内发现,Ingress 提供统一入口。完成后可以验证页面、API 和数据库连通性。
学习目标
- 编写并部署 Deployment、StatefulSet、Service、ConfigMap、Secret 和 Ingress。
- 按依赖顺序检查滚动状态、服务发现和持久化资源。
- 通过端到端请求定位入口、前端、后端或数据库链路中的问题。
前置检查
确认当前 kubectl 指向目标集群,并且集群存在默认 StorageClass。Ingress 仅在已安装 Ingress Controller 时生效;即使没有控制器,也可以通过端口转发完成核心链路验收。
kubectl cluster-info
kubectl get storageclass预期输出应包含 Kubernetes 控制面地址,并至少有一个 StorageClass 标记为默认。地址和名称因集群而异。
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 发布流程。
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。
部署并检查滚动状态
应用清单后,按数据库、后端、前端的顺序等待就绪。
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、年龄等实际值会不同。
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。下面的脚本会在验证后结束端口转发进程。
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。
<!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、调用方是否能解析并连接目标端口”的顺序推进。这个顺序比直接重建全部资源更快,也能避免掩盖真实根因。