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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.