はじめに
2026 年 8 月 21 日、AWS は Amazon EKS Capability for Argo CD に対して、argocd-cm ConfigMap によるカスタム設定のサポートを発表しました。標準的な Argo CD の設定作法のまま、マネージドな GitOps 環境をチームのワークフローに合わせて調整できるようになったことが大きな特徴です。
EKS Capability for Argo CD の運用では、カスタムリソースのヘルス判定がうまくいかず、sync wave の進行に影響が出るケースがありました。今回のアップデートは、この課題に直接応えるものです。
本記事では、何が変わったのか、どのような場面で役立つのか、そして実際にどう設定すればよいのかを中心に解説します。EKS 上で Argo CD Capability を運用しているインフラ・プラットフォームエンジニアの方や、GitOps 環境の構築を検討している方を想定読者としています。
何が変わったのか
Argo CD がカスタムリソースのヘルスをどう判定しているか、意識したことがない方も多いかもしれません。実は Argo CD は、Deployment や Service といった標準の Kubernetes リソースには組み込みのヘルスロジックを持っていますが、CRD 由来のカスタムリソースについては判定ロジックを持っておらず、何も設定しなければヘルス状態そのものが報告されません。
| 項目 | 従来 | 今回 |
|---|---|---|
| カスタムリソースのヘルス判定 | 判定ロジックがなく、Application 全体のヘルス判定から除外される | argocd-cm に Lua スクリプトを書けば独自のヘルスロジックを定義できる |
| UI バナーなどの表示調整 | マネージド環境側の設定に固定 | ui.bannercontent 等で自由にカスタマイズ可能 |
| リソースの監視・比較方法 | マネージド環境のデフォルト設定に依存 | resource.customizations 系のキーで調整可能 |
| 設定方法 | カスタム設定を行う手段がなかった | アップストリームの Argo CD と同じ argocd-cm ConfigMap |
従来の課題
カスタムリソースにヘルスチェックが定義されていない場合、Argo CD はそのリソースを「ヘルスなし」として扱い、Application 全体のヘルス判定の対象から除外します。この結果、リソースがまだプロビジョニング中や失敗していても、Application は Healthy と表示されてしまうことがあります。sync wave の進行はリソースのヘルス状態をもとに制御されるため、この見かけ上の Healthy によって、後続 wave のリソースが前段の準備完了を待たずにデプロイされてしまうリスクがありました。
argocd-cm による解決
今回のアップデートでは、標準の argocd-cm ConfigMap を使って、マネージド環境の挙動を調整できるようになりました。対応する設定は大きく 3 つのカテゴリに分かれます。
| カテゴリ | 主な設定例 | 用途 |
|---|---|---|
| UI 設定 | ui.bannercontent, ui.bannerurl など | UI 上のバナー表示やスタイルのカスタマイズ |
| リソース設定 | resource.customizations.health.<group>_<kind>, resource.compareoptions など | カスタムヘルスチェック、diff の比較方法の調整 |
| リポジトリ・ツール設定 | kustomize.buildOptions, helm.enable など | マニフェストのレンダリングに使うツールの制御 |
中でも影響が大きいのが resource.customizations.health.<group>_<kind> です。ここに Lua スクリプトを書くことで、カスタムリソースごとに Healthy、Progressing、Degraded、Suspended のいずれかを自分のロジックで返せるようになります。さらに、AWS Controllers for Kubernetes（ACK）と kro（Kube Resource Orchestrator）のリソースについては、追加設定なしで動作する組み込みのヘルスチェックがあらかじめ用意されています。
設定方法はアップストリームの Argo CD と同一のため、既存の知識やコミュニティのサンプルスクリプトをそのまま活用できる点も見逃せません。EKS Capability for Argo CD が利用可能な全リージョンで、この設定を行えます。
活用シーン
ここまでの内容を踏まえて、実際にどのような場面でこの機能が活きるのか、具体的なシナリオで見ていきます。
データベースのプロビジョニングを安全に待つ
RDS for PostgreSQL や DynamoDB といったデータベースリソースを ACK で管理している場合、カスタムヘルスチェックを定義することで、データベースが完全に Ready になるまで Application を Progressing 状態に保持できます。これにより、データベース接続がまだ確立していない段階でアプリケーション Pod が起動し、接続エラーでクラッシュしてしまうといった事態を防ぎやすくなります。
複数レイヤーのデプロイ順序を守る
Namespace や RBAC、NetworkPolicy といったインフラ層、データベースやキャッシュなどのミドルウェア層、そしてアプリケーション層という順序でデプロイする構成では、各層のカスタムリソースに適切なヘルスチェックを設定することで、前段の層が完全に準備完了してから次の層のデプロイが始まることを sync wave の仕組みで保証できます。
複数チームが同一クラスターを使う環境でのコミュニケーション
メンテナンス予定や重要なデプロイ情報を ui.bannercontent で Argo CD の UI に表示しておけば、同じクラスターを複数チームが利用する環境でも、意図しない同時デプロイや設定変更の見落としを防ぎやすくなります。
有効化の手順
前提条件
以下が揃っていることを確認してください。
- Argo CD Capability を作成済みの EKS クラスター
- クラスターと通信できるように設定済みの kubectl CLI
- Capability の作成時に設定した Argo CD 用の namespace（デフォルトは argocd）
ConfigMap を作成する
カスタム設定は、argocd-cm という名前の ConfigMap を通じて反映されます。作成時には次の点に注意してください。
- 名前は argocd-cm にする
- Capability の Argo CD 用 namespace に作成する（デフォルトは argocd）
- app.kubernetes.io/part-of: argocd ラベルを必ず付与する（このラベルはアップストリームの Argo CD と同様に必須です）
- キーやフォーマットはアップストリームの Argo CD と同じものを使う
ConfigMap はセキュアなストアではありません。secrets や credentials、その他の機微情報は argocd-cm に含めないでください。
UI バナーを設定する
まずは単純な例として、UI 上部にバナーを表示する設定です。
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
ui.bannercontent: "Production cluster"
このように、data の下に対応キーを追加していく形で、他の設定も同じ ConfigMap にまとめて記述できます。
カスタムヘルスチェックを定義する
続いて、カスタムリソースのヘルスチェックを定義する例です。キーは resource.customizations.health.<group>_<kind> の形式で指定し、値には Lua スクリプトを記述します。
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
resource.customizations.health.example.com_Database: |
hs = {}
hs.status = "Progressing"
hs.message = "Waiting for the resource to become ready"
if obj.status ~= nil then
if obj.status.phase == "Ready" then
hs.status = "Healthy"
hs.message = "Database is ready"
end
end
return hs
Lua スクリプトは、グローバル変数 obj を通じて対象リソースのオブジェクトにアクセスできます。スクリプトは最終的に status フィールド（Healthy、Progressing、Degraded、Suspended のいずれか）を持つテーブルを返す必要があり、任意で message フィールドに状態の説明を添えられます。
動作の仕組み（補足）
カスタムヘルスチェックの Lua スクリプトは、クラスターとは分離された、フルマネージドな実行環境で動作します。この実行環境は Capability ごとに隔離されており、クラスターのデータや AWS API へはアクセスできません。実行環境自体の構築・パッチ適用・運用は不要です。
一点注意が必要なのは、標準の Lua ライブラリが利用できないことです。useOpenLibs オプションは常に無効化されており、これはアップストリームの Argo CD におけるデフォルトの挙動と同じです。そのため、スクリプトからファイルシステムや OS の機能にアクセスすることはできません。セルフマネージドの Argo CD 環境で動かしていたスクリプトを移植する場合、標準ライブラリに依存した処理があると同じようには動かない可能性があるため、事前に開発環境で動作確認しておくことをおすすめします。
設定を確認する
ConfigMap を作成・更新したら、以下の方法で反映されているかを確認します。
Argo CD の UI で、定義したカスタムリソースを含む Application を開き、スクリプトが返したヘルス状態が表示されているかを確認します。CLI から確認する場合は、次のコマンドで対象 Application のヘルス状態を確認できます。
argocd app get <application-name>
期待した状態が表示されない場合は、以下を順に確認してください。
- ConfigMap の名前が argocd-cm になっているか、Capability の Argo CD 用 namespace に配置されているか
- app.kubernetes.io/part-of: argocd ラベルが付与されているか
- ヘルスチェックのキーが対象リソースの <group>_<kind> と一致しているか
導入前に確認すべきこと
サポート範囲は upstream Argo CD の「サブセット」
EKS Capability for Argo CD がサポートするのは、アップストリームの Argo CD が持つ設定・機能のうち一部です。argocd-cm ConfigMap に、サポート対象外のキーを書いても、エラーにはならずに単に無視されます。「設定したつもりが反映されていない」という状態に気づきにくいため、対応キーは事前に確認してから設定することをおすすめします。
値についても同様で、不正な値や不正な形式の値を設定した場合、Capability はその値を無視し、そのキーについてはデフォルト設定のまま動作を続けます。ConfigMap の記述ミスによってマネージドな Argo CD インスタンス自体が壊れることはありませんが、設定が意図通りに反映されているかどうかは、都度 UI や CLI で確認する習慣を持つとよいでしょう。
ACK・kro の組み込みヘルスチェックは上書きされる
ACK や kro のリソースに用意されている組み込みのヘルスチェックは、同じリソース種別に対して resource.customizations.health.<group>_<kind> キーで独自のヘルスチェックを定義すると上書きされ、自分で定義したロジックに置き換わります。組み込みのヘルスチェックで十分な場合は、あえて同じキーで上書きしないよう注意してください。
ヘルス評価が一時的に利用できない場合
Lua スクリプトによるヘルス評価が何らかの理由で一時的に行えない場合、対象のカスタムリソースはヘルス情報が失われるのではなく、Progressing として報告されます。これにより、評価が復旧するまでの間も、対象リソースが Application のヘルス状態から見えなくなることはありません。
argocd-cm への書き込み権限を絞る
argocd-cm ConfigMap への設定反映は、IAM の権限ではなく、クラスターの Kubernetes RBAC によって制御されます。つまり、この ConfigMap に対する書き込み権限を持つ人であれば誰でも、マネージドな Argo CD インスタンスの挙動を変更できてしまいます。Argo CD の namespace 内のオブジェクトを変更できる権限は、信頼できるユーザーやサービスアカウントに限定することをおすすめします。Kubernetes RBAC はリソース種別ごとに権限を分けられるため、例えば開発者には Application の作成・管理権限のみを与え、ConfigMap の変更権限は与えない、といった運用も可能です。
まとめ
Amazon EKS Capability for Argo CD が、argocd-cm ConfigMap によるカスタム設定に対応しました。これまでブラックボックスだったヘルス判定や UI、リソース監視の挙動を、アップストリームの Argo CD と同じ作法で、自分たちの運用に合わせて調整できるようになった点が、今回のアップデートの本質です。
サブセット対応である点や、ConfigMap への書き込み権限の管理など、運用時に押さえておきたいポイントはいくつかありますが、既存の Argo CD の知識やスクリプトをそのまま活かせる設計になっているため、導入のハードルは高くありません。まずは UI バナーなど影響範囲の小さい設定から試し、必要に応じてカスタムヘルスチェックの導入を検討するとよいでしょう。