juwan/juwan-backend

Fork 0

Files

T

wwweww fdbcde13b2 add:

2026-02-23 20:36:21 +08:00

11 KiB

Raw Blame History

JWT Secret + ETCD Encryption Deployment Guide

完整的 JWT 认证系统部署指南，包括密钥管理、RBAC 权限控制和 ETCD 加密。

部署顺序

第1步：创建 Secret 和 RBAC（必需）

创建 JWT 秘钥和服务账户权限：

kubectl apply -f deploy/k8s/secrets/jwt-secret.yaml

验证创建成功：

# 检查 Secret
kubectl get secret jwt-secret -n juwan
kubectl get secret jwt-secret -n juwan -o yaml

# 检查 ServiceAccounts
kubectl get sa user-rpc -n juwan
kubectl get sa envoy-gateway -n juwan

# 检查 RBAC 权限
kubectl get role jwt-secret-reader -n juwan
kubectl get rolebinding -n juwan -l app=jwt-secret-reader

第2步：更新 user-rpc 部署（依赖第1步）

已自动更新 deploy/k8s/service/user/user-rpc.yaml：

✅ 更新 serviceAccountName 从 find-endpoints → user-rpc
✅ 添加环境变量 JWT_SECRET_KEY 从 Secret jwt-secret 读取

应用更新：

kubectl apply -f deploy/k8s/service/user/user-rpc.yaml

验证部署：

# 检查 ServiceAccount 已正确绑定
kubectl get deployment user-rpc -n juwan -o yaml | grep -A 5 serviceAccountName

# 查看 Pod 是否以 user-rpc ServiceAccount 身份运行
kubectl get pod -n juwan -l app=user-rpc -o yaml | grep serviceAccount

# 验证环境变量已注入
kubectl exec -it POD_NAME -n juwan -- env | grep JWT_SECRET_KEY

第3步：更新 Envoy 网关部署（依赖第1步）

已自动更新 deploy/k8s/envoy/envoy.yaml：

✅ 添加 serviceAccountName: envoy-gateway 到 Deployment spec

应用更新：

kubectl apply -f deploy/k8s/envoy/envoy.yaml

验证部署：

# 检查 ServiceAccount 已正确绑定
kubectl get deployment envoy-gateway -n juwan -o yaml | grep -A 2 serviceAccountName

# 检查 Pod 状态
kubectl get pod -n juwan -l app=envoy-gateway

第4步：启用 ETCD 加密（强烈推荐用于生产环境）

这是一个集群级别的配置，需要在 Kubernetes 控制平面节点上执行。

前提条件：

具有 Kubernetes 集群管理员权限
可以访问控制平面节点
备份 ETCD 数据库

步骤：

生成加密密钥
```
head -c 32 /dev/urandom | base64
```
记录输出的 Base64 密钥。

创建加密配置文件

在控制平面节点上，创建 /etc/kubernetes/encryption-config.yaml：

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
    providers:
      - aescbc:
          keys:
            - name: key1
              secret: <BASE64_ENCODED_32_BYTE_KEY>
      - identity: {}

替换 <BASE64_ENCODED_32_BYTE_KEY> 为第1步生成的密钥。

修改 kube-apiserver 配置

在控制平面节点上，编辑 /etc/kubernetes/manifests/kube-apiserver.yaml：

添加参数：

spec:
  containers:
  - name: kube-apiserver
    command:
      - kube-apiserver
      - --encryption-provider-config=/etc/kubernetes/encryption-config.yaml

添加卷挂载：

spec:
  containers:
  - name: kube-apiserver
    volumeMounts:
    - name: encryption-config
      mountPath: /etc/kubernetes
      readOnly: true

volumes:
- name: encryption-config
  hostPath:
    path: /etc/kubernetes
    type: DirectoryOrCreate

重启 kube-apiserver

修改清单后，kubelet 会自动重启 kube-apiserver。检查状态：

# 在控制平面节点
kubectl get pods -n kube-system | grep kube-apiserver

# 监控重启过程
kubectl logs -n kube-system -l component=kube-apiserver -f

验证加密是否启用

创建一个新 Secret 并检查它在 ETCD 中是否加密：

# 创建测试 Secret
kubectl create secret generic test-secret -n juwan --from-literal=key=value

# 从 control plane 节点检查 ETCD 数据
# 如果数据不可读并包含加密标记，说明加密已启用

保存加密密钥

⚠️ 关键：将加密密钥安全地保存在离线存储中
- 密钥丢失后，无法解密 ETCD 中的数据
- 无法恢复任何 Secrets
- 建议用密码管理工具（如 HashiCorp Vault）或 HSM 存储密钥

第5步：验证整个系统

完整的验证清单：

# 检查所有 Secrets 已创建
kubectl get secret -n juwan
kubectl get secret jwt-secret -n juwan -o jsonpath='{.data.secret-key}' | base64 -d

# 检查 ServiceAccounts 已创建
kubectl get sa -n juwan
kubectl describe sa user-rpc -n juwan
kubectl describe sa envoy-gateway -n juwan

# 检查 RBAC 权限
kubectl get role -n juwan
kubectl get rolebinding -n juwan
kubectl describe role jwt-secret-reader -n juwan

# 测试权限：user-rpc 可以读 jwt-secret
kubectl auth can-i get secrets --as=system:serviceaccount:juwan:user-rpc --resource-name=jwt-secret -n juwan

# 测试权限：envoy-gateway 可以读 jwt-secret
kubectl auth can-i get secrets --as=system:serviceaccount:juwan:envoy-gateway --resource-name=jwt-secret -n juwan

# 测试权限：其他 ServiceAccount 无法读取
kubectl auth can-i get secrets --as=system:serviceaccount:juwan:other-service -n juwan

# 检查 Deployments 已正确配置
kubectl get deployment user-rpc -n juwan -o yaml | grep -A 2 serviceAccountName
kubectl get deployment envoy-gateway -n juwan -o yaml | grep -A 2 serviceAccountName

# 检查 Pods 是否已启动并运行
kubectl get pods -n juwan -l app=user-rpc
kubectl get pods -n juwan -l app=envoy-gateway

# 查看 JWT Secret 是否已挂载到 Pod
kubectl exec -it $(kubectl get pod -n juwan -l app=user-rpc -o name | head -1) -n juwan -- env | grep JWT_SECRET_KEY

监控和日志

查看 Pod 日志

# user-rpc 日志
kubectl logs -n juwan -l app=user-rpc -f --all-containers=true

# Envoy 日志
kubectl logs -n juwan -l app=envoy-gateway -f

检查 Pod 事件

# 查看 Pod 创建和启动事件
kubectl describe pod -n juwan -l app=user-rpc
kubectl describe pod -n juwan -l app=envoy-gateway

权限问题排查

如果 Pod 无法读取 Secret：

# 检查 Pod 使用的 ServiceAccount
kubectl get pod POD_NAME -n juwan -o yaml | grep serviceAccountName

# 检查 RBAC 绑定
kubectl get rolebinding -n juwan -o wide

# 检查 Role 权限定义
kubectl get role jwt-secret-reader -n juwan -o yaml

# 尝试用 Pod 的身份读取 Secret（需要 kubectl-user-impersonate 或类似工具）
kubectl get secret jwt-secret --as=system:serviceaccount:juwan:user-rpc -n juwan

安全最佳实践

1. 密钥轮换

周期性更换 JWT 秘钥（建议每季度）：

# 1. 生成新密钥
NEW_KEY=$(head -c 32 /dev/urandom | base64)

# 2. 更新 Secret
kubectl create secret generic jwt-secret \
  --from-literal=secret-key=$NEW_KEY \
  --dry-run=client -o yaml | kubectl apply -f -

# 3. 重启 Pods 以加载新密钥（滚动更新）
kubectl rollout restart deployment/user-rpc -n juwan
kubectl rollout restart deployment/envoy-gateway -n juwan

# 4. 验证新 Pods 已启动并运行
kubectl rollout status deployment/user-rpc -n juwan
kubectl rollout status deployment/envoy-gateway -n juwan

# 5. 已颁发的旧令牌将变为无效
# 需要用户重新登录获取新令牌

2. 审计和监控

在生产环境中启用 Kubernetes 审计日志来跟踪 Secret 访问：

# kube-apiserver 审计策略示例
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
  # 记录 secret 资源的访问
  - level: RequestResponse
    verbs: ["get", "list", "watch"]
    resources: ["secrets"]
  # 记录所有认证失败
  - level: RequestResponse
    omitStages:
      - RequestReceived
    userGroups: ["system:unauthenticated"]
  - level: Metadata
    omitStages:
      - RequestReceived

3. 网络策略

使用 NetworkPolicy 限制 Pods 之间的通信：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: jwt-secret-access
  namespace: juwan
spec:
  podSelector:
    matchLabels:
      app: jwt-secret-reader
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: user-rpc
        - podSelector:
            matchLabels:
              app: envoy-gateway
      ports:
        - protocol: TCP
          port: 443  # API Server

灾难恢复

备份 Secret 和 RBAC 配置

# 备份 JWT Secret
kubectl get secret jwt-secret -n juwan -o yaml > jwt-secret-backup.yaml

# 备份 RBAC 配置
kubectl get role jwt-secret-reader -n juwan -o yaml > jwt-role-backup.yaml
kubectl get rolebinding -n juwan -l app=jwt-secret-reader -o yaml > jwt-rolebinding-backup.yaml

# 加密备份文件
gpg --symmetric jwt-secret-backup.yaml

恢复步骤

如果 Secret 被意外删除：

# 从备份恢复
kubectl apply -f jwt-secret-backup.yaml

# 重启 Pods 以重新加载 Secret
kubectl rollout restart deployment/user-rpc -n juwan
kubectl rollout restart deployment/envoy-gateway -n juwan

常见问题

Q: Pod 无法启动，显示 "failed to pull secret"

A: 检查：

Secret 是否存在：kubectl get secret jwt-secret -n juwan
ServiceAccount 是否绑定了 RBAC：kubectl describe rolebinding -n juwan
Secret 名称和命名空间是否正确

Q: 加密后如何验证 ETCD 中的数据已加密？

A: 从 control plane 节点：

# 直接读取 ETCD（如果配置了加密，数据应该不可读）
sudo strings /var/lib/etcd/member/snap/db | grep -i secret

Q: 能否更改加密密钥而不重新创建 ETCD？

A: 可以，但流程复杂：

更新 encryption-config.yaml 中的新密钥
将新密钥添加到提供程序列表（保持旧密钥）
重启 kube-apiserver
触发重新加密：kubectl get all --all-namespaces -o json | kubectl apply -f -

Q: 如何在 Minikube 中启用 ETCD 加密？

A: 参考 ENCRYPTION.md 中的 Minikube 特定说明部分。

下一步

部署完成后：

集成 JWT 验证到 RPC Handlers
- 实现 gRPC unary interceptor
- 验证令牌有效性
- 处理令牌刷新逻辑
集成 JWT 验证到 Envoy
- 扩展 Lua filter 进行令牌验证
- 返回 401（无效令牌）或 200（有效令牌）
端到端测试
- 创建用户和登录
- 生成和验证 JWT
- 测试令牌刷新和撤销
- 验证 ETCD 加密
生产部署
- 启用审计日志
- 配置密钥轮换计划
- 建立备份和恢复流程
- 监控 Secret 访问

11 KiB Raw Blame History Unescape Escape