> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 네트워크 정책

> 연산자가 ClickHouse 및 Keeper 클러스터의 Kubernetes NetworkPolicies를 관리하는 방법, 클라이언트 및 모니터링 트래픽을 허용하는 방법, 그리고 controller manager 파드로의 인그레스를 제한하는 방법을 설명합니다.

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

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

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

<div id="cluster-network-policies">
  ## 클러스터 NetworkPolicies
</div>

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

```yaml theme={null}
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의 정책이 자동으로 업데이트됩니다.

<div id="allowing-clients">
  ### 클라이언트 및 모니터링 허용
</div>

클라이언트 연결과 메트릭 스크래핑은 **포함되지 않습니다**. 관리형
정책을 활성화하면 별도로 허용하기 전까지 클라이언트 포트(`9000`/`8123` 또는 TLS
변형)나 메트릭 포트에 연결할 수 없습니다. NetworkPolicy는 추가 방식으로 적용되므로,
관리형 정책과 함께 자체 정책을 추가하여 액세스를 허용하십시오:

```yaml theme={null}
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` 레이블이 있는 경우가 아니면 연산자가 절대 수정하지 않습니다.

<div id="np-cluster-wide-disable">
  ### 클러스터 전체 옵트아웃
</div>

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

```yaml theme={null}
# in the operator Deployment spec
env:
- name: ENABLE_NETWORK_POLICY
  value: "false"
```

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

```yaml theme={null}
# values.yaml
controller:
  networkPolicyManagement:
    enabled: false
```

<div id="operator-pod-policies">
  ## 연산자 파드 정책
</div>

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

<div id="what-the-helm-chart-creates">
  ## Helm 차트가 생성하는 항목
</div>

활성화하면 이 차트는 최대 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 파드에는 적용되지 않습니다.

<div id="default-deny">
  ## 기본 거부 동작
</div>

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

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

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

<div id="enabling">
  ## 정책 활성화
</div>

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

```yaml theme={null}
# values.yaml
networkPolicy:
  enabled: true
```

```bash theme={null}
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 설치 가이드](/ko/products/kubernetes-operator/install/kubectl)에 설명된 대로 `[NETWORK POLICY]` 섹션의 주석 처리를 해제하십시오.
raw 매니페스트에는 동일한 두 개의 정책이 포함되어 있습니다.

<div id="labeling-namespaces">
  ## 클라이언트 네임스페이스에 레이블 지정
</div>

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

```bash theme={null}
# 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와 함께 구성하십시오.
[모니터링 → 메트릭 엔드포인트 보안](/ko/products/kubernetes-operator/guides/monitoring#securing-the-metrics-endpoint):
NetworkPolicy는 연결 가능 여부를 제어하고, 클러스터 역할 바인딩은
권한 부여를 제어합니다. 보안이 적용된 스크레이프가 성공하려면 둘 다 반드시 구성되어 있어야 합니다.

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

<div id="verifying">
  ## 확인하기
</div>

```bash theme={null}
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 서버 도달성 관련 주의 사항이 가장 가능성 높은 원인입니다.

<div id="related-guides">
  ## 관련 가이드
</div>

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