What are ArgoCD resource health checks and how do you write a custom one?

ArgoCD evaluates the health of every managed Kubernetes resource using health check scripts written in Lua. For built-in resource types (Deployments, StatefulSets, DaemonSets, Services, Ingresses, PVCs, Jobs, CronJobs, etc.), ArgoCD ships with health checks out of the box. For Custom Resource Definitions (CRDs), ArgoCD returns Unknown health unless you provide a custom Lua script.

A Lua health check script receives the live resource object and must return a hs table with at least two fields: status (one of Healthy, Progressing, Degraded, Suspended) and message (a human-readable explanation).

Custom health checks are registered in the argocd-cm ConfigMap under the resource.customizations.health key:

# argocd-cm ConfigMap
data:
  resource.customizations.health: |
    certmanager.k8s.io/Certificate: |
      hs = {}
      if obj.status ~= nil then
        if obj.status.conditions ~= nil then
          for i, condition in ipairs(obj.status.conditions) do
            if condition.type == "Ready" and condition.status == "True" then
              hs.status = "Healthy"
              hs.message = "Certificate is ready"
              return hs
            end
          end
        end
      end
      hs.status = "Progressing"
      hs.message = "Waiting for certificate to become ready"
      return hs

The Lua sandbox in ArgoCD is restricted — it has no network access, file I/O, or most standard library functions. You work with the resource object (as a Lua table) and the hs return table only. This makes health checks fast and safe but requires understanding Lua table syntax for navigating nested JSON-like structures.