> ## 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.

# ネットワークポリシー

> operator が ClickHouse および Keeper クラスターの Kubernetes NetworkPolicies を管理する方法、クライアントおよび監視トラフィックを許可する方法、さらに controller manager ポッドへのイングレスを制限する方法について説明します。

operator は、どちらもデフォルトで無効になっている 2 つのレベルで Kubernetes の `NetworkPolicy` リソースを管理します。

* **クラスターポリシー** — `ClickHouseCluster` および `KeeperCluster` リソースの内部トラフィックを対象とするクラスターごとのポリシーで、各カスタムリソースの `spec.networkPolicy` で有効化します。
* **operator ポッドポリシー** — メトリクスおよび webhook エンドポイントへのイングレスを controller manager ポッド自体に対して制限する、チャート に含まれるポリシーです。

<Note>
  `NetworkPolicy` は、クラスターの CNI プラグインがこれを実装している場合にのみ適用されます
  (たとえば Calico や Cilium) 。NetworkPolicy を適用しない CNI では、これらの
  リソースは作成されても実際には効果がなく、Kubernetes も
  エラーを返しません。これらに依存する前に、使用中の CNI がポリシーを適用することを確認してください。
</Note>

<div id="cluster-network-policies">
  ## クラスターのNetworkPolicy
</div>

クラスターごとにマネージドポリシーを有効にします。

```yaml theme={null}
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
spec:
  networkPolicy:
    policy: Enabled
---
apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
spec:
  networkPolicy:
    policy: Enabled
```

管理対象のポリシーは、**クラスター内部のトラフィックのみ**を対象とします。ポッドを選択すると、
イングレスはデフォルト拒否となり、operator はクラスターの動作に必要な通信のみを許可します。

| クラスター      | 許可される送信元                                                      | 許可されるポート                                      |
| ---------- | ------------------------------------------------------------- | --------------------------------------------- |
| ClickHouse | クラスター自身のポッド                                                   | `9009` (interserver) 、`9001` (management)     |
| ClickHouse | Operator ポッド (ラベル `clickhouse.com/role: operator`、任意のネームスペース) | `9001`、`9002` (management)                    |
| Keeper     | クラスター自身のポッド                                                   | `9234` (Raft)                                 |
| Keeper     | Operator ポッドおよびこの Keeper を参照するすべての `ClickHouseCluster`        | `2181`、`2281` (client) 、`9123` (HTTP control) |

Keeper は `keeperClusterRef` に基づいて ClickHouse クラスターを許可します。参照を
追加または削除すると、他のネームスペースからの参照も含めて、Keeper のポリシーが
自動的に更新されます。

<div id="allowing-clients">
  ### クライアントと監視の許可
</div>

クライアント接続とメトリクスのスクレイプは**対象に含まれません**。managed
ポリシー を有効にすると、許可するまでクライアントポート (`9000`/`8123`、または TLS
バリアント) やメトリクスポートに到達できなくなります。NetworkPolicy は加算的に適用されるため、
managed ポリシー と併せて独自の ポリシー でアクセスを許可します。

```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` ラベルが
付与されている場合を除き、operator が変更することはありません。

<div id="np-cluster-wide-disable">
  ### クラスター全体での無効化
</div>

NetworkPolicy の管理は、operator's
`ENABLE_NETWORK_POLICY` 環境変数により、クラスター全体で無効にすることもできます。`ENABLE_NETWORK_POLICY=false` の場合、
operator は `spec.networkPolicy.policy` の設定にかかわらず、**すべての** ClickHouseCluster および KeeperCluster に対する
NetworkPolicy のリコンサイルをスキップし、`NetworkPolicy` リソースを**一切監視しません**。そのため、operator's
ServiceAccount には `networkpolicies.networking.k8s.io` に対する RBAC 権限は不要です。これは、これらの権限を意図的に付与していない
制限付き ServiceAccount で operator を実行する場合に有用です。

```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">
  ## Operator ポッドポリシー
</div>

チャート には、**controller manager ポッド**、つまり operator プロセス自体に到達できるトラフィックを制限するための任意のポリシーも含まれています。これらは、operator が他のクライアント向けに公開している 2 つのポート、メトリクスエンドポイントと admission webhook を対象とします。

<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]` のみを指定します。これらは operator からの外向きトラフィックを制限せず、
ClickHouse server や Keeper のポッドにも影響しません。

<div id="default-deny">
  ## デフォルト拒否の動作
</div>

イングレス `NetworkPolicy` でポッドを選択すると、そのポッドは**イングレスに対する
デフォルト拒否**に切り替わります。いずれかのポリシーが適用されると、明示的に許可されていない
controller manager ポッドへの受信トラフィックはすべて破棄されます。有効化後、
operator に到達できるイングレスは次のみです。

* `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` (
既定値) も追加で必要になるため、webhook を無効にすると、そのポリシーも削除されます。

raw の `kubectl` manifest を使用する場合は、
[kubectl install guide](/ja/products/kubernetes-operator/install/kubectl) で説明されているとおり、`[NETWORK POLICY]` セクションのコメントを外してください。
raw の manifest にも、同じ 2 つのポリシーが含まれています。

<div id="labeling-namespaces">
  ## クライアントのネームスペースへのラベル付け
</div>

どちらのポリシーも `namespaceSelector` によって送信元のネームスペースを照合するため、operator に到達する必要があるすべてのネームスペースには、対応するラベルが付いている必要があります。ラベルの付いていないネームスペースからの スクレイプ や webhook 呼び出しは破棄されます。

```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
```

これを
[監視 → メトリクス エンドポイントの保護](/ja/products/kubernetes-operator/guides/monitoring#securing-the-metrics-endpoint)
で説明しているメトリクス RBAC と組み合わせてください。
到達可否は NetworkPolicy が制御し、認可はクラスター ロール バインディングが制御します。
保護されたスクレイプを成功させるには、この両方が必要です。

<Warning>
  admission webhook へのリクエストは、通常の
  ポッドではなく Kubernetes API server から送信されます。そのトラフィックが
  `NetworkPolicy` の対象になるかどうか、またどの送信元として見えるかは、
  control plane のトポロジーと CNI に依存します。
  特にマネージド control plane では、どの `namespaceSelector` にも一致しないアドレスから
  webhook に到達することがあります。Kubernetes API server のトラフィックが
  `webhook: enabled` のネームスペースでカバーされていない場合、
  `allow-webhook-traffic` を有効にすると
  admission がブロックされ、`ClickHouseCluster`/`KeeperCluster` の作成および更新リクエストが
  タイムアウトする可能性があります。有効化後は非本番クラスターで admission をテストし、必要に応じて
  Kubernetes 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 を通過すること (webhook
  に到達できること) 。

スクレイプしてもデータが返らない場合や、CR の適用がハングする場合は、対象ネームスペースにラベルが付いていないこと、または
上記の API サーバー到達性に関する注意事項が原因である可能性が最も高いです。

<div id="related-guides">
  ## 関連ガイド
</div>

* [operator の監視](/ja/products/kubernetes-operator/guides/monitoring) — メトリクス エンドポイント、その RBAC、スクレイプの保護について説明します。
* [kubectl を使用したインストール](/ja/products/kubernetes-operator/install/kubectl) — ネットワークポリシーのセクションをどこでアンコメントするかを説明します。
* [Helm を使用したインストール](/ja/products/kubernetes-operator/install/helm) — operator に関連する chart の values。