This is not a guide to set-up argocd-agent for a production environment. It is rather a guide to help you get going with contributing to and hacking on argocd-agent. This guide does not intend to provide pure copy & paste instructions. Instead, it will assume a little bit of willingness to hackery on your side, as well as some core knowledge about the underlying technologies (JWT, TLS, etc)
Please note that some resource names might be out-of-date (e.g. have changed names, or were removed and replaced by something else). If you notice something, please figure it out and submit a PR to this guide. Thanks!
- control plane refers to the cluster with the management (or, controlling) components installed on. This typically will have the Argo CD UI on it, is connected to SSO, etc.
- hub is synonymous with control plane
- workload cluster refers to any cluster on which applications are reconciled to by Argo CD
- spoke is synonymous with workload cluster
- principal is the component of
argocd-agentthat runs on the control plane cluster. It provides gRPC services to the outside world. It will connect to the Kubernetes API on the control plane cluster only. - agent is the component of
argocd-agentthat runs on each workload cluster. It connects to the principal on the control plane via gRPC and will send and receive events over that connection. It will also connect to the Kubernetes API on the workload cluster.
Each agent can operate in one of the following modes:
- autonomous - In autonomous mode, configuration is maintained outside of the agents scope on the workload cluster. For example, through local ApplicationSets, App-of-Apps pattern or similar. Applications created on the workload cluster will be visible on the control plane. It is possible to trigger sync or refresh from the control plane, however, any changes made to the Applications on the control plane will not be propagated to the agents.
- managed - In managed mode, configuration is maintained on the control plane and transmitted to the workload cluster. Configuration can be performed using the Argo CD UI or CLI on the control plane, but could also come from other sources such as ApplicationSet. In managed mode, the Argo CD on the workload clusters may use the Redis on the control plane for enhanced observability. Also, it is possible to trigger sync and refresh from the control plane. However, any changes made to Applications on the workload clusters will be reverted to the state on the control plane.
The principal does not need to know details about topology details of the workload clusters or agents. However, agents need to authenticate to the principal using a pre-assigned, unique name. Agent names must comply to the RFC 1123 DNS label naming scheme. You need to create the credentials for the agent on the control plane cluster. You may also want to add an extra layer of authentication by requiring the agents to use TLS client certificates in addition to their credentials.
Each agent is assigned a dedicated, unique namespace on the control plane. This namespace will hold all of the workload cluster's configuration. The namespace must be created manually for now, before the agent is connecting the first time (this may change in the future).
On the workload cluster, the agent must be configured at least with:
- the address or FQDN of the principal's gRPC service,
- the agent's credentials,
- optionally, the agent's TLS client certificate and key,
- the agent's mode of operation (autonomous or managed)
A loose and incomplete collection of current limitations that you should be aware of.
The connection from the agent to the principal needs to be end-to-end HTTP/2. If you have a network component that is not able to speak HTTP/2 in either direction, argocd-agent will not work for you at the moment.#190 introduced preliminary support for HTTP/1 via websockets.- On the workload clusters, the apps-in-any-namespace feature cannot be used. This may or may not change in the future.
- Argo CD UI/API features that do not work in either mode, managed or autonomous:
- Pod logs
- Resource actions
- Resource manipulation
- Other Argo CD UI/API features such as resource diffing, live manifests, etc only work within specific topologies.
To install the principal, we will need the following things:
- An RSA key used to sign JWT tokens and
- A set of TLS certificates and private keys,
- A credentials file for authenticating agents
- Some Argo CD components installed, depending on the desired mode of agents
For the sake of simplicity, we will use the argocd namespace to install all required resources into the cluster.
The principal installation will come with a ClusterRole and ClusterRoleBinding, so make sure the account you'll be using for installation has sufficient permissions to do that.
The JWT signing key will be stored in a secret in the principal's namespace. We will first need to create the key:
openssl genrsa -out /tmp/jwt.key 2048
If you want a keysize different than 2048, just specify it.
Then, create the secret named argocd-agent-principal-jwt with the RSA key as field jwt.key:
kubectl create -n argocd secret generic --from-file=jwt.key=/tmp/jwt.key argocd-agent-jwt
The principal itself will need a valid TLS server certificate and key pair in order to provide its service. This may be a self-signed certificate if you turn off TLS verification on the agents but that is insecure and shouldn't be used anywhere, really.
A much better idea is to use certificates issued by an existing CA or to set up your own CA. For development purposes, it is fine (and even encouraged) that such CA is of transient, non-production nature.
Once you have the server's certificate and key (in this example, stored in files named server.crt and server.key respectively) as well as the certificate of the CA (stored in a file named ca.crt), create a new secret with the contents of these files:
kubectl create -n argocd secret generic --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt argocd-agent-tls
Keep the ca.crt file, as you will need it for the installation of agents, too.
Create the principal user password secret; replace <PASSWORD> with the password of your choice:
kubectl create -n argocd secret generic argocd-agent-principal-userpass --from-literal=passwd='<PASSWORD>'
Now that the required secrets exist, it's time to apply the installation manifests and install the principal into the cluster:
kubectl apply -n argocd -k install/kubernetes/principal
This should create all required manifests in the cluster and spin up a deployment with a single pod.
To check its status:
kubectl get -n argocd deployments argocd-agent-principal
kubectl get -n argocd pods
You can configure the principal by editing the argocd-agent-params ConfigMap in the principal's installation namespace. For an up-to-date example with comments, have a look at the
example
After a change to the argocd-agent-params ConfigMap, the principal needs to be restarted to pick up the changes:
kubectl rollout -n argocd restart deployment argocd-agent-principal
To install the agent, we will need the following things:
- A set of TLS certificates and private keys,
- A credentials file for authenticating agents
we will use the argocd namespace to install all required resources into the cluster.
Create the agent user password secret; replace <CREDENTIALS> with the credentials of your choice:
kubectl create -n argocd secret generic argocd-agent-agent-userpass --from-literal=credentials='<CREDENTIALS>'
Now that the required secrets exist, it's time to apply the installation manifests and install the agent into the cluster:
kubectl apply -n argocd -k install/kubernetes/agentThis should create all the required agent related resources.
You can configure the agent by editing the argocd-agent-params ConfigMap in the agent's installation namespace. For an up-to-date example with comments, have a look at the
example
Note:
Set agent.tls.client.insecure to insecure to if needed.
After a change to the argocd-agent-params ConfigMap, the agent needs to be restarted to pick up the changes:
kubectl rollout -n argocd restart deployment argocd-agent-agent