网络策略

operator 在两个层级管理 Kubernetes NetworkPolicy 资源，二者默认均处于关闭状态：

集群策略 — 针对各个集群的策略，涵盖 ClickHouseCluster 和 KeeperCluster 资源的内部流量，可通过每个自定义资源中的 spec.networkPolicy 启用。
Operator pod (容器组) 策略 — 图表随附的策略，用于限制进入 controller manager pod (容器组) 本身的流量，适用于指标和 webhook 端点。

只有当 cluster 的 CNI plugin 实现了 NetworkPolicy 时，NetworkPolicy 才会生效 (例如 Calico 或 Cilium) 。如果 CNI 不强制执行 NetworkPolicy，这些资源虽然会被创建，但实际上不会产生任何效果，而且 Kubernetes 也不会返回 error。在依赖这些策略之前，请先确认你的 CNI 会强制执行这些策略。

集群网络策略

为每个集群启用托管策略：

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
spec:
  networkPolicy:
    policy: Enabled
---
apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
spec:
  networkPolicy:
    policy: Enabled

托管策略仅涵盖集群内部流量。选中这些 pod (容器组) 后，其入口流量将默认拒绝，operator 仅允许集群正常运行所需的流量：

集群	允许的来源	允许的端口
ClickHouse	集群自身的 Pod (容器组)	`9009` (服务器间通信) 、`9001` (管理)
ClickHouse	Operator pod (容器组) (标签为 `clickhouse.com/role: operator`，任意命名空间)	`9001`、`9002` (管理)
Keeper	集群自身的 Pod (容器组)	`9234` (Raft)
Keeper	Operator pod (容器组) 以及引用此 keeper 的所有 `ClickHouseCluster`	`2181`、`2281` (客户端) 、`9123` (HTTP 控制)

keeper 根据其 keeperClusterRef 允许 ClickHouse 集群接入——添加或移除引用会自动更新 keeper 的策略，包括来自其他命名空间的引用。

允许客户端连接和监控

客户端连接和指标抓取不在涵盖范围内：启用托管策略后，除非您明确允许，否则无法访问客户端端口 (9000/8123 或 TLS 变体) 或指标端口。NetworkPolicy 具有叠加性，因此请在托管策略之外，通过您自己的策略授予访问权限：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-clients
  namespace: <cluster-namespace>
spec:
  podSelector:
    matchLabels:
      app: <name>-clickhouse
  policyTypes: [Ingress]
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: my-app
    ports:
    - protocol: TCP
      port: 9000

同样适用于 Prometheus 抓取 (ClickHouse 使用端口 9363， Keeper 使用端口 9090) — 请明确允许监控命名空间访问。设置 networkPolicy.policy: Disabled (默认值) 会移除受管理的策略；operator 不会修改用户定义的策略，除非这些策略带有集群的 app 标签。

集群级禁用

还可通过 operator 的 ENABLE_NETWORK_POLICY 环境变量在整个集群范围内禁用 NetworkPolicy 管理。设置 ENABLE_NETWORK_POLICY=false 后，无论各个 ClickHouseCluster 和 KeeperCluster 的 spec.networkPolicy.policy 配置如何，operator 都会跳过每个集群的 NetworkPolicy reconcile 步骤，且完全不 watch NetworkPolicy 资源。因此，operator 的 ServiceAccount 无需拥有 networkpolicies.networking.k8s.io 的 RBAC 权限。这在使用受限 ServiceAccount 运行 operator 时非常有用，因为此类 ServiceAccount 会有意不授予这些权限。

# in the operator Deployment spec
env:
- name: ENABLE_NETWORK_POLICY
  value: "false"

使用 Helm 时，可通过图表值设置同一开关：

# values.yaml
controller:
  networkPolicyManagement:
    enabled: false

Operator pod (容器组) 策略

该图表还附带可选策略，用于限制哪些流量可以到达 controller manager pod (容器组) ——也就是 operator 进程本身。这些策略覆盖 operator 向其他客户端公开的两个端口：指标端点和 admission webhook。

Helm 图表会创建什么

启用后，该图表最多会创建两个仅针对入口流量的策略，二者都会选择 controller-manager pod (容器组) ：

策略	允许的来源	允许的端口
`allow-metrics-traffic`	带有 `metrics: enabled` 标签的命名空间	`metrics.port` (默认 `8080`/TCP)
`allow-webhook-traffic`	带有 `webhook: enabled` 标签的命名空间	`webhook.port` (默认 `9443`/TCP)

这两个策略都只声明 policyTypes: [Ingress]。它们不会限制 operator 的出站流量，也不会影响 ClickHouse server 或 Keeper pod (容器组) 。

默认拒绝行为

当某个 pod (容器组) 被入口 NetworkPolicy 选中时，该 pod (容器组) 就会切换为对入口流量默认拒绝：一旦任一策略生效，所有未被显式允许、发往 controller manager pod (容器组) 的入站流量都会被丢弃。启用后，唯一能够到达 operator 的入口流量只有：

来自带有 metrics: enabled 标签的命名空间的指标抓取，以及
来自带有 webhook: enabled 标签的命名空间的 admission webhook 调用。

发往该 pod (容器组) 的其他所有流量都会被拒绝。这正是预期的加固效果，但也意味着未加标签的抓取器或 webhook 调用方会在这些策略生效的那一刻停止工作。

启用这些策略

如果使用 Helm，请在配置值中设置此开关：

# values.yaml
networkPolicy:
  enabled: true

helm upgrade --install clickhouse-operator \
  oci://ghcr.io/clickhouse/clickhouse-operator-helm \
  -n clickhouse-operator-system --create-namespace \
  -f values.yaml

allow-webhook-traffic 还要求 webhook.enabled: true ( 默认启用) ，因此禁用 webhook 也会一并移除其策略。对于原始 kubectl 清单，请按 kubectl install guide 中所述，取消注释 [NETWORK POLICY] 部分。这些原始清单同样包含这两条策略。

为客户端命名空间添加标签

由于这两条策略都会通过 namespaceSelector 匹配源命名空间，因此每个需要访问 operator 的命名空间都必须带有相应的标签。来自未打标签命名空间的抓取或 webhook 调用都会被丢弃。

# Allow a Prometheus namespace to scrape the metrics endpoint
kubectl label namespace <prometheus-namespace> metrics=enabled

# Allow webhook callers from a given namespace
kubectl label namespace <caller-namespace> webhook=enabled

请将其与 Monitoring → 保护指标端点中介绍的指标 RBAC 配合使用： NetworkPolicy 控制可达性，而 集群角色 绑定控制授权。要让受保护的抓取成功，这两者都必须同时具备。

准入 webhook 请求来自 Kubernetes API server，而不是普通的 pod (容器组) 。这些流量是否受 NetworkPolicy 约束，以及它显示为来自哪个源，取决于你的控制平面拓扑和 CNI — 托管控制平面尤其如此，它们可能会从 namespaceSelector 无法匹配的地址访问该 webhook。如果 API server 的流量不在 webhook: enabled 命名空间的覆盖范围内，启用 allow-webhook-traffic 可能会阻断准入，并导致 ClickHouseCluster/KeeperCluster 的创建和更新请求超时。启用后，请先在非生产集群上测试准入；如有需要，再为 API server 添加一条显式放行规则。

验证

NS=clickhouse-operator-system

# The policies exist
kubectl -n $NS get networkpolicy

# Inspect the selectors and allowed sources
kubectl -n $NS describe networkpolicy

启用后，请确认：

Prometheus 仍在抓取指标端点 (其命名空间带有 metrics: enabled 标签，并绑定到 metrics-reader 集群角色) 。
创建或更新 ClickHouseCluster 仍可通过准入控制 (webhook 可达) 。

如果抓取未返回数据，或者对 CR 执行 apply 时卡住，最可能的原因是源命名空间未打标签，或上文提到的 API 服务器可达性注意事项。

Operator 监控 — 指标端点、其 RBAC，以及如何保护抓取过程。
使用 kubectl 安装 — 在哪里取消网络策略部分的注释。
使用 Helm 安装 — 与 Operator 相关的 chart 配置值。

Install

Guides

Reference

集群网络策略

允许客户端连接和监控

集群级禁用

Operator pod (容器组) 策略

Helm 图表会创建什么

默认拒绝行为

启用这些策略

为客户端命名空间添加标签

验证

​集群网络策略

​允许客户端连接和监控

​集群级禁用

​Operator pod (容器组) 策略

​Helm 图表会创建什么

​默认拒绝行为

​启用这些策略

​为客户端命名空间添加标签

​验证

​相关指南

集群网络策略

允许客户端连接和监控

集群级禁用

Operator pod (容器组) 策略

Helm 图表会创建什么

默认拒绝行为

启用这些策略

为客户端命名空间添加标签

验证

相关指南