How to Deploy Argo CD on Kubernetes [Beginners Guide]

In this blog we will look Argo CD installation on Kubernetes using step by step instructions.

After the installation, we will look at deploying sample applications the GitOps way. We will use a git repository to deploy application using ArgoCD.

We will also look at configuring github webhooks to enable sync process as soon as there is a change in the configured git repository.

Setup Prerequisites

To get started with the setup, you should have the following.

1. A working Kubernetes cluster
2. Kubectl configured with the cluster with cluster admin permissions.
3. Helm installed an configured on your workstation..

Lets get started with the setup.

ArgoCD Setup Using Manifest Files

The easiets way to setup ArgoCD on Kubernetes is using plain Kubernetes manifest files available in the Argo project Github repository.

You can use this manifest deployment for learning purposes. If you are setting up ArgoCD for projects requirements, use helm charts given in the next section.

We will deploy ArgoCD in a custom namespace called argocd

The following kubectl commands will create the namespace and deploy the manifest

kubectl create namespace argocd

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

It creates many Kubernetes objects related to ArgoCD – Namespace scoped & cluster scoped resources

The key objects are Argocd services, deployments and statefulsets, ClusterRoles, Configmaps and Secrets.

It also created Argo CD custom resources like applications, applicationsets and appprojects

You can access the ArgoCD UI in our workstation using the following port warding command.

kubectl port-forward svc/argocd-server -n argocd 8080:443

You will get an SSL error due to self-signed certificate added to the ArgoCD server. You can click proceed to access the UI.

To login to the UI, you need a username and password.

The default username is admin. To get the password, execute the following command.

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 --decode ; echo

Once logged in you will get the ArgoCD server dashbaord as shown below.

You can clean up the setup using the following command.

kubectl delete -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

ArgoCD Setup Using Official Helm Chart

If you are setting up ArgoCD for project purposes, we highly recommend you setup using Helm charts rather than plain manifest files.

Follow the steps given below to setup ArgoCD using the official Argoproject helm chart.

Step 1: Add argo cd repo

Add Argo CD repo to your system to download the helm chart to set up Argo CD. Run the following command to add the repo

helm repo add argo https://argoproj.github.io/argo-helm

Now, list every repo with the word argo using the command

helm search repo argo

You will get the list of repos with the word argo as shown below. The chart we need is argo-cd

You can convert the argo-cd Helm chart to a Kubernetes manifest using the command given below. This allows you to go through all the configurations associated with the Helm chart. This is primarily important when using the Helm chart for project purposes.

helm template argo argo/argo-cd --output-dir argocd-manifests

This helm chart deploys the following argocd components.

1. argocd application controller (Statefulset): A core component of Argo CD that is responsible for managing and synchronizing applications (reconcilation) deployed in a Kubernetes cluster with the desired state in Git
2. argocd application set (Deployment): A controller that automatically generates and manages Argo CD Applications based on a template.
3. argocd notification (Deployment): To send notifications about Argo CD events to various channels like email, Slack, or webhooks.
4. argocd reposerver (Deployment): The component that manages Git repositories and provides an API for accessing and synchronizing application manifests.
5. argocd server (Deployment): The main component that exposes the Argo CD API and serves the web UI for managing applications and configurations.
6. dex server (Deployment): It is an identity provider that can be integrated with Argo CD for user authentication and authorization with external identity providers (OIDC Providers) like GitHub, SAML etc.
7. Redis (Deployment) : Used for caching to reduce request sent to Kube API and to Git provider.

Step 2: Customize Helm Chart Configuration Values

Before deploying you need to update NodePort configurations in the helm chart so that you can access Argo CD UI in the browser, for that use the below command to save the default values of the helm chart in a YML file.

helm show values argo/argo-cd > values.yaml

Make changes in the service configuration block. Change the type from ClusterIP to NodePort as shown in the below image. It is responsible for exposing the Argo CD server UI. The deafult nodePort is 30080. You can customize that as well.

By changing the type to NodePort you can access Argo CD UI on the browser using the URL <Public/Private IP of your k8s node>:<port>.

Make sure to use the same node port number you mentioned in the values.yml file.

Following are the images used in this Helm chart.

1. quay.io/argoproj/argocd
2. ghcr.io/dexidp/dex
3. public.ecr.aws/docker/library/redis

If you want to set up ArgoCD in an project environment without access to these public registries, you might have to upload them to the relevant internal registry and then run the helm chart with custom values.

You can also download the whole helm chart with every file use the below command

helm fetch argo/argo-cd

This command will download every file of the helm chart in a .tgz package, run the below command to extract the file

tar -zxvf argo-cd-<version>.tgz

Now, you can see every file packed inside the package.

Step 3: Deploy Argo CD

Before deploying Argo CD, create a namespace for it using the command

kubectl create namespace argocd

Now, use the below command to deploy Argo CD in the namespace created above

helm install --values values.yaml argocd argo/argo-cd --namespace argocd

On a successfull deployment, you should see the following output.

Verify if all the objects have been created and running successfully using the command.

kubectl get all -n argocd

Step 4: Log in to Argo CD Web UI

You can access the web ui using port forwarding using the following command.

kubectl port-forward svc/argocd-server -n argocd 8080:443

If you visit http://localhost:8080 you will be able to access the webUI. You need to accept the self signed certificate to access the dashboard.

Also, we have enabled the NodePort on 30080

You can use the public IP or Private IP of any node of your cluster with the node port number in the format <node IP>:<port>. In my case, the URL will be 34.71.163.101:30080

Now, access the UI in your browser using the URL you will get the following window

Login to Argo CD using the username and password.

Your default username will be admin and to get the password run the following command

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 --decode ; echo

This command will show your password for Argo CD, use the password and log in to Argo CD UI.

Once you log in you can see the home screen of Argo CD as shown below

Deploying Applications from GitHub with ArgoCD (GitOps Way)

Now that we have the ArgoCD setup ready, we can test a Nginx deployment that shows a custom message in Index page exposed on NodePort 32000.

We have the Nginx deployment files in the Argo CD Guide repository.

https://github.com/techiescamp/argocd-guide

The manifests are organzied the following way under the nginx-deployment folder.

➜  nginx-deployment

├── configmap.yaml
├── deployment.yaml
└── service.yaml

From the Argo CD dashboard press the + NEW APP button to configure the repository.

A new window will pop up, specify the Application Name as nginx-deployment, give the Project Name as default, and set the SYNC POLICY to automatic or manual as you like.

If you set the SYNC POLICY to automatic, Argo CD automatically detects the changes made in your Git repository and triggers the deployment, or if you set the SYNC POLICY to manual you have to trigger it manually to start the deployment.

By default the automatic sync uses polling to find the changes that happens in the git repository. The default polling interval is three minutes (180 seconds). It is a configurable option in the helm chart. You can modify timeout.reconciliation as per your sync requirement.

Also enable AUTO-CREATE NAMESPACE option so that namespace will be created if it doesn’t exist.

Also, there are other SYNC POLICY options, enable them as per your need.

Now, add the source information which is your Git repository URL, and the path of the YML file.

Then, select the Cluster URL which will be shown when you select the Cluster URL tab. Select https://kubernetes.default.svc as we are deploying the application on the same cluster where Argo CD is deployed.

Also specify the namespace as webserver. Now click the Create button as shown below.

When you click the create button it will sync the repository manifests and deploy it. You can see the deployment information in the dashboard as shown below.

Click the application to see detailed info about your deployment as shown below.

To validate our deployment, lets try to access the Nginx deployment on NodePort 32000. You should see a page as shown below.

Configure Github Webhook

Though Argo CD continuously monitors Git for changes there is a time delay in syncing the changes, to remove the time delay we can use webhook which triggers the sync process as soon as a change is made in Git.

Let’s loot at how to configure webhook on Argo CD.

After pressing the Add webhook button you can see the configuration window as shown below.

The Payload ULR would be the ArgoCD webUI endpoint appended with /api/webhook. That is <node IP>:<port>/api/webhook

For example, https://34.71.163.101:30080/api/webhook.

Change the Content type to application/json, and give the Secret as you like.

Now, select Enable SSL verification if you are using an SSL certificate for your Argo CD, and select Disable if you are not using an SSL certificate.

Then select the event in which you like to trigger the webhook, it will trigger the webhook according to the event you select.

Press the Add webhook button to add the webhook configuration for your Argo CD, you can see the webhook has been added as shown below

By selecting it you can see the triggers made by the hook as shown below

ArgoCD Setup Best Practices

Following are some of the best practices you need to follow when running ArgoCD for production use cases.

1. It is a standard practice to run one Argo CD instances per environment (dev, stage, prod) to avoid potential conflicts.
2. Ensure you enable RBAC to limit access to the ArgoCD instance to follow principle of least privilege. Categorize users based on roles and responsibilities and audit them regularly.
3. Patch the ArgoCD image regularly to avoid security vulnerabilities.
4. Backup ArgoCD configuration for disaster Recovery and backup purposes.
5. Setup monitoring and alerting using tools like Prometheus for events like deployment failures, resource constraints etc.

Argo CD Configuration FAQ’s