Liqo v1のCustomResourceでの宣言的なクラスタ接続

この記事はAIによって作成されています。

### Liqo v1.0.0 — Declarative Peering（CR ベース）の総合ガイド

Liqo 1.0 からは「Declarative Peering」が正式にサポートされ、`ForeignCluster` などの CR（Custom Resource）を GitOps-フレンドリに配置するだけでクラスタ間ピアリングを自動確立できます。以下では **Networking／Authentication／Offloading** の 3 モジュールを対象に、最小構成から応用までを日本語でまとめます。([docs.liqo.io][1])

---

## 1. 前提条件

| 項目         | 内容                                                                            |
| ---------- | ----------------------------------------------------------------------------- |
| Liqo 版数    | **v1.0.0**（`liqoctl version` で確認）                                             |
| Kubernetes | 1.24 以降を推奨                                                                    |
| アクセス       | 各クラスタの `kubeconfig` と **Cluster ID**<br/>（`liqoctl info --get clusterid` で取得） |
| CNI        | WireGuard トンネルを張れるネットワーク到達性                                                   |
| GitOps     | Argo CD / Flux などは任意                                                          |

---

## 2. テナント Namespace の作成

ピアごとに *tenant* 用 Namespace を両クラスタに用意し、以下 2 ラベルを必ず付与します。

```yaml
# 例: コンシューマ側（provider を指す）
apiVersion: v1
kind: Namespace
metadata:
  name: liqo-tenant-cl-provider           # 任意
  labels:
    liqo.io/remote-cluster-id: cl-provider
    liqo.io/tenant-namespace: "true"
```

*同名にする必要はありません。* すべての CR はこの Namespace 内に置きます。([docs.liqo.io][1])

---

## 3. Networking（WireGuard Fabric）

### 3-1. CIDR 交換用 `Configuration` CR

* クラスタ A には *B の* PodCIDR / ExternalCIDR を、クラスタ B には *A の* 情報を登録。
* CR は `networks.ipam.liqo.io/v1beta1` グループ。

### 3-2. 鍵ペア生成と配布

```bash
openssl genpkey -algorithm X25519 -outform der -out private.der
openssl pkey    -inform der -in  private.der -pubout -outform der -out public.der
```

* `privateKey` / `publicKey` を Base64 化し、各クラスタの tenant NS に Secret `gw-keys` を配置。
* 相手クラスタの公開鍵を `PublicKey` CR で登録（下記ラベル必須）。

```yaml
labels:
  liqo.io/remote-cluster-id: <PEER_ID>
  networking.liqo.io/gateway-resource: "true"
```

### 3-3. Gateway 構成

| 役割       | CR              | 主な項目                                      |
| -------- | --------------- | ----------------------------------------- |
| Provider | `GatewayServer` | `endpoint.port / serviceType / secretRef` |
| Consumer | `GatewayClient` | `endpoint.addresses[] / port / secretRef` |

UDP `NodePort` / `LoadBalancer` どちらでも可。接続確認は `Connection` CR の `status.phase=Connected` を参照。([docs.liqo.io][1])

---

## 4. Authentication

### 4-1. Provider → Consumer への権限付与

1. Provider クラスタで **クライアント証明書**または ServiceAccount Token を発行
2. 発行した主体に tenant NS 内で `RoleBinding` → ClusterRole `liqo-remote-controlplane` を割当

```yaml
kind: RoleBinding
metadata:
  name: liqo-binding-liqo-remote-controlplane
  namespace: <PROVIDER_TENANT_NS>
roleRef:
  kind: ClusterRole
  name: liqo-remote-controlplane
subjects:
- kind: User          # 証明書の場合
  name: <CN>
```

### 4-2. `Tenant` CR（Provider 側）

```yaml
apiVersion: authentication.liqo.io/v1beta1
kind: Tenant
metadata:
  name: <任意>
spec:
  clusterID: <CONSUMER_ID>
  authzPolicy: TolerateNoHandshake   # Declarative 構成では必須
  tenantCondition: Active
```

`authzPolicy=TolerateNoHandshake` によりハンドシェイクなしでリソース要求を受理。

### 4-3. Consumer 側 Secret

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: cplane-secret
  labels:
    liqo.io/identity-type: ControlPlane
    liqo.io/remote-cluster-id: <PROVIDER_ID>
  annotations:
    liqo.io/remote-tenant-namespace: <PROVIDER_TENANT_NS>
data:
  kubeconfig: <BASE64_ENCODED_KUBECONFIG>
```

作成後、`liqo-crd-replicator` のログに *Starting reflection* が出れば OK。([docs.liqo.io][1])

---

## 5. Resource Negotiation & Offloading

### 5-1. `ResourceSlice`（Consumer 側）

```yaml
apiVersion: authentication.liqo.io/v1beta1
kind: ResourceSlice
metadata:
  annotations:
    liqo.io/create-virtual-node: "true"
  labels:
    liqo.io/remote-cluster-id: <PROVIDER_ID>
spec:
  class: default
  providerClusterID: <PROVIDER_ID>
  resources:
    cpu: "20"
    memory: 128Gi
```

Provider が受理すると Consumer Kubernetes に **Virtual Node** が追加され、そのリソース量がスケジューラに広告されます。([docs.liqo.io][1])

### 5-2. `NamespaceOffloading`

```yaml
apiVersion: offloading.liqo.io/v1beta1
kind: NamespaceOffloading
metadata:
  name: offloading
  namespace: demo        # オフロード対象 NS
spec:
  clusterSelector: {}    # 全 Virtual Node を対象
  namespaceMappingStrategy: DefaultName
  podOffloadingStrategy: LocalAndRemote
```

* **必ず Pod 作成前** に設定。後から置くと `Pending` から抜けません。
* `podOffloadingStrategy` を `Remote` にすると強制的にリモート実行可。([docs.liqo.io][1])

---

## 6. ピアリングの更新・解除

| 操作 | 方法                                                                                                                   |
| -- | -------------------------------------------------------------------------------------------------------------------- |
| 解除 | `kubectl delete` で `Gateway*`, `PublicKey`, `ResourceSlice` など関連 CR を削除（順不同で OK）。`Tenant` を `Cordoned` へ変更すれば一時停止も可。 |
| 更新 | CR スペックを GitOps ツール経由で上書き。たとえば `ResourceSlice.resources` を変更すると、自動で Virtual Node キャパシティが再計算される。                      |

---

## 7. GitOps 運用のヒント

* すべての CR を **tenant NS 配下のディレクトリ**にまとめ、`kustomize` でクラスタ固有値（CIDR, WireGuard Key, IP など）をパッチ。
* Argo CD の `SyncWave` を使い、**Namespace → Secret / PublicKey → Gateway → Tenant → ResourceSlice** の順に同期すると安全。

---

## 8. トラブルシューティング

| 症状                     | チェック項目                                                          |
| ---------------------- | --------------------------------------------------------------- |
| `Connection` が `Error` | UDP ポート開放／WireGuard 鍵一致                                         |
| Virtual Node が現れない     | `ResourceSlice` が `Accepted` になっているか<br/>Provider 側 `Tenant` 状態 |
| Pod が `Pending`        | 該当 Namespace に `NamespaceOffloading` があるか                       |
| CRD 反映されない             | `liqo-crd-replicator` Pod ログを確認                                 |

---

## 9. まとめ

Declarative Peering を使うことで **完全 GitOps** でのマルチクラスタ運用が可能になります。WireGuard Fabric の鍵交換と `Tenant` CR の `authzPolicy` 設定さえ押さえれば、Liqo 1.0 以降は手動 CLI 操作を一切挟まずに
*接続 → 認証 → リソース共有 → オフロード*
のライフサイクルを自動化できます。([docs.liqo.io][1])

[1]: https://docs.liqo.io/en/stable/advanced/peering/peering-via-cr.html?utm_source=chatgpt.com "Declarative peering - Liqo"