4. Kubernetes 环境准备：Minikube/K3s 集群搭建、kubectl 配置、命名空间规划

在契约测试落地 API 事务边界治理之前，必须建立一个可复现、轻量级、支持快速销毁与重建的 Kubernetes 验证环境。本章将指导你完成 Minikube 与 K3s 两种集群的搭建、kubectl 工具链的配置，以及面向契约测试场景的命名空间规划策略。

4.1 环境选型对比：Minikube vs K3s

两种方案均可在单机或虚拟机中运行完整的 Kubernetes 集群，但设计目标与适用场景存在显著差异。下表从验证契约测试的核心需求出发进行对比：

4.2 Minikube 集群搭建

以下步骤基于 Linux/macOS 环境，Windows 用户请使用 WSL2 或 PowerShell 配合 minikube.exe 执行。

4.2.1 安装 Minikube 与驱动

# 下载 Minikube 二进制（v1.34.0 及以上）
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# 验证安装
minikube version

# 安装 Docker 驱动（推荐）
sudo apt-get update && sudo apt-get install -y docker.io
sudo usermod -aG docker $USER && newgrp docker

4.2.2 启动集群并配置资源

# 启动 Minikube 集群，指定资源与 Kubernetes 版本
minikube start \
  --driver=docker \
  --cpus=4 \
  --memory=8192 \
  --kubernetes-version=v1.30.0 \
  --cni=calico

# 启用必要插件
minikube addons enable ingress
minikube addons enable metrics-server
minikube addons enable dashboard

# 检查集群状态
kubectl cluster-info
kubectl get nodes -o wide

4.2.3 验证集群就绪

# 运行一个测试 Pod 验证调度
kubectl run test-pod --image=nginx:alpine --restart=Never
kubectl wait --for=condition=Ready pod/test-pod --timeout=30s
kubectl delete pod test-pod

# 查看集群组件健康状态
kubectl get pods -n kube-system

4.3 K3s 集群搭建（备选方案）

当资源受限或需要快速启动多个独立集群进行契约测试隔离时，K3s 是更优选择。

# 一键安装 K3s（v1.30.0+k3s1）
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.30.0+k3s1 sh -

# 设置 kubectl 访问权限
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
export KUBECONFIG=~/.kube/config

# 验证集群
kubectl get nodes
kubectl get pods -A

# 查看 K3s 内置组件（traefik、local-path-provisioner）
kubectl get pods -n kube-system

4.4 kubectl 配置与上下文管理

契约测试通常需要在多个集群或命名空间之间切换，合理的 kubectl 配置能大幅提升效率。

4.4.1 配置多集群上下文

# 查看当前上下文
kubectl config current-context

# 添加 Minikube 集群上下文（通常自动生成）
kubectl config set-context minikube-contract \
  --cluster=minikube \
  --user=minikube \
  --namespace=contract-testing

# 添加 K3s 集群上下文
kubectl config set-context k3s-contract \
  --cluster=default \
  --user=default \
  --namespace=contract-testing

# 切换上下文
kubectl config use-context minikube-contract

4.4.2 配置自动补全与别名

# Bash 自动补全
source <(kubectl completion bash)
echo "source <(kubectl completion bash)" >> ~/.bashrc

# 常用别名（提升契约测试操作效率）
alias k='kubectl'
alias kg='kubectl get'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias kx='kubectl exec -it'
alias kn='kubectl config set-context --current --namespace'

# 查看当前命名空间
kubectl config view --minify -o jsonpath='{..namespace}'

4.5 命名空间规划策略

在契约测试的 API 事务边界治理中，命名空间不仅是资源隔离单元，更是 契约版本 与 事务边界 的逻辑分区。推荐采用以下三层规划模型：

4.5.1 命名空间创建脚本

#!/bin/bash
# create-contract-ns.sh — 创建契约测试三层命名空间

BASE_NS="contract-base"
BOUNDARY_ID=${1:-"tx-boundary-001"}
SNAPSHOT_TS=$(date +%Y%m%d%H%M%S)

# 创建基础环境命名空间（幂等）
kubectl create namespace $BASE_NS --dry-run=client -o yaml | kubectl apply -f -

# 创建事务边界命名空间
kubectl create namespace contract-boundary-$BOUNDARY_ID --dry-run=client -o yaml | kubectl apply -f -

# 创建验证快照命名空间
kubectl create namespace contract-snapshot-$SNAPSHOT_TS --dry-run=client -o yaml | kubectl apply -f -

# 为边界命名空间打标签（便于选择器过滤）
kubectl label namespace contract-boundary-$BOUNDARY_ID \
  contract.scope=boundary \
  contract.boundary-id=$BOUNDARY_ID

echo "命名空间创建完成："
echo "  - $BASE_NS"
echo "  - contract-boundary-$BOUNDARY_ID"
echo "  - contract-snapshot-$SNAPSHOT_TS"

4.5.2 命名空间资源配额与限制

为防止单个契约测试用例耗尽集群资源，必须为事务边界命名空间设置资源配额：

apiVersion: v1
kind: ResourceQuota
metadata:
  name: contract-boundary-quota
  namespace: contract-boundary-tx-boundary-001
spec:
  hard:
    requests.cpu: "1"
    requests.memory: "1Gi"
    limits.cpu: "2"
    limits.memory: "2Gi"
    pods: "10"
    services: "5"
    configmaps: "10"
---
apiVersion: v1
kind: LimitRange
metadata:
  name: contract-boundary-limits
  namespace: contract-boundary-tx-boundary-001
spec:
  limits:
  - default:
      cpu: "500m"
      memory: "512Mi"
    defaultRequest:
      cpu: "200m"
      memory: "256Mi"
    type: Container

4.6 环境验证清单

完成集群搭建与命名空间规划后，执行以下验证步骤确保环境就绪：

1. 集群连通性： kubectl cluster-info 返回正常，API Server 可达。
2. 节点状态： kubectl get nodes 显示 Ready 状态，kubelet 版本与预期一致。
3. DNS 解析： 部署一个 busybox Pod 执行 nslookup kubernetes.default.svc.cluster.local，确认 CoreDNS 正常工作。
4. Ingress 控制器： kubectl get pods -n ingress-nginx 或 kubectl get pods -n kube-system | grep traefik 显示 Running。
5. 命名空间隔离： 在 contract-base 中部署的服务无法直接访问 contract-boundary-* 中的 Pod IP（通过 NetworkPolicy 验证）。
6. 资源配额生效： 尝试在边界命名空间中创建超过配额限制的 Pod，应收到 Forbidden 错误。

至此，Kubernetes 验证环境已准备就绪。下一阶段将基于此环境部署契约测试基础设施，包括 Pact Broker、Provider 与 Consumer 服务，并开始执行 API 事务边界的契约验证。