When argocd-agent fits a hub-and-spoke Argo CD design
argocd-agent suits teams that must manage clusters the central Argo CD cannot reach inbound. Lightweight agents run on each workload cluster and connect out to a central hub, so the control plane needs no outbound connections to those clusters and the application controllers run locally, next to the workloads they reconcile. That single change matters most when clusters sit behind firewalls, in segmented networks, in edge locations or in another organization's account, where opening inbound API access from a management cluster would be refused by the security team or would widen the attack surface more than the design can justify.
The pattern earns its complexity when several conditions hold at once: many clusters, network rules that block the central control plane from calling their API servers, and a need to keep each cluster's reconciliation working if the link to the hub drops. If your clusters are reachable from one management cluster through an approved network path, and the teams accept that path and its credentials, plain cluster registration as described in the Argo CD documentation is simpler to build, verify and operate. Count the clusters that would need new network paths, the number of credentials you would otherwise store centrally, and whether your change process already accepts an agent running in each cluster.
Before you commit, confirm two things with the project rather than assume them. The argocd-agent documentation describes the project as under active development with a stable core and notes that some sections may be incomplete, so check the current feature list, supported Argo CD versions and upgrade path against the argocd-agent documentation for the release you plan to use. Then decide which agent mode fits each cluster, since managed and autonomous modes change where configuration originates and therefore who can change a workload cluster. Write those answers into the design record so the reader's security and platform leads can review the decision before any cluster is connected.
Managed mode or autonomous mode: which direction configuration flows
In managed mode, configuration flows from the control plane to the workload cluster. Application definitions are authored and stored on the hub, and the agent on the spoke receives them and applies them locally. The platform team keeps one place to define what runs where, which suits clusters where a central team owns the change history.
- Authorship: Application resources are created and edited on the control plane, so application teams work through the hub rather than the spoke cluster.
- Change origin: Changes start at the hub and are pushed to the agent, which makes the hub the audit point for what was deployed.
- Spoke role: The workload cluster runs the application controller locally, but its desired state comes from the hub.
- Operational fit: Teams that want one approval path across many clusters usually find this mode easier to govern.
- Trade-off: A spoke that loses its link to the hub cannot receive new desired state until the connection returns.
Before you choose this mode for a spoke, confirm the exact sync and failure behavior for managed mode in the argocd-agent agent modes documentation.
In autonomous mode, configuration flows from the workload cluster to the control plane. The team that operates the spoke authors its application definitions locally, and the agent reports that configuration up to the hub. This suits clusters where local teams need to keep ownership of their manifests and where the hub should mirror, not originate, the change.
- Authorship: Application resources are created on the workload cluster, closer to the team that owns the workloads.
- Change origin: Changes start on the spoke and are reported to the principal, so the spoke's own change process remains the source of truth.
- Hub role: The control plane holds a view of spoke state for visibility, reporting and central oversight.
- Operational fit: Teams in segmented networks or with local change control often prefer keeping authorship where the workloads run.
- Trade-off: Central policy has to be enforced through what the spoke accepts and reports, so the hub's control over spoke content is different from managed mode.
Confirm the exact direction of configuration, reporting and conflict handling for autonomous mode in the argocd-agent agent modes documentation before you design approval flows around it.
Both modes can run in the same hub-and-spoke design, so each spoke can use the mode that matches its ownership model. A design might place regulated production clusters in managed mode while letting a lab or edge site in autonomous mode. The decision is per spoke, but it changes how the hub's audit trail and RBAC map onto each cluster.
- Per-spoke choice: Assign a mode to each agent based on who owns its workloads and how its change process works.
- Audit consistency: Decide in advance how changes from autonomous spokes will appear in the hub's history alongside managed changes.
- Access model: Map hub projects and RBAC to each spoke so that teams see only the applications they own, whichever direction configuration flows.
- Operational runbooks: Document the recovery steps for each mode, since a disconnected spoke behaves differently in each.
- Maturity: Mixed designs add operational surface, so test each mode on a non-production spoke first.
The argocd-agent project describes itself as under active development with a stable core and some incomplete sections, so verify the mixed-mode behavior you rely on in the argocd-agent documentation before committing production spokes.
The direction of configuration flow determines which team's process controls each change. Before selecting a mode, map who creates applications, who approves them, and where the approved record lives. Mismatches here cause the most friction after go-live, when a hub approval and a local change disagree about what should be running.
- Application authors: Name the group that writes application manifests for each spoke and confirm they have the access that mode requires.
- Approvers: Identify whether approvals happen in Git review, on the hub, or in a local change system.
- Source of truth: Decide which record counts when hub and spoke disagree, and document it.
- Emergency changes: Define who can change a spoke during an incident and how that change is reconciled afterward.
- Evidence: Plan what the hub logs and what the spoke retains, so an auditor can trace a change to its origin.
Work through these questions with your change management owners, then confirm the authorship and reporting details for each mode in the argocd-agent agent modes documentation.
Each mode behaves differently when the connection between hub and spoke is lost, and recovery depends on which side holds the latest desired state. Plan this before go-live rather than during an outage. The questions below help you define expected behavior, and the agent modes documentation should confirm the exact mechanics.
- Managed spokes: Ask what the spoke keeps running and whether it resumes from the last applied desired state after reconnecting.
- Autonomous spokes: Ask how changes made locally during an outage are reported to the hub once the link returns.
- Hub outage: Confirm which hub components are required for spokes to keep operating and how the hub is restored.
- Testing: Rehearse disconnection and reconnection on a non-production spoke for each mode you plan to run.
- Documentation: Keep a recovery runbook per mode that names the owner and the steps.
For each mode, record what you confirmed with the vendor documentation and what you tested yourself, because the project is still maturing and some sections may be incomplete.
Configuration choices and when each fits
This table compares the decisions a team makes before deploying argocd-agent: the mode for each cluster, where the principal runs and how it is exposed, and how mixed fleets are organized. Read each row as a question to settle for your fleet, then confirm the current behavior in the project documentation before you commit.
| Decision | Option | When it fits | What to confirm |
|---|---|---|---|
| Agent mode per cluster | Managed mode | Central teams own configuration and want the control plane to define what each workload cluster runs. | Which resources flow from the control plane to the agent, and how local overrides are handled. |
| Agent mode per cluster | Autonomous mode | A cluster team owns its own manifests and wants changes to originate in the workload cluster. | How the principal records and reports status from clusters that keep their configuration locally. |
| Agent mode per cluster | Mixed modes in one hub | Some clusters are centrally governed while others are run by their own teams under the same principal. | Whether a single principal can serve both modes at the same time and how RBAC maps to each mode. |
| Principal placement | Principal in the hub cluster | One central Argo CD control plane is already operated and the hub has sufficient capacity and access controls. | The supported install topology for the principal and the namespaces, service accounts and CRDs it requires. |
| Principal exposure | Inbound endpoint reachable by agents | Workload clusters can reach the hub over a network path you approve, such as a private load balancer or VPN. | The supported transport, the TLS and client certificate setup, and the ports that must be open on each side. |
| Agent placement | Agent per workload cluster | Each remote or firewalled cluster needs its own local application controller and only outbound connectivity. | The agent's resource footprint, its upgrade path, and how it authenticates to the principal. |
| Fleet organization | Grouping by environment or region | Clusters share change windows, owners or compliance boundaries, so one principal serves each group. | How agents are named and mapped to projects, and how loss of connectivity is reported per group. |
| Maturity | Pilot before production | Your team can accept a project still under active development and expects to track releases closely. | The current release status, known gaps in the documentation, and the support you can rely on. |
How mature argocd-agent is today and what to confirm before adopting it
The argocd-agent documentation describes an active project with a stable core and some incomplete sections. The cards below separate what is documented from what you must verify in a lab, so the decision to adopt rests on your own testing rather than on the project's label alone.
Documented status and licensing
argocd-agent is Apache 2.0 licensed and lives in the argoproj-labs organization, not the main Argo project namespace. The documentation describes it as under active development with a stable core, and notes that some sections may be incomplete. Record this status in your architecture decision, and treat the stable core as the only part you would consider for production until your own tests confirm the rest.
Pin versions for every component
Pin the argocd-agent principal, the agent and the Argo CD release they run beside to exact versions in Git. Because the project is still moving, a change in any one component can alter how the hub and spokes talk. Ask DeployOpen or your team to confirm the compatibility matrix for the exact versions you select, and keep the pinned set in the same repository as your other deployment manifests.
Plan upgrades around Argo CD releases
Argo CD ships a minor release four times a year, and only the three most recent minor versions get patch releases. Your agent tier may lag the hub or need matching versions, so plan each upgrade as a joint change: upgrade a lab hub and agent first, run sync and rollback tests, then roll out to spokes in waves. Confirm with the project which versions are supported together before you set a schedule.
Verify the managed and autonomous modes
Confirm in a lab which mode each cluster will use. In autonomous mode, configuration flows from the workload cluster to the control plane, while in managed mode it flows the other way, and the two can be mixed. Test which application definitions can be created, edited and deleted from the hub for each mode, since the boundary between them determines who can change what on a spoke.
Test failure and recovery paths
Simulate a lost network path between an agent and the principal, a principal restart and a spoke cluster outage. Confirm how queued changes resume, whether applications show stale status, and how credentials and certificates for the agent connection are rotated. Record the recovery steps as a runbook, because the incomplete documentation sections may not cover these cases.
Confirm RBAC, TLS and tenancy fit
Check that the features your teams need are documented and working: project boundaries, SSO group mapping, audit of changes made through the hub and the TLS setup between agents and the principal. Where a section is incomplete, ask the maintainers or test it yourself before writing it into your control design. Keep a sign-off record of what was verified and by whom.
How to set up a hub and one spoke with argocd-agent
This sequence connects one workload cluster to a central Argo CD hub through an outbound agent connection, so the hub manages that cluster without inbound access to it. Each step ends with a check that tells you whether the next step can start.
Prepare the hub and principal networking
The platform team selects the hub cluster that will run Argo CD and the argocd-agent principal, then confirms the address and port the principal will expose to workload clusters. Agents only need outbound access to that endpoint, so the firewall work is on the workload side, but the principal endpoint must be reachable from every spoke network. Confirm the exact ports, ingress or load balancer choices and TLS requirements in the current argocd-agent documentation before you change any firewall rule. Done means the endpoint resolves from the spoke network and the rule that allows the agent's outbound connection has been approved by the network owner.
Deploy the principal on the hub
Install Argo CD on the hub, then deploy the argocd-agent principal component next to it using the installation method the current documentation describes. The principal is the component that accepts agent connections, and the application controllers for spoke clusters will run on those spokes rather than on the hub. Generate or supply the certificates the principal needs, following the documented certificate handling rather than improvised steps. Done means the principal pod is running, its logs show it listening for connections, and the Argo CD UI or CLI on the hub responds normally.
Prepare the workload cluster and its agent
On the workload cluster, install the argocd-agent agent component in the namespace the documentation specifies and give it the client identity and certificates that the principal expects. Use an agent name that matches the registration you create on the hub so the two sides can pair. Confirm that the agent has the RBAC it needs on its own cluster, since the local application controller will apply manifests there. Done means the agent pod is running and its logs show it is preparing to connect, with no certificate or name errors.
Establish the outbound agent connection
Start the agent so it dials out to the principal endpoint from the previous steps. The hub does not open any connection to the workload cluster, which is the main reason this pattern suits remote or firewalled clusters. Check the principal logs for an agent connection record with the expected name, and check the agent logs for a successful session with the principal. If the connection fails, check the endpoint, the TLS trust chain and the certificate names before changing anything else. Done means the principal reports the agent as connected.
Choose the agent mode for each spoke
Decide whether this spoke runs in managed mode, where configuration flows from the control plane to the workload cluster, or autonomous mode, where configuration flows from the workload cluster up to the control plane. The two modes can be mixed across spokes, so the decision is per cluster. Ask your team which party should own the Application definitions for each cluster, because that answer usually decides the mode. Record the choice in Git with the agent configuration so the decision is reviewable. Done means the mode is set in the agent configuration and the agent has restarted or reloaded under that mode.
Verify sync and agent status
Create a small test Application that targets the spoke, sync it, and confirm that the resources appear on the workload cluster and that the hub shows them as healthy and synced. Then check the agent status from the hub, and test a change in Git to confirm that a new revision reaches the spoke. Repeat the test after restarting the agent to confirm that it reconnects on its own. Done means the test application is synced and healthy, a Git change propagates, and the agent reconnects after a restart. Treat any gap here as a blocker before onboarding real workloads.
Security and operational risks of agent-based delivery
An agent-based design moves connection direction, credentials and failure handling into places a single hub-and-spoke model does not have. The cards below cover where trust is created, how identities are issued and rotated, how access is scoped on each side, and what to check when the hub cannot be reached.
Outbound connections define the trust boundary
Because each agent opens its connection to the principal, the workload cluster accepts no inbound control traffic from the hub. That shifts the risk to the principal, which becomes the single point that every agent trusts. Confirm where the principal is exposed, who can reach its endpoint, and which network paths agents are allowed to use before you register the first spoke.
Certificates between agent and principal
Agents and the principal authenticate with certificates, and the Argo CD security documentation states that TLS protects traffic between its components. Decide who issues agent certificates, how long they live, how revocation works, and how a compromised spoke is removed from the hub. Write these steps into the runbook so rotation is not improvised during an incident.
API access depends on JSON Web Tokens
The Argo CD security documentation says the API accepts only JSON Web Tokens for authentication. Any script, pipeline or user on the hub therefore acts through a token, so token lifetime, the SSO groups mapped to roles, and the handling of automation tokens matter as much as the agent link. Review which tokens can create or change applications that target spoke clusters.
RBAC on the hub and on each spoke
Hub RBAC decides who can create or sync applications for a given agent, while each spoke still enforces what its local Argo CD components may write. Scope both: restrict hub projects to the agents and namespaces a team owns, and limit the permissions the spoke grants to the controller. Test each layer separately, because a permissive hub project will not be stopped by a narrow spoke.
Repo-server exposure on each spoke
The repo-server runs Helm and Kustomize against repository content, and the security documentation calls out untrusted repositories and out-of-tree file access as risks. In a pull model, that work happens on the workload cluster as well, so the spoke inherits this exposure. Restrict which repositories each project may use, keep plugins and chart sources reviewed, and confirm which repo-server settings apply on every spoke.
Monitoring agent health and hub outages
When an agent loses its connection, deployments on that spoke stop being driven from the hub, and the hub may show stale status without an obvious failure. Set alerts on agent connection state and on the age of the last reported sync, and define what teams do during a hub outage, including whether the spoke continues in autonomous mode and how changes are reconciled afterward.
What running argocd-agent costs in people and time
The main cost of an argocd-agent deployment is platform engineering time, not licenses, because the project itself is Apache 2.0 licensed and carries no paid edition. The work falls into four buckets: designing the hub (the principal, its exposure to agents, certificates and how Argo CD on the hub maps to teams), rolling out agents cluster by cluster, testing the chosen modes against your own workflows, and keeping the hub, agents and Argo CD versions aligned over time. The first two are largely one-time. The last two recur, and they grow with every upgrade of Argo CD or argocd-agent. Because the argocd-agent documentation describes the project as under active development with a stable core and some incomplete sections, testing carries more weight here than it would for a mature component. Ask any partner to show which parts of the documentation they verified against your intended configuration.
Several factors move effort up or down. Cluster count is the obvious one, but per-cluster work varies: a cluster that needs a managed-mode agent with a clean network path is far cheaper to bring online than one that requires custom network policy, a firewall exception review and its own certificate handling. The mix of autonomous and managed modes also matters, since each mode changes where configuration originates and therefore where change control, RBAC and troubleshooting have to be designed. Version pinning is a second lever. Teams that pin the hub, agents and Argo CD to tested releases spend more time up front but less on emergency upgrades. Teams that track moving versions pay the cost later, in regression testing. Confirm with the project's release notes which Argo CD versions your chosen argocd-agent release supports before you agree on a timeline.
For a fixed-scope quote, request a line-item breakdown with these items: hub design and certificate plan, a per-cluster rollout estimate that states the mode and network assumptions for each cluster, a test plan that names the scenarios covered and the environments used, and a description of the upgrade work included in the first year and what a separate retainer would cover. Ask which items are one-time and which recur, who holds the on-call duty for the hub and each agent, and what happens if an argocd-agent release changes behavior mid-project. A quote that cannot separate these items is hard to compare with an internal estimate, so insist on that separation before you decide between your own team and a partner.
Questions teams ask before adopting argocd-agent
Is argocd-agent production ready?
Treat it as a project that is under active development with a stable core, and plan your rollout around the parts that are still maturing. The argocd-agent documentation describes the project this way and notes that some sections may be incomplete. Before committing, check the current release notes, the open issues for the features you need, and the documentation sections that cover your mode. Ask for a pilot on a non-critical cluster, a tested recovery procedure for the principal, and a written rollback path to direct registration if a feature you depend on is not ready.
How does argocd-agent differ from registering clusters directly?
Direct registration has the central Argo CD connect outward to each cluster API server, so the control plane needs network paths and credentials for every destination. With argocd-agent, a lightweight agent on each workload cluster connects out to a central principal, so the control plane needs no outbound connections to those clusters and each application controller runs locally. The trade-off is an additional component to operate, certificates for agent identity, and a different place where configuration and status flow. Choose the agent model when clusters sit behind firewalls, in segmented networks, or outside your direct reach.
Can managed and autonomous modes run side by side?
Yes. The argocd-agent documentation states that agents can run in autonomous mode, where configuration flows from the workload cluster to the control plane, or in managed mode, where it flows from the control plane to the workload cluster, and that both modes can be mixed across clusters. Decide per cluster based on who owns the cluster's configuration and who approves changes there. Document which mode each cluster uses, because the source of truth differs between them and an operator who looks in the wrong place will misread drift.
What does the effort and timeline depend on?
Effort depends mostly on the number of clusters, how many of them sit behind restricted networks, how many teams and projects need separate access, and how much certificate and identity work the environment already has. Each agent needs a registered identity and a secure connection back to the principal, and each mode changes where the configuration lives. Ask for a quote that lists the principal setup, the number and type of agents, SSO and project design, the verification and recovery tests, and the handover to your operators. The work is fixed-scope, so the agreed written scope sets the timeline.
What does the work need from our team?
You will need named owners for the Argo CD control plane, the Git repositories that hold desired state, the clusters that run agents, and the identity provider used for access. Your team should supply network rules that allow outbound agent connections, the cluster inventory with its environments and owners, the certificate authority or issuance process, and decisions on which mode each cluster uses. Access to a non-production environment for testing is also needed before any production change. Missing owners or unclear network approvals are the most common reasons these projects slip.
Can our own team build and run this without a partner?
Yes, if your team already runs Argo CD and Kubernetes in production and has engineers who can manage certificates, network policy and Git-based delivery. The project's maturity means your engineers will need to read the current documentation, test each feature they depend on, and track releases closely. Evaluate the skills and time your team can commit, then compare that with the scope you need. A partner is useful when the team lacks that experience, needs the work finished on a fixed schedule, or wants a documented, tested runbook handed over at the end.
Which Argo CD version should we run with argocd-agent?
Pin the Argo CD version on the control plane and the agent to versions you have tested together, and confirm compatibility in the argocd-agent documentation before each upgrade. Argo CD publishes a minor release four times a year and patch releases only for the three most recent minor versions, so plan upgrades on that cadence. Ask your implementation partner or internal team to write a test step for each upgrade that covers agent reconnection and sync behavior.
How DeployOpen scopes and supports argocd-agent rollouts
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For argocd-agent, that means agreeing in writing which clusters run agents, which mode each one uses and which parts of the hub you will operate, before any build starts.
How we scope
- Inventory which workload clusters need agents and which can stay on direct cluster registration
- Choose autonomous, managed or mixed mode per cluster and record the reason in the written scope
- Confirm the hub, principal and agent placement, plus the network paths each agent opens outward
- Agree which argocd-agent features are in use, given the project's stated active development status
How we build
- Stand up the principal on the hub and agents on pilot workload clusters, then verify connectivity and sync
- Set project boundaries, RBAC and SSO mapping on the hub so agent-delivered applications stay scoped
- Test certificate issuance, agent restarts and hub outages, and record what each failure looks like
- Harden the setup against the Argo CD security guidance, including the repo-server risks on untrusted content
How we hand over
- Document the component map showing where each piece runs, which ports open and which credentials exist
- Provide runbooks for adding a cluster, rotating agent credentials and recovering the principal
- Walk your platform team through the operations and upgrade steps, including project-specific version checks
- Deliver test evidence for connectivity, sync behavior and access controls in your environment
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Track argocd-agent changes and Argo CD patch releases against your pinned versions and agreed plan
- Re-test connectivity and access controls after each cluster is added or the hub is upgraded
- Confirm current argocd-agent maturity with the project before approving any production rollout
