Quickstart Guide

Get started with Argo CD in minutes - install, deploy your first application, and sync manifests from Git

Overview

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. This quickstart guide will walk you through installing Argo CD, accessing the UI and CLI, and deploying your first application from a Git repository.

This guide assumes you have:

• A running Kubernetes cluster
• kubectl installed and configured
• A kubeconfig file (default location: ~/.kube/config)
• CoreDNS enabled (for microk8s: microk8s enable dns && microk8s stop && microk8s start)

Installation

1. Install Argo CD

   Create the argocd namespace and install Argo CD using the official manifests:

   kubectl create namespace argocd
   kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
   

   This creates all Argo CD services and application resources in the argocd namespace.

   Why --server-side --force-conflicts?

   The --server-side flag is required because some Argo CD CRDs (like ApplicationSet) exceed the 262KB annotation size limit imposed by client-side kubectl apply. Server-side apply avoids this limitation by not storing the last-applied-configuration annotation.

   The --force-conflicts flag allows the apply operation to take ownership of fields that may have been previously managed by other tools.

   The installation manifests include ClusterRoleBinding resources that reference the argocd namespace. If you’re installing into a different namespace, update the namespace reference in the manifests.

   For production use, pin to a specific version:

   kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.2.0/manifests/install.yaml
   
2. Install Argo CD CLI

   Download and install the Argo CD CLI to interact with Argo CD from your terminal.

   macOS (Homebrew)

   brew install argocd
   

   Verify the installation:

   argocd version --client
   
3. Access Argo CD

   By default, the Argo CD API server is not exposed externally. Choose one of the following methods to access it:

   Port Forwarding (Recommended for Testing)

   Use kubectl port-forward to access the API server locally:

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

   Access the UI at: https://localhost:8080

   Service Type LoadBalancer

   Expose the service with a LoadBalancer (requires cloud provider support):

   kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'
   

   Get the external IP:

   kubectl get svc argocd-server -n argocd -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'
   

   Ingress

   For production environments, configure an Ingress resource. See the Argo CD Ingress documentation for detailed configuration.

4. Login to Argo CD

   Retrieve the initial admin password:

   argocd admin initial-password -n argocd
   

   The password is auto-generated and stored in the argocd-initial-admin-secret secret.

   Login using the CLI:

   argocd login <ARGOCD_SERVER>
   

   Use username admin and the password from the previous command.

   Delete the argocd-initial-admin-secret after changing your password:

   kubectl delete secret argocd-initial-admin-secret -n argocd
   

   The secret serves no purpose after the initial login and can be safely deleted.

   Change the admin password:

   argocd account update-password
   

   If the CLI can’t directly access the API server, use port forwarding:

   • Add --port-forward-namespace argocd to each command, or
   • Set ARGOCD_OPTS environment variable: export ARGOCD_OPTS='--port-forward-namespace argocd'
5. Create Your First Application

   Deploy the example guestbook application from the Argo CD demo repository.

   Set the default namespace:

   kubectl config set-context --current --namespace=argocd
   

   Create the application using the CLI:

   argocd app create guestbook \
     --repo https://github.com/argoproj/argocd-example-apps.git \
     --path guestbook \
     --dest-server https://kubernetes.default.svc \
     --dest-namespace default
   

   Or create using a declarative YAML manifest:

   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: guestbook
     namespace: argocd
   spec:
     project: default
     source:
       repoURL: https://github.com/argoproj/argocd-example-apps.git
       targetRevision: HEAD
       path: guestbook
     destination:
       server: https://kubernetes.default.svc
       namespace: default
   

   Apply the manifest:

   kubectl apply -f application.yaml
   
6. Sync the Application

   View the application status:

   argocd app get guestbook
   

   Output:

   Name:               guestbook
   Server:             https://kubernetes.default.svc
   Namespace:          default
   URL:                https://10.97.164.88/applications/guestbook
   Repo:               https://github.com/argoproj/argocd-example-apps.git
   Target:             HEAD
   Path:               guestbook
   Sync Policy:        <none>
   Sync Status:        OutOfSync from (1ff8a67)
   Health Status:      Missing
   
   GROUP  KIND        NAMESPACE  NAME          STATUS     HEALTH
   apps   Deployment  default    guestbook-ui  OutOfSync  Missing
          Service     default    guestbook-ui  OutOfSync  Missing
   

   The application is initially OutOfSync because resources haven’t been deployed yet.

   Sync (deploy) the application:

   argocd app sync guestbook
   

   This retrieves manifests from Git and performs a kubectl apply. View the deployed resources:

   argocd app get guestbook
   

   You can also sync from the UI:

   1. Navigate to the Applications page
   2. Click the Sync button on the guestbook application
   3. Click Synchronize in the panel

Next Steps

Core Concepts

Learn about Applications, sync status, health checks, and GitOps principles

Architecture

Understand Argo CD’s component architecture and how they work together

Configure Auto-Sync

Enable automated synchronization for continuous deployment

Multi-Cluster Setup

Register external clusters for multi-cluster deployments

Optional: Register External Clusters

To deploy applications to external clusters (not the cluster where Argo CD is running):

# List available contexts
kubectl config get-contexts -o name

# Register a cluster
argocd cluster add docker-desktop

This installs a ServiceAccount (argocd-manager) in the target cluster’s kube-system namespace and binds it to an admin-level ClusterRole.

When deploying to the same cluster where Argo CD runs, use https://kubernetes.default.svc as the destination server. No cluster registration is needed.