DEV Community

Cover image for Setting Up Argo CD on Kubernetes
Vultr profile image Sanskriti Harmukh
Sanskriti Harmukh for Vultr

Posted on with Aashish Chaurasiya Originally published at docs.vultr.com

Setting Up Argo CD on Kubernetes

#gitops #devops #kubernetes #argocd

Argo CD is a Kubernetes-native, declarative GitOps tool for deploying applications at scale. It pulls application manifests directly from a Git repository and syncs them to a Kubernetes cluster, supports YAML, Kustomize, Jsonnet, and Helm, and ships with a built-in web UI for monitoring sync status and application health. This guide installs Argo CD on a Kubernetes cluster, sets up access to its web UI and CLI, and deploys applications through both a YAML manifest and the Argo CD dashboard. By the end, you'll have Argo CD running behind TLS with two applications deployed and synced through it.

Before you begin, you'll need access to a Kubernetes cluster with at least three nodes, a Linux-based local or remote instance to test the Argo CD CLI, the kubectl CLI installed and configured on your local machine, the Helm client installed locally, and a domain name for your Argo CD installation (for example, argo.example.com).

1. Install Argo CD

1. Create a namespace for Argo CD:

$ kubectl create namespace argocd
Enter fullscreen mode Exit fullscreen mode

2. Create a new directory for Argo CD in your home directory:

$ mkdir ~/argocd
Enter fullscreen mode Exit fullscreen mode

3. Switch to the argocd directory:

$ cd ~/argocd
Enter fullscreen mode Exit fullscreen mode

4. Clone the Argo CD Helm repository:

$ git clone https://github.com/argoproj/argo-helm.git
Enter fullscreen mode Exit fullscreen mode

5. Navigate to the argo-cd chart directory:

$ cd argo-helm/charts/argo-cd/
Enter fullscreen mode Exit fullscreen mode

6. Update Helm dependencies:

$ helm dependency up
Enter fullscreen mode Exit fullscreen mode

7. Install Argo CD into the argocd namespace using Helm:

$ helm install argocd . -f values.yaml -n argocd
Enter fullscreen mode Exit fullscreen mode

On success, you'll see metadata about the installation:

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

8. Verify that Argo CD is deployed to the argocd namespace:

$ kubectl get pods -n argocd
Enter fullscreen mode Exit fullscreen mode

The output should display pods with names starting with argocd-.

9. Check the running services and ports:

$ kubectl get services -n argocd
Enter fullscreen mode Exit fullscreen mode

Output:

NAME                               TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
...
argocd-server                      ClusterIP   10.101.247.167   <none>        80/TCP,443/TCP      53s
Enter fullscreen mode Exit fullscreen mode

The argocd-server service serves the Argo CD UI.

2. Access the Argo CD UI

The Argo CD UI isn't reachable from outside the cluster by default. Use port forwarding to expose it locally without exposing the service externally.

1. Extract the default admin password from the argocd-initial-admin-secret secret:

$ kubectl get secrets -n argocd argocd-initial-admin-secret -o yaml
Enter fullscreen mode Exit fullscreen mode

The encrypted password appears in the output:

apiVersion: v1
data:
  password: TU1DaWRNQVJXNWJ3S1FBNA==
kind: Secret
...
Enter fullscreen mode Exit fullscreen mode

Copy the encrypted password (TU1DaWRNQVJXNWJ3S1FBNA== above) for decoding.

2. Decode the password:

$ echo TU1DaWRNQVJXNWJ3S1FBNA== | base64 --decode
Enter fullscreen mode Exit fullscreen mode

3. Forward port 443 of the argocd-server service to port 8080 on your localhost:

$ kubectl port-forward svc/argocd-server -n argocd 8080:443
Enter fullscreen mode Exit fullscreen mode

Output:

Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
Enter fullscreen mode Exit fullscreen mode

This occupies your current terminal session.

4. Open the Argo CD UI in a browser:

http://127.0.0.1:8080
Enter fullscreen mode Exit fullscreen mode

5. Sign in with username admin and the decoded password. You can only access the dashboard while the port forward is active — press Ctrl + C in the terminal to end it.

Optional: Access Argo CD Using the CLI Tool

Keep the port forward from the previous step active in one terminal, then open a new terminal for the following steps.

1. Download the Argo CD CLI tool:

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

This installs version 2.7.4. Check the Assets section of the official releases page for the latest version.

2. Move the binary to /usr/local/bin/:

$ sudo mv argocd-linux-amd64 /usr/local/bin/argocd
Enter fullscreen mode Exit fullscreen mode

3. Grant execute permissions:

$ sudo chmod +x /usr/local/bin/argocd
Enter fullscreen mode Exit fullscreen mode

4. Log in to the Argo CD server:

$ argocd login localhost:8080
Enter fullscreen mode Exit fullscreen mode

Accept the server certificate, then enter 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:
Enter fullscreen mode Exit fullscreen mode

On success:

'admin:login' logged in successfully
Context 'localhost:8080' updated
Enter fullscreen mode Exit fullscreen mode

5. Change the default admin password:

$ argocd account update-password
Enter fullscreen mode Exit fullscreen mode

You'll be prompted for your existing password, a new password, and confirmation.

3. Deploy Argo CD Applications

You can deploy Argo CD applications via a YAML manifest, the web UI, or the CLI.

Creating and Deploying an Application Using a YAML Manifest

1. Create a YAML file for the application:

$ nano argocd-app.yaml
Enter fullscreen mode Exit fullscreen mode

Add the following:

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
Enter fullscreen mode Exit fullscreen mode

Save and close the file.

2. Apply the configuration:

$ kubectl apply -f argocd-app.yaml
Enter fullscreen mode Exit fullscreen mode

3. Check the deployment status:

$ kubectl get app -n argocd
Enter fullscreen mode Exit fullscreen mode

Output:

NAME               SYNC STATUS   HEALTH STATUS
argo-application   Synced        Healthy
Enter fullscreen mode Exit fullscreen mode

You can also verify this with the CLI:

$ argocd app list
Enter fullscreen mode Exit fullscreen mode

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  <none>      https://gitlab.com/jasmine.harit/argocd-app-config.git  dev   HEAD
Enter fullscreen mode Exit fullscreen mode

4. Get detailed information about the application:

$ argocd app get argo-application
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

5. Refresh the web dashboard to see the deployed application.

Creating and Deploying an Application via the Dashboard and CLI

1. In the Argo CD UI, click NEW APP to open the Application configuration screen.

  • In GENERAL, define the application name, project, and sync policy.
  • In SOURCE, enter the repository path, revision, and URL — for example, the argocd-example-apps repository with the helm-guestbook application as the path.
  • In DESTINATION, enter your cluster URL and namespace.
  • Click CREATE to deploy the application.

2. Check the application status with the CLI:

$ argocd app get guestbook
Enter fullscreen mode Exit fullscreen mode

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:        <none>
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
Enter fullscreen mode Exit fullscreen mode

The application is deployed but OutOfSync. Sync it with:

$ argocd app sync guestbook
Enter fullscreen mode Exit fullscreen mode

This fetches the necessary manifests from the repository and applies them using kubectl.

3. On the web dashboard, verify the application's health status and click into it for more details.

4. Secure Argo CD with TLS Encryption

Expose the Argo CD server through the Nginx Ingress controller, terminated with TLS.

1. Install the Nginx Ingress controller on your cluster:

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

This installs the controller into a new ingress-nginx namespace, naming its resources my-ingress-nginx-*.

2. Check the Ingress service to get the load balancer IP address:

$ kubectl get services -n ingress-nginx
Enter fullscreen mode Exit fullscreen mode

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   <none>         443/TCP                      5m50s
Enter fullscreen mode Exit fullscreen mode

Note the EXTERNAL-IP of my-ingress-nginx-controller and create an A DNS record for your domain (e.g., argo.example.com) pointing to it with your DNS provider. It may take a few minutes for EXTERNAL-IP to populate — until then it shows as <pending>.

3. Install cert-manager:

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

This installs cert-manager v1.17.2 into the cert-manager namespace. Check the official releases page for the latest version.

4. Create a manifest for an Issuer resource:

$ nano issuer.yaml
Enter fullscreen mode Exit fullscreen mode

Add the following, replacing [email protected] with your email address (required for the Issuer to work):

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: [email protected]
    privateKeySecretRef:
      name: letsencrypt-private-key
    solvers:
      - http01:
          ingress:
            class: nginx
Enter fullscreen mode Exit fullscreen mode

Save and exit.

5. Create a manifest for the Ingress resource for the argocd-server service:

$ nano ingress.yaml
Enter fullscreen mode Exit fullscreen mode

Add the following:

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
Enter fullscreen mode Exit fullscreen mode

Save and exit.

6. Check the TLS certificate status:

$ kubectl get certificate -n argocd
Enter fullscreen mode Exit fullscreen mode

Output:

NAME         READY   SECRET       AGE
argocd-tls   False   argocd-tls   5m43s
Enter fullscreen mode Exit fullscreen mode

The status changes to True after a short wait.

7. Verify by visiting your domain (https://argo.example.com) in a browser.

Next Steps

  • Wire Argo CD into your CI pipeline to trigger automated syncs on every merge.
  • Configure RBAC and SSO (OIDC/SAML) for team access to the Argo CD dashboard.
  • Set up notifications (Slack, email) for sync and health status changes.
  • Explore App-of-Apps and ApplicationSets for managing multiple applications at scale.

For the full guide with additional tips, visit the original article on Vultr Docs.

Top comments (0)