Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Configure Argo CD settings

The EKS Capability for Argo CD provides a fully managed Argo CD experience. Upstream Argo CD offers many optional settings and features, and the capability supports a subset of them. For general settings, use the argocd-cm ConfigMap. Use the argocd-cmd-params-cm ConfigMap to turn on the source hydrator with hydrator.enabled and configure additional Application and ApplicationSet source namespaces. The capability reads supported fields from these ConfigMaps in your cluster and applies them to the managed Argo CD instance.

Prerequisites

Before you configure Argo CD settings, you must have:

Configure the argocd-cm ConfigMap

To configure supported Argo CD settings, create a ConfigMap named argocd-cm in your cluster. The managed capability reads the supported settings from this ConfigMap and applies them to the managed Argo CD instance. For the settings that the capability supports and how it applies them, see Supported settings.

Create the ConfigMap with the following requirements:

The following example shows the ConfigMap structure, with a setting that displays a banner across the Argo CD UI. Add other supported settings under data in the same way.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
  labels:
    app.kubernetes.io/part-of: argocd
data:
  ui.bannercontent: "Production cluster"

How the capability applies your settings

You configure Argo CD by creating an argocd-cm ConfigMap in your own cluster. The capability applies the supported settings from your ConfigMap to the managed Argo CD instance. It applies only supported argocd-cm settings, and ignores any other field or feature that you set. Any argocd-cm setting that isn’t listed in Supported settings is unsupported and has no effect.

The capability validates the values that you set. If a value is invalid or malformed, the capability ignores that value and keeps running with its default configuration for that setting. A mistake in your ConfigMap doesn’t break your managed Argo CD instance.

Configure namespaces for Applications and ApplicationSets

The primary Argo CD namespace is the namespace value in the capability’s configuration.argoCd configuration. If you omit this value, EKS uses argocd. You can’t change the primary namespace after you create the capability. By default, the capability manages Application and ApplicationSet resources only in this namespace. You can enable additional namespaces for these resources.

Create an argocd-cmd-params-cm ConfigMap in the primary Argo CD namespace. This is a separate ConfigMap from the argocd-cm ConfigMap that you use for the settings in Supported settings. The following example enables both resource types in two team namespaces:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
  namespace: argocd
  labels:
    app.kubernetes.io/part-of: argocd
data:
  application.namespaces: "team-a-gitops,team-b-gitops"
  applicationsetcontroller.namespaces: "team-a-gitops,team-b-gitops"

The keys have the following effects:

The primary Argo CD namespace is always enabled, so don’t include it in either value. Each value is a comma-separated list with a maximum of 50 entries. An entry can be a Kubernetes namespace name or a shell-style glob pattern, such as team-*-gitops. Entries can contain lowercase letters, numbers, hyphens, and asterisks, and can be up to 63 characters long. An entry can’t start or end with a hyphen. Regular expressions aren’t supported. The capability ignores invalid and duplicate entries and literal entries for the primary namespace. You can’t use default, kube-node-lease, kube-public, or kube-system as resource namespaces. These Kubernetes system namespaces remain excluded when a glob pattern matches them. Use specific namespace names or narrow patterns so that a pattern doesn’t unintentionally include other namespaces.

To verify a namespace, wait up to 10 minutes after a configuration change. For an existing Application, run argocd app get <namespace>/<application-name>. For an existing ApplicationSet, run argocd appset get <namespace>/<applicationset-name>. A successful response confirms that Argo CD can access the resource in that namespace. If the ApplicationSet command returns namespace '<namespace>' is not permitted, the namespace isn’t effective. For Kubernetes status and controller log checks, see Application or ApplicationSet in an additional namespace isn’t reconciled.

ApplicationSets in additional namespaces don’t support the Plugin (plugin), Pull Request (pullRequest), or Source Code Management (SCM) Provider (scmProvider) generators. To use one of these generators, create the ApplicationSet in the primary Argo CD namespace.

The managed capability configures the required Kubernetes permissions and restarts the affected Argo CD components for you. Don’t apply the upstream Argo CD ClusterRole or ClusterRoleBinding manifests, and don’t restart managed workloads. If you remove a namespace from the ConfigMap, the capability stops managing Application or ApplicationSet resources in that namespace. However, it doesn’t delete those resources or their deployed workloads.

Supported settings

The following sections list the argocd-cm settings that the managed capability supports, grouped by category. Each setting uses the same key and format as upstream Argo CD. Each table’s How your value is applied column shows whether your value appends to or overrides the capability’s default configuration. For the full description of each setting, see the argocd-cm ConfigMap reference on the Argo CD documentation website.

User interface

These settings customize the Argo CD UI.

Resource settings

These settings control how the capability watches, compares, and displays the resources that Argo CD manages.

Repository and tool settings

These settings control the manifest tools that Argo CD uses to render your manifests.

Supported kustomize.buildOptions flags

For kustomize.buildOptions, the capability filters your value to a set of safe, supported flags. It doesn’t support flags that let the build read arbitrary files or run arbitrary code. It drops any unsupported flag or invalid value individually and applies the remaining supported flags. You can write flags in either the --flag value or --flag=value form.

The capability drops any other flag, including --load-restrictor, --enable-exec, and --enable-alpha-plugins.

Custom health checks

Argo CD assesses the health of the resources it deploys. For standard Kubernetes resources such as Deployments and Services, Argo CD has built-in health logic. For Custom Resources that Argo CD does not recognize, it has no built-in health logic and reports no health status.

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 when its resources are still provisioning or have failed. This also means that sync waves can advance before those resources are ready, because sync ordering depends on reported health.

With custom health checks, you can define health logic for your Custom Resources, so Argo CD reports accurate health and sequences deployments correctly. You define custom health checks the same way you do in upstream Argo CD, using the same configuration keys. Existing upstream scripts and community examples work with the EKS Capability for Argo CD without modification.

Built-in health checks for ACK and kro

The EKS Capability for Argo CD includes built-in health checks for AWS Controllers for Kubernetes (ACK) and kro (Kube Resource Orchestrator) resources. These resources report accurate health with no additional configuration.

To change how the capability assesses the health of an ACK or kro resource, you can define a custom health check for that resource type. A custom health check that you define for a resource type overrides the built-in health check for that type.

Write a custom health check

Define a custom health check by adding a Lua script to the argocd-cm ConfigMap, using a key in the following format:

resource.customizations.health.<group>_<kind>

Replace <group> with the API group of the Custom Resource and <kind> with its kind. For example, the key for a Custom Resource with the API group example.com and the kind Database is resource.customizations.health.example.com_Database.

The Lua script has access to the resource object through the global obj variable. The script must return a table with a status field set to one of Healthy, Progressing, Degraded, or Suspended. The script can also set an optional message field to provide a descriptive status message.

The following example ConfigMap defines a health check for a Database Custom Resource. The script reports the resource as Healthy when its status phase is Ready, and as Progressing otherwise:

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

For more information about the health check script format, the list of built-in health checks, and community examples that you can adapt, see Resource Health on the Argo CD documentation website.

Safety and limitations

With the managed capability, your custom health check scripts run in isolated, fully managed compute. The execution environment is isolated per capability and has no access to your cluster’s data or to AWS APIs. You do not provision, patch, or operate any part of the execution environment.

Note the following when you write custom health checks for use with the EKS Capability:

If health evaluation is temporarily unavailable, the capability reports affected Custom Resources as Progressing rather than removing their health status. This keeps the affected resources visible in the Application’s health until evaluation recovers.

Verify a custom health check

After you apply or update the argocd-cm ConfigMap, confirm that the health check is active: