Cattage 入門：Argo CD マルチテナント運用を Accurate と連携して自動化するサイボウズ製 OSS

記事のサマリー（TL;DR）

サイボウズ製 OSS「Cattage」は、Accurate の Namespace 管理と Argo CD の AppProject 設定を自動で同期し、テナントがクラスタ管理者を介さずデプロイできる状態を実現
Tenant CR によるシャーディング管理で、単一クラスタのソフトマルチテナンシー環境でも application-controller の負荷をテナント単位に分散可能
独自の SyncWindow CR により、テナントユーザーが AppProject を直接変更せずに同期ウィンドウを柔軟に設定できる

Kubernetes マルチテナント基盤を内製する国内企業への示唆

サイボウズの Cattage が解く問題は「Namespace を増やしたら Argo CD の設定も誰かが直さなければならない」という運用上の摩擦です。この摩擦は、複数プロダクトチームが1つの Kubernetes クラスタを共有する国内企業であれば規模を問わず発生します。

Cattage は GitHub で Apache 2.0 ライセンスのもと公開されており、Accurate との組み合わせを前提とした設計です。自社の Kubernetes 基盤に Argo CD を採用し、ソフトマルチテナンシーで運用している組織であれば、導入検討の余地があります。

kintone や Salesforce などの SaaS 上に独自 UI を構築している場合でも、その裏側のデプロイ基盤が Kubernetes + Argo CD であれば、テナント分離の自動化という観点で参考になる設計パターンです。

Cattage 自体は「汎用ツールではない」とサイボウズが明記しているため、Accurate を未導入の環境への適用は難しい点に注意が必要です。まず Accurate による Namespace 階層管理を整備することが前提条件になります。

詳細

サイボウズの Kubernetes クラスタとマルチテナンシー

サイボウズでは、1つの Kubernetes クラスタを複数のテナント（クラスタリソースへのアクセス権を持つ開発チームの集まり）で共有しています。マルチテナンシーには大きく2種類があります。

ソフトマルチテナンシー: 1つのクラスタを共有し、Namespace / RBAC / NetworkPolicy / ResourceQuota / Pod Security などで論理的に隔離する方式
ハードマルチテナンシー: クラスタや Control Plane を分離し（クラスタ単位の分割、kube-apiserver 等の仮想クラスタ、専用ノード/ネットワーク）、強い境界を持たせる方式

サイボウズはソフトマルチテナンシーを採用しています。

Argo CD の役割

サイボウズの Kubernetes 基盤では、Argo CD が標準的なデプロイツールとして使われています。Argo CD は Kubernetes 向け GitOps ツールであり、Git リポジトリに保存されたマニフェストファイルと Kubernetes クラスタの状態を継続的に同期し、宣言的な設定管理を実現します。

サイボウズでは Argo CD の AppProject を用いて、各テナントごとにアプリケーションのアクセス制御やリソース制限などを一括管理しています。

Accurate：Cattage の前提となるコントローラー

Cattage のメリットを享受するには、まず Accurate というコントローラーの導入が必要です。Accurate は、サイボウズが開発・OSSとして公開している Kubernetes コントローラーです。

Accurate の主な機能は「Namespace に親子関係を持たせ、親の Namespace から子の Namespace へリソース・ラベル・アノテーションを継承・伝播させること」です。

サイボウズでは Accurate を利用することで、クラスタ管理者の介在なしにテナントユーザー自身が Namespace を管理できる状態を実現しています。クラスタ管理者は各プロダクトチームやサービス単位で親の Namespace を割り当てており、その下であればチームが自分たちで子 Namespace を作成・削除できます。

本記事で登場する独自用語

用語	説明
Root Namespace	`accurate.cybozu.com/type=root` ラベルを付けた Namespace。Accurate における Namespace ツリーの起点
SubNamespace CR	子 Namespace の作成・削除を宣言する Accurate のカスタムリソース。親 Namespace 内に作成する
親 Namespace	子 Namespace から親として参照されている Namespace。SubNamespace CR が置かれる
子 Namespace	`accurate.cybozu.com/parent=<親Namespace名>` ラベルを持つ Namespace。親のラベル・Annotation・RoleBinding などが伝播される

Cattage とは

Cattage は、サイボウズが開発した「Accurate を使用して Argo CD のマルチテナンシーを強化する Kubernetes コントローラー」です。主な機能は以下の通りです。

テナントチームが Namespace を管理できるように設定する機能
Argo CD AppProject リソースの自動更新機能
Accurate の子 Namespace 所有権変更に伴う Argo CD 設定の自動更新
テナント単位でのシャーディング管理
任意作成可能な SyncWindow カスタムリソースの提供

生まれた背景：Accurate と Argo CD の間にある「隙間」

Accurate は Kubernetes 上の権限分離を担いますが、Argo CD の権限分離まで自動で行う機能はありません。テナントが自由に Namespace を作成できても、その Namespace に Argo CD でデプロイできるようになるわけではないのです。

Argo CD では、テナントが使用できる Namespace やリポジトリを AppProject で明示的に定義する必要があります。Namespace を新規作成しただけでは AppProject の設定は自動で更新されません。

そのため従来は「Namespace を作ったらクラスタ管理者に Argo CD の設定変更も依頼する」というワンクッションが必要でした。これが双方にとって大きな手間となっていました。

Cattage は、Kubernetes の Namespace 作成・削除に連動して Argo CD の設定を自動更新することで、この依頼ステップをなくします。

Cattage の基本機能

Tenant CR による Root Namespace とテナントの紐付け管理

Cattage は Tenant というカスタムリソースを持ちます。「どの Root Namespace がどのテナントに属するか」「そのテナントが Argo CD 上でどの Namespace にデプロイでき、どのリポジトリを参照できるか」という設定を結びつけるための定義です。

Tenant CR を作成すると、Cattage は以下を自動で作成・更新します。

Tenant で指定された Root Namespace
テナント向けの AppProject
各 Root Namespace に配置するテナント用の RoleBinding

これにより、テナントは Argo CD 側の設定を手動で調整せずに、自身の親 Namespace および子 Namespace への admin 権限を取得できます。

apiVersion: cattage.cybozu.io/v1beta1
kind: Tenant
metadata:
  name: tenant-name
spec:
  argocd:
    repositories:
      - https://github.com/org/tenant-repo
  rootNamespaces:
    - name: root-tenant-namespaces
      labels:
        team: tenant-name

動作フローは以下の通りです。

テナントユーザーが SubNamespace リソースを作成・削除すると、Accurate が対応する子 Namespace を増減させる
Cattage は Namespace / RoleBinding / AppProject などの変更を監視しており、Namespace の作成・更新・削除イベントを検知すると cattage.cybozu.io/tenant ラベルから関連する Tenant を特定する
同じ tenant ラベルを持つ Namespace を取得し、AppProject の destinations や sourceNamespaces などを更新する
テナントは手動で Argo CD 側の設定を操作することなく、作成した Namespace にすぐアプリケーションをデプロイできる状態になる

Accurate の子 Namespace 所有権変更に伴う Argo CD 設定の自動更新

チーム統合やプロダクト移管のタイミングで、アプリケーションの所有権を別のテナントに移行するケースがあります。サイボウズでは実際にこのような場面が発生しています。

この場合の動作は以下の通りです。

クラスタ管理者が子 Namespace の親を変更する
Accurate が parent ラベルを変更し、tenant ラベルと伝播リソースを更新する
Namespace の更新イベントを受けた Cattage が、移管元 Tenant と移管先 Tenant をそれぞれ再調整する
現在の所属 Namespace 一覧から各 AppProject を再生成し、移管元の AppProject から子 Namespace が除外され、移管先の AppProject へ追加される

テナント単位でのシャーディング管理

Argo CD では、管理対象の Application リソースや同期対象リソースが増えるにつれて application-controller にかかる負荷が顕著になります。

Argo CD には application-controller のシャーディング機能があり、割当方法として「デプロイ先クラスタ単位」や「Applications in Any Namespace を使った Namespace 単位」などが存在します。しかしソフトマルチテナンシー環境でデプロイ先クラスタが実質1つの場合、クラスタ単位のシャーディングだけでは負荷分散が不十分になるケースがあります。

サイボウズでは Namespace 単位のシャーディングを利用しており、Cattage はさらに Tenant CR の spec.controllerName に「どのシャードに属するか」を記述することで、テナント単位での application-controller 分散を実現しています。

これにより、同一クラスタ内でも特定テナントの同期処理が重くなっても他テナントの同期に影響しにくくなります。

任意作成可能な SyncWindow CR の提供

Argo CD には特定の時間帯においてアプリケーションの同期を制限する Sync Windows 機能があります。ただし Sync Windows の設定には AppProject リソースの変更が必要であり、マルチテナント環境ではテナントユーザーが自由に設定できません（AppProject の変更は管理権限と同義のため）。

この問題は Argo CD の公式 Issues（Issue #11755「Introduce sync windows as a CRD」）でも報告されている既知の課題です。

夜間バッチやメンテナンス対応の都合でテナントごとに同期の可否を柔軟に切り替えたい場面は実運用では頻繁に発生します。そのたびにクラスタ管理者へ AppProject の変更を依頼する運用では、変更までのリードタイムが伸び、テナントの自律性も損なわれます。

Cattage は SyncWindow カスタムリソースを提供することでこの問題を解決しています。テナントユーザーが権限を持つ Namespace 内に SyncWindow リソースを作成すると、Cattage がそのテナントに紐づく AppProject の syncWindows フィールドを自動設定します。同一テナント内で複数の SyncWindow リソースが作成された場合、それらは統合されて AppProject に反映されます。

apiVersion: cattage.cybozu.io/v1beta1
kind: SyncWindow
metadata:
  name: syncwindow-sample
  namespace: tenant-namespace
spec:
  syncWindows:
    - kind: deny
      schedule: "0 22 * * *"
      duration: 1h
      namespaces:
        - default

まとめ

Cattage は汎用的なツールではありませんが、ソフトマルチテナンシーという運用方針のもとで Accurate と Argo CD の間にあった運用上の隙間を埋めるコントローラーです。Namespace 管理・AppProject 自動更新・シャーディング・SyncWindow の自律設定という4つの機能が組み合わさることで、クラスタ管理者への依頼工数を大幅に削減し、テナントの自律的なデプロイ運用を支えています。

Cattage は Apache 2.0 ライセンスのもと GitHub で公開されており、同じように Argo CD のマルチテナント運用に課題を抱えている組織にとって参考になる実装例です。