네트워크 정책

연산자는 기본적으로 비활성화된 두 가지 수준의 Kubernetes NetworkPolicy 리소스를 관리합니다.

클러스터 정책 — ClickHouseCluster 및 KeeperCluster 리소스의 내부 트래픽을 대상으로 하는 클러스터별 정책으로, 각 사용자 지정 리소스의 spec.networkPolicy를 통해 활성화합니다.
연산자 파드 정책 — 메트릭 및 웹훅 엔드포인트에 대해 controller manager 파드 자체로의 인그레스를 제한하는 차트 제공 정책입니다.

NetworkPolicy는 클러스터의 CNI plugin이 이를 구현하는 경우에만 적용됩니다 (예: Calico 또는 Cilium). NetworkPolicy 적용을 지원하지 않는 CNI에서는 해당 리소스가 생성되더라도 아무런 효과가 없으며, Kubernetes는 오류를 반환하지 않습니다. 따라서 이를 사용하기 전에 사용 중인 CNI가 정책을 실제로 적용하는지 확인하십시오.

클러스터 NetworkPolicies

클러스터별 관리형 정책을 활성화합니다:

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

관리형 정책은 클러스터 내부 트래픽에만 적용됩니다. 파드를 선택하면 인그레스가 기본 거부로 전환되며, 연산자는 클러스터 운영에 필요한 트래픽만 정확히 허용합니다:

클러스터	허용되는 소스	허용되는 포트
ClickHouse	클러스터 자체의 파드	`9009` (interserver), `9001` (management)
ClickHouse	연산자 파드(레이블 `clickhouse.com/role: operator`, 모든 네임스페이스)	`9001`, `9002` (management)
Keeper	클러스터 자체의 파드	`9234` (Raft)
Keeper	연산자 파드 및 이 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(기본값)로 설정하면 관리형 정책이 제거됩니다. 사용자가 정의한 정책은 클러스터의 app 레이블이 있는 경우가 아니면 연산자가 절대 수정하지 않습니다.

클러스터 전체 옵트아웃

연산자의 ENABLE_NETWORK_POLICY 환경 변수를 통해 클러스터 전체의 NetworkPolicy 관리를 비활성화할 수도 있습니다. ENABLE_NETWORK_POLICY=false로 설정하면 연산자는 spec.networkPolicy.policy 설정과 관계없이 모든 ClickHouseCluster 및 KeeperCluster의 NetworkPolicy 조정 단계를 건너뛰고, NetworkPolicy 리소스를 전혀 감시하지 않습니다. 따라서 연산자의 ServiceAccount에는 networkpolicies.networking.k8s.io에 대한 RBAC 권한이 필요하지 않으므로, 이러한 권한을 의도적으로 제외한 제한된 ServiceAccount에서 연산자를 실행할 때 유용합니다.

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

Helm에서는 동일한 설정을 차트 값으로 지정합니다:

# values.yaml
controller:
  networkPolicyManagement:
    enabled: false

연산자 파드 정책

차트는 어떤 트래픽이 연산자 프로세스 자체인 controller manager 파드에 도달할 수 있는지 제한하는 선택적 정책도 제공합니다. 이 정책은 연산자가 다른 클라이언트에 노출하는 두 개의 포트, 즉 메트릭 엔드포인트와 admission 웹훅을 대상으로 합니다.

Helm 차트가 생성하는 항목

활성화하면 이 차트는 최대 2개의 인그레스 전용 정책을 생성하며, 두 정책 모두 controller manager 파드를 대상으로 합니다:

정책	허용된 소스	허용된 포트
`allow-metrics-traffic`	`metrics: enabled` 레이블이 있는 네임스페이스	`metrics.port` (기본값 `8080`/TCP)
`allow-webhook-traffic`	`webhook: enabled` 레이블이 있는 네임스페이스	`webhook.port` (기본값 `9443`/TCP)

두 정책 모두 policyTypes: [Ingress]만 선언합니다. 따라서 연산자의 egress는 제한하지 않으며, ClickHouse 서버 또는 Keeper 파드에는 적용되지 않습니다.

기본 거부 동작

인그레스 NetworkPolicy로 파드를 선택하면 해당 파드는 인그레스 기본 거부 상태로 전환됩니다. 즉, 둘 중 하나의 정책이라도 적용되면 명시적으로 허용되지 않은 controller manager 파드로 들어오는 모든 인바운드 트래픽은 차단됩니다. 활성화 후 연산자에 도달할 수 있는 인그레스는 다음뿐입니다.

metrics: enabled로 레이블된 네임스페이스에서의 메트릭 스크레이프
webhook: enabled로 레이블된 네임스페이스에서의 admission webhook 호출

그 외 파드로 들어오는 모든 트래픽은 거부됩니다. 이는 의도된 보안 강화이지만, 레이블이 없는 scraper 또는 webhook 호출자는 정책이 적용되는 즉시 작동하지 않게 됩니다.

정책 활성화

Helm을 사용하는 경우 values에서 게이트를 설정하십시오:

# 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(기본값)가 필요하므로, 웹훅을 비활성화하면 해당 정책도 함께 제거됩니다. raw kubectl 매니페스트를 사용하는 경우, kubectl 설치 가이드에 설명된 대로 [NETWORK POLICY] 섹션의 주석 처리를 해제하십시오. raw 매니페스트에는 동일한 두 개의 정책이 포함되어 있습니다.

클라이언트 네임스페이스에 레이블 지정

두 정책 모두 namespaceSelector를 기준으로 소스를 매칭하므로, 연산자에 연결해야 하는 모든 네임스페이스에는 일치하는 레이블이 있어야 합니다. 레이블이 없는 네임스페이스에서 발생한 스크레이프 또는 웹훅 호출은 차단됩니다.

# 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

이를 다음에 설명된 메트릭 RBAC와 함께 구성하십시오. 모니터링 → 메트릭 엔드포인트 보안: NetworkPolicy는 연결 가능 여부를 제어하고, 클러스터 역할 바인딩은 권한 부여를 제어합니다. 보안이 적용된 스크레이프가 성공하려면 둘 다 반드시 구성되어 있어야 합니다.

admission webhook 요청은 일반 파드가 아니라 Kubernetes API server에서 발생합니다. 해당 트래픽에 NetworkPolicy가 적용되는지 여부와 어떤 소스로 표시되는지는 컨트롤 플레인 토폴로지와 CNI에 따라 달라집니다. 특히 관리형 컨트롤 플레인에서는 어떤 namespaceSelector로도 일치시킬 수 없는 주소에서 웹훅에 도달할 수 있습니다. API server의 트래픽이 webhook: enabled 네임스페이스에 포함되지 않은 상태에서 allow-webhook-traffic를 활성화하면 admission이 차단되어 ClickHouseCluster/KeeperCluster 생성 및 업데이트 요청이 시간 초과될 수 있습니다. 활성화한 후에는 프로덕션이 아닌 클러스터에서 admission을 테스트하고, 필요한 경우 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를 생성하거나 업데이트할 때도 계속 admission을 통과하는지 확인하십시오(웹훅에 연결할 수 있어야 합니다).

스크레이프 결과 데이터가 없거나 CR 적용이 멈춘다면, 레이블이 없는 소스 네임스페이스 또는 위에서 설명한 API 서버 도달성 관련 주의 사항이 가장 가능성 높은 원인입니다.

연산자 모니터링 — 메트릭 엔드포인트, 해당 RBAC, 그리고 스크레이프를 안전하게 보호하는 방법입니다.
kubectl로 설치 — 네트워크 policy 섹션의 주석을 해제해야 하는 위치입니다.
Helm으로 설치 — 연산자와 관련된 chart values입니다.

Install

Guides

Reference

클러스터 NetworkPolicies

클라이언트 및 모니터링 허용

클러스터 전체 옵트아웃

연산자 파드 정책

Helm 차트가 생성하는 항목

기본 거부 동작

정책 활성화

클라이언트 네임스페이스에 레이블 지정

확인하기

​클러스터 NetworkPolicies

​클라이언트 및 모니터링 허용

​클러스터 전체 옵트아웃

​연산자 파드 정책

​Helm 차트가 생성하는 항목

​기본 거부 동작

​정책 활성화

​클라이언트 네임스페이스에 레이블 지정

​확인하기

​관련 가이드

클러스터 NetworkPolicies

클라이언트 및 모니터링 허용

클러스터 전체 옵트아웃

연산자 파드 정책

Helm 차트가 생성하는 항목

기본 거부 동작

정책 활성화

클라이언트 네임스페이스에 레이블 지정

확인하기

관련 가이드