Skip to main content

​
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.
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:
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}'
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.