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

Posted at 2025-06-03

この記事は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. 前提条件

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

2. テナント Namespace の作成

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

# 例: コンシューマ側（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)

3. Networking（WireGuard Fabric）

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

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

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

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 で登録（下記ラベル必須）。

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)

4. Authentication

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

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

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 側）

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

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

4-3. Consumer 側 Secret

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)

5. Resource Negotiation & Offloading

5-1. `ResourceSlice`（Consumer 側）

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)

5-2. `NamespaceOffloading`

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)

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` になっているか 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)

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up