4. Calico API Server (calico-apiserver) 部署与配置：安装、TLS证书、RBAC权限

Calico API Server（calico-apiserver）是控制平面驱动准入策略的核心组件。它作为 Kubernetes API 的聚合层扩展，将 Calico 资源（如 NetworkPolicy、GlobalNetworkPolicy、NetworkSet）以标准 CRD 形式暴露，并负责执行准入控制器的 Webhook 回调。本章将详细讲解其部署流程、TLS 证书配置以及 RBAC 权限绑定。

4.1 架构定位与组件关系

在部署之前，理解 calico-apiserver 在集群中的位置至关重要。它并非独立运行，而是作为 API 聚合层注册到 kube-apiserver，所有 Calico 资源的读写请求均通过此路径。

4.2 安装方式与版本选择

推荐使用 Helm Chart 或 Operator 进行安装，避免手动 YAML 拼写错误。以下为两种主流方式的对比：

4.2.1 Helm 安装示例

# 添加 Calico Helm 仓库
helm repo add projectcalico https://docs.tigera.io/calico/charts
helm repo update

# 安装 calico-apiserver
helm upgrade --install calico-apiserver projectcalico/tigera-apiserver \
  --namespace calico-apiserver \
  --create-namespace \
  --set image.pullPolicy=IfNotPresent \
  --set apiServerReplicas=2 \
  --set certificate.certManager.enabled=true

4.3 TLS 证书配置

calico-apiserver 与 kube-apiserver 之间的通信必须使用 TLS。证书配置有三种方式，按安全等级排序：

1. cert-manager 自动签发（推荐）：利用 cert-manager 自动生成并轮换证书，Helm 中设置 certificate.certManager.enabled=true。
2. 手动提供 Secret：预先生成证书并创建 Kubernetes Secret，适用于已有 PKI 体系的环境。
3. 自签名证书（仅测试）：使用 OpenSSL 生成临时证书，生产环境不推荐。

4.3.1 手动证书 Secret 结构

手动方式需要提供以下三个文件，并创建 Secret：

# 生成证书（示例，生产环境应使用内部 CA）
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt -subj "/CN=calico-apiserver"

# 创建 Secret
kubectl create secret tls calico-apiserver-certs \
  --cert=tls.crt --key=tls.key \
  -n calico-apiserver

4.4 RBAC 权限配置

calico-apiserver 需要适当的 RBAC 权限来管理 Calico CRD 资源，同时也要为客户端（如 kubectl、CI/CD 系统）配置访问权限。

4.4.1 calico-apiserver 自身 ServiceAccount

安装时自动创建 calico-apiserver ServiceAccount，并绑定以下 ClusterRole：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: calico-apiserver
rules:
- apiGroups: ["crd.projectcalico.org"]
  resources: ["*"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["projectcalico.org"]
  resources: ["*"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["apiextensions.k8s.io"]
  resources: ["customresourcedefinitions"]
  verbs: ["get", "list", "watch"]

4.4.2 客户端访问权限

普通用户或服务账号需要访问 Calico 资源时，需绑定以下 ClusterRole：

# 示例：为 CI 系统创建只读权限
kubectl create clusterrolebinding ci-calico-reader \
  --clusterrole=calico-network-policy-reader \
  --serviceaccount=ci-namespace:ci-sa

4.5 部署验证与健康检查

部署完成后，执行以下步骤验证：

1. 检查 Pod 状态：kubectl get pods -n calico-apiserver，确保所有 Pod 处于 Running 状态。
2. 验证 API 聚合：kubectl get apiservice v3.projectcalico.org，状态应为 True。
3. 测试 CRD 访问：kubectl get globalnetworkpolicies，应返回空列表或已有策略。
4. 检查 TLS 证书：kubectl logs -n calico-apiserver deploy/calico-apiserver | grep -i tls，确认无证书错误。

4.6 常见问题与排障

• 证书不匹配：kube-apiserver 日志报 x509: certificate is valid for ... not ...，检查证书 CN/SAN 是否包含 calico-apiserver.calico-apiserver.svc。
• API 聚合超时：Failed to connect to calico-apiserver: dial tcp: i/o timeout，检查网络策略或 CoreDNS 解析。
• RBAC 权限不足：Forbidden! User "system:serviceaccount:..." cannot list resource "globalnetworkpolicies"，按 4.4 节绑定对应 ClusterRole。