AWS Builder Center

Amazon EKS Capability for Argo CD Now Supports Custom Configuration

You can now tune custom health checks, UI settings, and resource-watching behavior for the EKS Capability for Argo CD through the standard argocd-cm ConfigMap. This post covers the sync wave issue this solves, along with concrete setup steps and things to watch for before adopting it.

Introduction

On August 21, 2026, AWS announced that the Amazon EKS Capability for Argo CD now supports custom configuration through the argocd-cm ConfigMap. The key highlight is that you can now tune this managed GitOps environment to fit your team's workflow, using the same configuration approach as standard Argo CD.
Teams running the EKS Capability for Argo CD have run into cases where health checks for Custom Resources didn't behave as expected, which could affect how sync waves progressed. This update addresses that gap directly.
This post walks through what changed, where it's useful, and how to configure it. It's aimed at infrastructure and platform engineers running the Argo CD Capability on EKS, and at anyone evaluating a GitOps setup on EKS.

What Changed

You may not have thought much about how Argo CD determines the health of your Custom Resources. Argo CD has built-in health logic for standard Kubernetes resources such as Deployments and Services, but it has no such logic for Custom Resources defined by CRDs — without configuration, no health status is reported for them at all.

Before
Now
Health checks for Custom Resources
No health logic; excluded from the Application's overall health
Custom health logic can be defined with a Lua script in argocd-cm
UI banner and display settings
Fixed by the managed environment
Freely customizable via ui.bannercontent and related settings
Resource watch/diff behavior
Determined by the managed environment's defaults
Adjustable through resource.customizations settings
Configuration method
No way to apply custom configuration
The same argocd-cm ConfigMap used in upstream Argo CD

The Underlying Problem

When a Custom Resource has no health check, Argo CD reports no health for it and excludes it from the Application's overall health. As a result, an Application can report Healthy even while its resources are still provisioning or have failed. Because sync wave progression depends on reported health, this apparent "Healthy" status could let a later sync wave advance before the resources in an earlier wave were actually ready.

How argocd-cm Solves It

With this update, you can shape the managed capability's behavior through the standard argocd-cm ConfigMap. Supported settings fall into three broad categories.
Category
Example settings
Purpose
User interface
ui.bannercontent, ui.bannerurl, and others
Customize the UI banner and styling
Resource settings
resource.customizations.health.<group>_<kind>, resource.compareoptions, and others
Define custom health checks and adjust diff behavior
Repository and tool settings
kustomize.buildOptions, helm.enable, and others
Control the manifest rendering tools Argo CD uses
The setting with the biggest impact is resource.customizations.health.<group>_<kind>. Writing a Lua script under this key lets you return one of Healthy, Progressing, Degraded, or Suspended for a given Custom Resource type, based on your own logic. On top of that, AWS Controllers for Kubernetes (ACK) and kro (Kube Resource Orchestrator) resources now come with built-in health checks that work out of the box, with no extra configuration required.
Because these settings use the same keys and format as upstream Argo CD, your existing knowledge and community example scripts carry over without modification. You can configure this in any AWS Region where the EKS Capability for Argo CD is available.

Use Cases

With the above in mind, here are a few concrete scenarios where this feature helps.

Waiting Safely for Database Provisioning

If you manage database resources such as RDS for PostgreSQL or DynamoDB through AWS Controllers for Kubernetes (ACK), a custom health check can hold an Application at Progressing until the database is fully Ready. That keeps application Pods from starting — and crashing on connection errors — before the database is actually reachable.

Enforcing Deployment Order Across Layers

For deployments that follow an order such as infrastructure (Namespaces, RBAC, NetworkPolicies), then middleware (databases, caches), then application workloads, setting appropriate health checks on the Custom Resources in each layer lets sync waves guarantee that one layer is fully ready before the next one starts deploying.

Communicating Across Teams Sharing a Cluster

Displaying maintenance windows or important deployment notices through ui.bannercontent in the Argo CD UI makes it easier to avoid accidental simultaneous deployments or missed configuration changes when multiple teams share the same cluster.

Setup Guide

Prerequisites

Before you begin, make sure you have:
  • An EKS cluster with the Argo CD Capability already created
  • The kubectl CLI configured to communicate with your cluster
  • The Argo CD namespace you set when creating the Capability (argocd by default)

Create the ConfigMap

Custom settings are applied through a ConfigMap named argocd-cm. Keep the following in mind when you create it:
  • Name it argocd-cm
  • Create it in the Argo CD namespace for your Capability (argocd by default)
  • Apply the app.kubernetes.io/part-of: argocd label — this is required, just as it is in upstream Argo CD
  • Use the same keys and format as upstream Argo CD
A ConfigMap is not a secure store. Don't put secrets, credentials, or other sensitive information in argocd-cm.

Set a UI Banner

As a simple first example, here's a setting that displays a banner across the top of the UI.
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
ui.bannercontent: "Production cluster"

You can add other supported settings under data the same way, in the same ConfigMap.

Define a Custom Health Check

Next, here's an example that defines a health check for a Custom Resource. The key follows the format resource.customizations.health.<group>_<kind>, and the value is a Lua script.
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

The Lua script accesses the target resource through the global obj variable. It must return a table with a status field set to one of Healthy, Progressing, Degraded, or Suspended, and can optionally include a message field with a descriptive status.

How This Works Under the Hood

Custom health check scripts run in fully managed compute that's isolated from your cluster. This execution environment is isolated per Capability and has no access to your cluster's data or to AWS APIs — you don't need to provision, patch, or operate any part of it.
One thing to watch for: standard Lua libraries aren't available. The useOpenLibs option is always disabled, which matches the default behavior in upstream Argo CD, so scripts can't access the filesystem or OS. If you're porting a script from a self-managed Argo CD environment that relies on standard libraries, it may not behave the same way here — test it in a development environment before relying on it in production.

Verify the Configuration

After creating or updating the ConfigMap, confirm it's taking effect.
In the Argo CD UI, open an Application that includes a Custom Resource you defined a health check for, and check whether it shows the health status your script returns. From the CLI, you can check the same thing with:
argocd app get <application-name>

If the resource isn't reporting the health you expect, check the following in order:
  • The ConfigMap is named argocd-cm and lives in the Argo CD namespace for your Capability
  • The app.kubernetes.io/part-of: argocd label is present
  • The health check key matches the resource's <group>_<kind>

Before You Get Started

Supported Settings Are a Subset of Upstream Argo CD

The EKS Capability for Argo CD supports only a subset of the settings and features available in upstream Argo CD. If you set an unsupported key in argocd-cm, it's silently ignored rather than causing an error — which makes it easy to miss when a setting you configured isn't actually taking effect. It's worth checking the list of supported keys before you configure something.
The same applies to values: if you set an invalid or malformed value, the Capability ignores it and keeps running with the default configuration for that setting. A mistake in your ConfigMap won't break your managed Argo CD instance, but it's still worth getting into the habit of confirming through the UI or CLI that your settings are actually reflected.

Built-in Health Checks for ACK and kro Can Be Overridden

ACK and kro resources come with built-in health checks. If you define a custom health check for the same resource type using the resource.customizations.health.<group>_<kind> key, it overrides the built-in one. If the built-in check already meets your needs, be careful not to override it unintentionally.

When Health Evaluation Is Temporarily Unavailable

If Lua-based health evaluation is temporarily unavailable for some reason, affected Custom Resources are reported as Progressing rather than losing their health status entirely. This keeps them visible in the Application's health until evaluation recovers.

Restrict Write Access to argocd-cm

Changes to argocd-cm are governed by your cluster's Kubernetes RBAC, not by IAM permissions. In other words, anyone with write access to this ConfigMap can change how your managed Argo CD instance behaves. We recommend limiting permission to modify objects in the Argo CD namespace to trusted users and service accounts. Since Kubernetes RBAC scopes permissions by resource type, you can still grant developers the access they need — for example, letting them create and manage Applications while withholding permission to modify ConfigMaps.

Summary

The Amazon EKS Capability for Argo CD now supports custom configuration through the argocd-cm ConfigMap. The core of this update is that health checks, UI settings, and resource-watching behavior — previously a black box — can now be tuned to fit your operations, using the same conventions as upstream Argo CD.
There are a few things worth keeping in mind during operation, such as the subset of supported settings and managing write access to the ConfigMap, but since your existing Argo CD knowledge and scripts carry over directly, the barrier to adoption is low. A good place to start is a low-risk setting like the UI banner, then move on to custom health checks as needed.

References

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article