Health Checks Overview

In the previous module, we completed our exploration of synchronization options, covering sync windows, allow/deny rules, schedules, and enterprise freeze patterns. With deployment schedules clear, we will now start Module 8: Health Checks, beginning with Health Assessment Overview.

Once resources are synchronized and deployed, ArgoCD does not stop tracking them. The controller maintains a continuous diagnostic loop to check the health and readiness states of all child resources inside your application dependency tree.

In this guide, we will cover how ArgoCD gathers health status data, how health status codes are mapped, and how they are displayed in the dashboard.

1. How ArgoCD Gathers Health Status Data

The argocd-application-controller pod monitors target cluster resources by querying the Kubernetes API server:

Reconciliation Diagnostic Loop
        │
        ▼ (1. Query Kubernetes API server)
  Kubernetes API (Resource Status)
        │
        ▼ (2. Parse status parameters)
  - Pods: status.phase
  - Deployments: status.availableReplicas
  - Services: status.loadBalancer.ingress
        │
        ▼ (3. Map to Health Code)
  Health Status Code: Healthy / Progressing / Degraded / Suspended

• Deployments: Compares status.availableReplicas with status.replicas. If they match, and all replicas are running, the resource is marked Healthy.
• Services: Verifies that endpoints are bound. For LoadBalancer services, it checks that the cloud load balancer has assigned an IP or hostname.
• Pods: Evaluates the container status list. If any container has crashed or is stuck in an initialization state, the pod status updates to Degraded or Progressing.

2. Explaining Health Status Codes

The health status of any resource is mapped to one of the following codes:

Healthy

The resource is fully functional and ready to process requests. All pods are running and ready, endpoints are active, and ingress routing is verified.

Progressing

The resource is currently transitioning to a healthy state (e.g., pods are booting, downloading images, or running init containers).

Degraded

The resource has failed to boot or configuration errors occurred (e.g., pods are stuck in CrashLoopBackOff or volume attachments failed).

Suspended

The resource execution is paused (e.g., CronJobs/Jobs are suspended or completed successfully).

3. The Health Rollup Hierarchy

ArgoCD rolls up health statuses from individual resources to the top-level Application card in the dashboard. The application health is determined by the lowest health status in its resource tree:

       Application Card Health (DEGRADED)
                     ▲
                     │ (Rolls up to parent)
       Deployment Health (DEGRADED)
                     ▲
                     │ (Rolls up to parent)
          Pod Health (DEGRADED)
                     ▲
                     │ (Container crash detected)
          Container 1: CrashLoopBackOff

If a single resource in the tree is Degraded, the entire Application health updates to Degraded, alerting the team.

4. Operational Best Practices: Health Checks

• Configure probe timeouts: Set reasonable timeout limits on your liveness and readiness probes to prevent pods from switching statuses during transient network drops.
• Integrate alert notifications: Set up alert rules to send notifications to Slack or PagerDuty immediately when applications become degraded.
• Write custom health scripts: Configure custom Lua health checks for all third-party CRDs to ensure accurate health monitoring.

5. Health Status Code Reference Summary

Now that we have covered how ArgoCD gathers health data and maps status codes, the next step is built-in health checks. In the next section, we will cover the default built-in health checks for core Kubernetes resources.