KubeBYON Cluster 级工作负载 Admission Webhook 部署与验证

最后更新：2026-05-16

本文档说明如何在 Docker Compose 部署的 KubeBYON 后端 上启用并验证 cluster 级 workload admission webhook。

当前推荐模式是：

  • 本地完成代码修改与测试
  • 源码同步到远程服务器
  • 镜像构建与容器重启全部在远程执行

1. 目标与范围

当前实现包含两部分：

  • Mutating webhook
    • 对未声明资源的 Pod 自动补默认 requests / limits
  • Validating webhook
    • 在 Pod 创建前校验 cluster 内所有业务命名空间工作负载总和是否超额

适用前提：

  • KubeBYON 后端已经通过 deployments/single-node/docker-compose 运行
  • 后端模式为 vcluster
  • 你希望对 vCluster 内工作负载启用 cluster 级资源准入控制

admission webhook 不是单独的独立进程。 它由 kubebyon-api 自身额外监听一个 HTTPS 端口提供。

2. 部署前确认

请先确认：

  • 远程后端机已经可用
  • docker compose 正常
  • 宿主机 kubeconfig 可访问宿主集群
  • 已准备好后端公网 IP / 域名
  • 如需实机验证，已经有一个可操作的测试 cluster

如果你还没先把后端 Compose 跑起来，请先看：

  • docs/runbooks/deploy-kubebyon-backend-docker-compose.md

3. 需要的配置项

启用 admission 时，.env 里需要存在：

KUBEBYON_ADMISSION_ADDR=:9443
KUBEBYON_ADMISSION_BASE_URL=https://YOUR_PUBLIC_IP:9443
KUBEBYON_ADMISSION_TLS_CERT_FILE=/etc/kubebyon/runtime/admission/tls.crt
KUBEBYON_ADMISSION_TLS_KEY_FILE=/etc/kubebyon/runtime/admission/tls.key
KUBEBYON_ADMISSION_SHARED_SECRET=<RANDOM_HEX>

要求：

  • KUBEBYON_ADMISSION_BASE_URL 必须是 https
  • 证书 SAN 要覆盖 YOUR_PUBLIC_IP 或对应域名
  • KUBEBYON_ADMISSION_SHARED_SECRET 要使用随机长串

4. 生成证书与 shared secret

推荐直接使用 Compose 目录中的脚本生成，而不是手写 openssl 命令。

进入远程目录：

cd /opt/kubebyon/deployments/single-node/docker-compose
mkdir -p runtime/admission

生成文件：

./gen-admission-assets.sh YOUR_PUBLIC_IP 9443 ./runtime/admission

生成物包括：

  • runtime/admission/tls.crt
  • runtime/admission/tls.key
  • runtime/admission/shared-secret.txt
  • runtime/admission/admission.env

把 env 片段写入 .env：

cat runtime/admission/admission.env >> .env

验证 SAN：

openssl x509 -in runtime/admission/tls.crt -text -noout | grep -A1 'Subject Alternative Name'

5. Compose 侧需要满足的条件

当前 Compose 已经内置好 admission 所需的接线，关键点包括：

5.1 环境变量透传

docker-compose.yml 里会把以下变量传给 kubebyon-api：

  • KUBEBYON_ADMISSION_ADDR
  • KUBEBYON_ADMISSION_BASE_URL
  • KUBEBYON_ADMISSION_TLS_CERT_FILE
  • KUBEBYON_ADMISSION_TLS_KEY_FILE
  • KUBEBYON_ADMISSION_SHARED_SECRET

5.2 证书目录挂载

kubebyon-api 需要挂载：

- ./runtime/admission:/etc/kubebyon/runtime/admission:ro

5.3 启动前校验

start-kubebyon.sh 会在 admission 启用时检查：

  • KUBEBYON_ADMISSION_BASE_URL
  • KUBEBYON_ADMISSION_SHARED_SECRET
  • KUBEBYON_ADMISSION_TLS_CERT_FILE
  • KUBEBYON_ADMISSION_TLS_KEY_FILE

如果缺失，容器会直接启动失败，而不是带病运行。

6. 远程构建并重启

注意：镜像构建必须在远程服务器执行。

cd /opt/kubebyon/deployments/single-node/docker-compose
docker compose --env-file .env up -d --build

查看状态与日志：

docker compose --env-file .env ps
docker compose --env-file .env logs --tail=120 kubebyon-platform-secret-bootstrap kubebyon-api

预期日志中会看到：

  • starting kubebyon admission api
  • starting kubebyon api

7. 基础健康检查

7.1 API

curl -fsS http://YOUR_PUBLIC_IP:8080/healthz

7.2 Admission HTTPS

curl -kI https://YOUR_PUBLIC_IP:9443/

预期：

  • HTTP 状态码通常是 404
  • 重点是端口可连通，不能 connection refused

8. 让 webhook 配置真正下发到 vCluster

webhook 配置的同步发生在以下时机：

  • ProvisionCluster
  • UpdateCluster

因此：

  • 新创建的 cluster 会自动下发 webhook 配置
  • 老 cluster 在升级到新版本后，需要做一次更新，才能把 webhook 配置补进去

8.1 登录后台

curl -fsS -c cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@kubebyon.local","password":"<ADMIN_PASSWORD>"}' \
  http://YOUR_PUBLIC_IP:8080/api/auth/login

8.2 对已有 cluster 做一次 no-op 更新

curl -fsS -b cookie.txt \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{"workload_cpu_limit_milli_cores":1000,"workload_memory_limit_mib":512}' \
  http://YOUR_PUBLIC_IP:8080/api/console/clusters/CLUSTER_ID

如果是新 cluster，可跳过这一步。

9. 验证 webhook 配置是否存在

推荐先下载 kubeconfig，再用本地 kubectl 验证。

9.1 下载 kubeconfig

read -rsp 'Current password: ' KUBEBYON_CURRENT_PASSWORD
printf '\n'
tmp_payload="$(mktemp)"
trap 'rm -f "$tmp_payload"' EXIT
export KUBEBYON_CURRENT_PASSWORD
python3 - <<'PY' > "$tmp_payload"
import json
import os

print(json.dumps({"password": os.environ["KUBEBYON_CURRENT_PASSWORD"]}))
PY
unset KUBEBYON_CURRENT_PASSWORD

curl -fsS -b cookie.txt \
  -H 'Content-Type: application/json' \
  -X POST \
  -d @"$tmp_payload" \
  'http://YOUR_PUBLIC_IP:8080/api/console/clusters/CLUSTER_ID/kubeconfig?download=1' \
  > /tmp/cluster.kubeconfig

这里用 read -s 与临时 JSON 文件传递当前密码，避免把密码明文写进 shell history。?download=1 在后端支持时会直接返回 kubeconfig YAML attachment。

9.2 查看 webhook 配置

kubectl --kubeconfig /tmp/cluster.kubeconfig \
  get mutatingwebhookconfigurations,validatingwebhookconfigurations

预期会看到当前 cluster 对应的：

  • kubebyon-<cluster>-workload-mutate
  • kubebyon-<cluster>-workload-validate

10. 实机功能验证建议

10.1 验证 mutate：默认资源自动补全

创建一个不写 resources 的 Pod，确认 admission 后落地结果带有默认：

  • requests.cpu = 100m
  • requests.memory = 128Mi
  • limits.cpu = 1
  • limits.memory = 256Mi

10.2 验证 validate：超额 Pod 被拒绝

在多个业务 namespace 中逐步创建 Pod，直到总 requests / limits 超过 cluster workload hard limit，确认最后一个 Pod 被 admission 拒绝。

推荐关注报错里是否包含：

  • 当前已占用值
  • incoming Pod 的资源值
  • hard limit
  • 被拒绝对象的 namespace / pod name

11. 常见问题

11.1 为什么一定要 HTTPS？

因为 Kubernetes admission webhook 调用的是 API Server -> webhook server 的服务链路，默认要求 TLS。 当前实现中使用自签名证书，并把证书内容写入 webhook caBundle。

12.2 admission 是单独部署的吗？

不是。它和 kubebyon-api 一起部署，只是 kubebyon-api 额外监听了一个 HTTPS 端口。

12.3 为什么健康检查看到 404 也算正常？

因为这里检查的是端口连通性，而不是业务首页。 只要 curl -k https://YOUR_PUBLIC_IP:9443/ 不报连接失败，就说明 admission HTTPS server 已经起来了。