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: v1kind: ConfigMapmetadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: 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: v1kind: ConfigMapmetadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: 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
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article