Argo CD Installation and Usage Guide on Kubernetes

Argo CD is a Kubernetes-native declarative GitOps tool designed to manage the deployment of large-scale applications on Kubernetes. Compared to other continuous delivery tools, it is lightweight, efficient, and user-focused. It can directly fetch application code from a Git repository and deploy it into a Kubernetes cluster. Argo CD supports multiple configuration management approaches, including YAML, Kustomize, Jsonnet, and Helm. Additionally, it provides a built-in web interface that allows monitoring of synchronizations and the application’s state.

In this guide, you will install Argo CD on your Kubernetes cluster, access its web interface, and deploy applications using both the Argo CD UI and CLI.

Prerequisites

Before you begin, ensure the following requirements are met:

• Access to a Kubernetes cluster with at least three nodes.
• A Linux-based local or remote instance for testing the Argo CD CLI tool.
• kubectl CLI installed and configured on your local machine.
• Helm client installed on your local machine.
• A domain name available for your Argo CD installation, for example: argo.example.com.

Install Argo CD

Create a namespace for Argo CD:

$ kubectl create namespace argocd

Create a directory for Argo CD in your home folder:

$ mkdir ~/argocd

Move into the Argo CD directory:

$ cd ~/argocd

Clone the Argo CD Helm repository:

$ git clone https://github.com/argoproj/argo-helm.git

Enter the argo-cd directory from the cloned repository:

$ cd argo-helm/charts/argo-cd/

Update Helm dependencies:

$ helm dependency up

Install Argo CD into the argocd namespace using Helm:

$ helm install argocd . -f values.yaml -n argocd

Once successful, Helm will return output similar to this:

NAME: argocd
LAST DEPLOYED: Sun Jun 11 18:13:17 2023
NAMESPACE: argocd
STATUS: deployed
...

Check that Argo CD pods are running in the argocd namespace:

$ kubectl get pods -n argocd

The output should list pods prefixed with argocd-, which correspond to Argo CD components.

List services in the namespace to verify running endpoints:

$ kubectl get services -n argocd

Example output:

NAME                               TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
...
argocd-server                      ClusterIP   10.101.247.167           80/TCP,443/TCP      53s

The argocd-server service is responsible for serving the Argo CD UI.

Access the Argo CD UI

Although Argo CD is running, the UI is not directly accessible from outside the cluster. You can forward the argocd-server service port to a port on your localhost to access it without exposing the service externally.

First, retrieve the initial admin password stored in the secret argocd-initial-admin-secret:

$ kubectl get secrets -n argocd argocd-initial-admin-secret -o yaml

The output will include an encrypted password, for example:

apiVersion: v1
data:
  password: TU1DaWRNQVJXNWJ3S1FBNA==
kind: Secret
...

Copy the encrypted value and decode it:

$ echo TU1DaWRNQVJXNWJ3S1FBNA== | base64 --decode

Next, forward port 443 of the argocd-server service to port 8080 of your local machine:

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

Example output:

Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080

This process will occupy the terminal session. Open your browser and visit:

http://127.0.0.1:8080

On the login page, enter admin as the username, paste the decoded password, and click Sign In. If the credentials are valid, you will be redirected to the Argo CD dashboard.

Note: The Argo CD dashboard remains accessible only while the port forwarding session is active. Press Ctrl + C in the terminal to stop port forwarding.

Optional: Access Argo CD Using the CLI Tool

Argo CD also provides a command-line tool that allows you to deploy applications and manage additional tasks such as syncing, refreshing, and pausing applications. Keep the port forwarding command from the previous section running in one terminal and open a new terminal to follow these steps:

Download the latest Argo CD CLI tool using wget:

$ wget https://github.com/argoproj/argo-cd/releases/download/v2.7.4/argocd-linux-amd64

The above command installs version 2.7.4. You can always check the official GitHub repository for the latest release in the Assets section.

Move the downloaded binary to the global /usr/local/bin/ directory:

$ sudo mv argocd-linux-amd64 /usr/local/bin/argocd

Make the binary executable:

$ sudo chmod +x /usr/local/bin/argocd

Login to the Argo CD server with the CLI tool:

$ argocd login localhost:8080

Accept the certificate warning, then enter the username admin and the decoded password:

WARNING: server certificate had error: x509: certificate signed by unknown authority. Proceed insecurely (y/n)? y
Username: admin
Password: 
'admin:login' logged in successfully
Context 'localhost:8080' updated

For security reasons, change the default password:

$ argocd account update-password

You will be asked for your current password, a new strong password, and confirmation of the new one.

Deploy Argo CD Applications

Applications in Argo CD can be created and deployed via YAML manifests, the UI, or the CLI. Below, you will deploy one application using a YAML manifest file and another via the UI.

Creating and Deploying an Application Using a YAML Manifest File

Create a new YAML file:

$ nano argocd-app.yaml

Add this configuration:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argo-application
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.com/jasmine.harit/argocd-app-config.git
    targetRevision: HEAD
    path: dev
  destination: 
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    syncOptions:
    - CreateNamespace=true
    automated:
      selfHeal: true
      prune: true

Save and exit the editor, then apply the configuration:

$ kubectl apply -f argocd-app.yaml

Verify deployment status:

$ kubectl get app -n argocd

Example output:

NAME               SYNC STATUS   HEALTH STATUS
argo-application   Synced        Healthy

You can also verify deployment with the CLI:

$ argocd app list

Example output:

NAME                     CLUSTER                         NAMESPACE  PROJECT  STATUS  HEALTH   SYNCPOLICY  CONDITIONS       REPO                                                    PATH  TARGET
argocd/argo-application  https://kubernetes.default.svc  myapp      default  Synced  Healthy  Auto-Prune        https://gitlab.com/jasmine.harit/argocd-app-config.git  dev   HEAD

Get more details about the application:

$ argocd app get argo-application

Sample output:

Name:               argocd/argo-application
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          myapp
URL:                https://localhost:8080/applications/argo-application
Repo:               https://gitlab.com/jasmine.harit/argocd-app-config.git
Target:             HEAD
Path:               dev
SyncWindow:         Sync Allowed
Sync Policy:        Automated (Prune)
Sync Status:        Synced to HEAD (9c92bf8)
Health Status:      Healthy

GROUP  KIND        NAMESPACE  NAME           STATUS   HEALTH   HOOK  MESSAGE
       Namespace              myapp          Running  Synced         namespace/myapp created
       Service     myapp      myapp-service  Synced   Healthy        service/myapp-service created
apps   Deployment  myapp      myapp1         Synced   Healthy        deployment.apps/myapp1 created

Refresh your browser session at http://127.0.0.1:8080 to see the deployed application.

Create and Deploy Applications Using the Dashboard and CLI Tool

Open the Argo CD UI dashboard. Click NEW APP to open the application configuration screen.

• General Configuration: Enter the application name, project, and sync policy.
• Source Section: Provide repository URL, revision, and path. For example, use the argocd-example-apps repository and select the helm-guestbook application in the Path.
• Destination Section: Enter your cluster URL and namespace. Click CREATE to deploy the application.

When deployment completes, the Argo CD Guestbook application will appear in the dashboard.

Verify its status using the CLI:

$ argocd app get guestbook

Sample output:

Name:               argocd/guestbook
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          argocd
URL:                https://argocd.example.com/applications/guestbook
Repo:               https://github.com/argoproj/argocd-example-apps.git
Target:             HEAD
Path:               helm-guestbook
SyncWindow:         Sync Allowed
Sync Policy:        
Sync Status:        OutOfSync from HEAD (4773b9f)
Health Status:      Missing

GROUP  KIND        NAMESPACE  NAME                      STATUS     HEALTH   HOOK  MESSAGE
       Service     argocd     guestbook-helm-guestbook  OutOfSync  Missing        
apps   Deployment  argocd     guestbook-helm-guestbook  OutOfSync  Missing 

The application is deployed but appears OutOfSync. To synchronize it, run:

$ argocd app sync guestbook

This command retrieves the required manifests from the repository and applies them via kubectl. On the Argo CD dashboard, confirm that the application is healthy. Click the application entry to see more details.

Secure Argo CD with TLS Encryption

This section explains how to expose your Argo CD server through an Nginx Ingress controller, secured with TLS encryption.

Install the Nginx Ingress controller in your cluster:

$ helm install my-ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx --create-namespace

This installs the Nginx Ingress controller in the ingress-nginx namespace and prefixes its resources with my-ingress-nginx-.

Check the Ingress services to obtain the LoadBalancer IP address:

$ kubectl get services -n ingress-nginx

Example output:

NAME                                    TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)                      AGE
my-ingress-nginx-controller             LoadBalancer   10.97.77.219   192.0.2.10     80:31808/TCP,443:30834/TCP   5m50s
my-ingress-nginx-controller-admission   ClusterIP      10.108.64.48            443/TCP                      5m50s

Note the EXTERNAL-IP value of the my-ingress-nginx-controller service and create a DNS A record for your domain (e.g., argo.example.com).

Note: It may take a while before the service receives its external IP. Until then, the value will display as <pending>.

Next, install cert-manager:

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.2/cert-manager.yaml

This command installs version 1.17.2 of cert-manager in the cert-manager namespace. Check the official releases page for the latest version.

Create a manifest file for an Issuer resource:

$ nano issuer.yaml

Add the following content:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: tls-certificate-issuer
  namespace: default
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-private-key
    solvers:
      - http01:
          ingress:
            class: nginx

Replace admin@example.com with your own email address, otherwise the Issuer will fail. Save and close the file.

Now create a manifest file for the Ingress resource of the argocd-server service:

$ nano ingress.yaml

Add the following configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-argocd
  namespace: argocd
  annotations:
    cert-manager.io/issuer: tls-certificate-issuer
spec:
  ingressClassName: nginx
  rules:
  - host: argo.example.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: argocd-server
            port:
              number: 80
  tls:
  - hosts:
      - argo.example.com
    secretName: argocd-tls

Save and exit the file.

Check the TLS certificate status:

$ kubectl get certificate -n argocd

Example output:

NAME         READY   SECRET       AGE
argocd-tls   False   argocd-tls   5m43s

After a while, the certificate status will change to True.

To confirm the configuration, open your browser and visit: https://argo.example.com.

Conclusion

You have now installed Argo CD on a Kubernetes cluster and learned how to deploy applications using the Argo CD UI, CLI, and YAML manifests. For further details, refer to the official Argo CD documentation.