Support a hybrid architecture in the same Argo CD instance

[jannfis]

Is your feature request related to a problem? Please describe.

Most people that take a look at the argocd-agent project will already have an Argo CD instance, and many of them use Argo CD in production. Trying out or evaluating argocd-agent in this context comes with quite some complexity, as the user would need to stand up a dedicated Argo CD instance (i.e. without running an application controller) next to their existing instance(s).

Describe the solution you'd like

The argocd-agent architecture should support a "drop-in" installation, where the user can install and configure the principal component into an existing Argo CD installation, without any (or only minimal) changes to this installation would be required.

This would make it much easier for people to evaluate the argocd-agent, and it would aid in migrating from the traditional "push" based approach to the "pull" based approach introduced by the argocd-agent. Users would be able to perform migration one cluster at a time, with a potential rollback path.

Describe alternatives you've considered
N/A

Additional context
N/A

[jannfis]

I would assume that #593 is a prerequisite for this to work.

[jannfis]

In another discussion/troubleshooting we had recently on Slack, we also noticed that the application-controller and principal will compete over cluster secrets, which both components are using.

[jannfis]

In another discussion/troubleshooting we had recently on Slack, we also noticed that the application-controller and principal will compete over cluster secrets, which both components are using.

Potentially, we could just assign a fixed, very high shard number to our cluster secrets, for example 999999. This way, the application controller would just ignore those secrets.

Right now, I don't see any real downside to this, except a bit of migratory effort for existing argocd-agent installations.

[tleveque69]

Mmmm I tried it yesterday but it didn't work i might not have the right configuration but i set the secret shard to 9999 and i got those logs in my "legacy" argocd-application-controller (controller deployed next to the principal) :

{"level":"warning","msg":"Specified cluster shard (999) for cluster: https://argocd-agent-resource-proxy.argocd.svc:9090?agentName=dev-go-cell-001 is greater than the number of available shard (2). Using shard 0.","time":"2026-02-11T11:52:31Z"}

[jannfis]

Thanks @tleveque69 for testing it out! I think you will also need to set the ARGOCD_CONTROLLER_REPLICAS environment variable to that value, so that the sanity check passes. But the more I think about it, the more it sounds like a really ugly hack.

Maybe we should drive a feature to temporarily pause (or ignore) a specific cluster in Argo CD. So that one could put an annotation on the cluster secret, which will have any application controller shard ignore that cluster secret. That sounds like a bit of a cleaner solution to me.

[tleveque69]

This is a part of the definition of my application controller and i already had the env variable set but i still get :

{"level":"warning","msg":"Specified cluster shard (999) for cluster: https://argocd-agent-resource-proxy.argocd.svc:9090?agentName=dev-go-cell-001 is greater than the number of available shard (2). Using shard 0.","time":"2026-02-12T09:20:41Z"}

I can only agree with you on the fact that this hack is ugly.
But I wonder if it is possible to add something in to main argocd, for the agent to work 🤔 .
If this is possible, an annotation on the secret to tell the controller to ignore this secret would be the best solution 👍

[drewbailey]

I filed argoproj/argo-cd#26425, if argocd maintainers are willing to accept the issue I have a draft up on my fork, drewbailey/argo-cd#1

[jannfis]

I have created argoproj/argo-cd#26426 in Argo CD. Let's see what the community says to this.