Skip to content
English
  • There are no suggestions because the search field is empty.

Akuity Cluster Agents in an Unknown Status

Misapplied agent manifests cause a healthy-looking agent that fails to register with the Akuity control plane.

Overview

Akuity agent pods appear healthy when inspected via kubectl, but the Akuity Platform dashboard shows the cluster as not reporting or in an unknown state. This symptom is most commonly caused by applying the wrong agent manifests to the wrong cluster, resulting in a running agent process that is registered to a different cluster identity than expected.

  • The cluster row on the Akuity Platform Clusters dashboard shows a question mark (?) status icon or displays "Cluster agent health is unknown."
  • A tooltip reads: "Did you install the agent manifests?"
  • The Installed Agent and Installed Argo CD columns show a dash (–) for the affected cluster.
  • kubectl get pods -n <agent-namespace> shows agent pods in a Running and Ready state.
  • No obvious errors appear in the agent pod logs at first glance.
  • Re-applying the correct manifests resolves the reporting issue immediately.

Root Cause

Each Akuity agent manifest is generated specifically for a single cluster and contains a cluster-scoped identity (agent ID). When manifests intended for Cluster A are applied to Cluster B, the agent running on Cluster B registers itself against Cluster A's identity in the Akuity control plane.

As a result:

  • Cluster B has no registered agent, so the platform marks it as unknown/not reporting.
  • Cluster A may appear to have a duplicate or ghost agent registration.
  • kubectl reports healthy pods because the container runtime has no visibility into whether the agent is talking to the correct control-plane identity.

Following Steps can be taken:

Step 1 – Confirm the Symptom on the Dashboard

Navigate to Akuity Platform > Argo CD > <Instance> > Clusters and confirm that the affected cluster shows a ? status with the tooltip "Cluster agent health is unknown. Did you install the agent manifests?"

Step 2 – Verify Agent Pods Are Running

kubectl get pods -n akuity-agent   # or the relevant namespace

Expected (misleading) output: pods in Running/Ready state despite the dashboard showing unknown status.

Step 3 – Identify and Re-apply the Correct Manifests

Obtain the correct manifests for the affected cluster from the Akuity Platform:

  1. Navigate to Akuity Platform > Clusters > [Affected Cluster] > Install.
  2. Download or copy the manifest for the specific cluster.
  3. Apply it to the correct target cluster: kubectl apply -f <correct-cluster-manifest>.yaml
  4. Monitor the Clusters dashboard. The status icon should turn green within 1-2 minutes.

Resolution

After applying the correct manifests, the Installed Agent and Installed Argo CD version columns on the Clusters dashboard should populate (e.g., v0.5.92 and v3.4.3-ak.70 respectively), and the status icon should turn green.