Argo CD doesn’t just deploy your Kubernetes manifests; it actively synchronizes them with your Git repository, ensuring your cluster state always matches your desired state.
Let’s get Argo CD running on a Kubernetes cluster. We’ll start with a simple installation using kubectl.
First, create a namespace for Argo CD:
kubectl create namespace argocd
Now, apply the official Argo CD installation manifest:
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
This command downloads the manifest and applies it to your cluster. It will create all the necessary Deployments, Services, Custom Resource Definitions (CRDs), and other resources for Argo CD to function.
After a few minutes, you can check the status of the Argo CD pods:
kubectl get pods -n argocd
You should see pods like argocd-application-controller, argocd-dex-server, argocd-notifications-controller, argocd-redis, and argocd-server all in a Running state.
To access the Argo CD API server, you need to expose it. For local testing, port-forwarding is the easiest way:
kubectl port-forward svc/argocd-server -n argocd 8080:443
This command forwards traffic from your local machine’s port 8080 to the Argo CD server’s port 443.
The default administrator username is admin. To get the initial password, you need to retrieve the secret that Argo CD creates:
kubectl -n argocd get secret argocd-initial-secrets -o jsonpath="{.data.admin-password}" | base64 -d
This command fetches the argocd-initial-secrets secret, extracts the admin-password field, and decodes it from base64. Copy the output; this is your initial password.
You can now access the Argo CD UI by navigating to https://localhost:8080 in your web browser. You’ll likely see a certificate warning because Argo CD uses a self-signed certificate by default. Accept the risk to proceed. Log in with the username admin and the password you just retrieved.
The core concept behind Argo CD is its declarative, GitOps-driven approach. You define your desired application state – which container images to run, how many replicas, environment variables, etc. – in Kubernetes manifests (YAML files). These manifests are stored in a Git repository. Argo CD then continuously monitors this Git repository and compares the desired state with the actual state of your applications running in Kubernetes. If there’s a drift (meaning the live state doesn’t match what’s in Git), Argo CD will automatically synchronize them.
Let’s create a simple application. First, ensure you have a Git repository with some Kubernetes manifests. For this example, we’ll use a public Nginx deployment. A common pattern is to have a dedicated directory in your Git repo for each application.
# my-nginx-app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.25.3 # Use a specific version for reproducibility
ports:
- containerPort: 80
Commit this file to a Git repository.
Now, back in the Argo CD UI, click "New App" and fill in the details:
- Application Name:
my-nginx - Project:
default - Sync Policy:
Manual(for now, we’ll change this later) - Source:
- Repository URL: Your Git repository URL (e.g.,
https://github.com/yourusername/your-repo.git) - Revision:
HEAD(or a specific branch/tag) - Path: The directory within your repository containing
my-nginx-app.yaml(e.g.,apps/nginx/)
- Repository URL: Your Git repository URL (e.g.,
- Destination:
- Cluster URL:
https://kubernetes.default.svc(this refers to your current cluster) - Namespace:
default(or wherever you want to deploy Nginx)
- Cluster URL:
Click "Create". You’ll see your new application listed. Initially, it will show a "OutOfSync" status. Click on the application name. You’ll see the detected resources. Click the "Sync" button. Argo CD will apply the manifests from your Git repository to your Kubernetes cluster. The status should change to "Synced".
The most potent way to leverage Argo CD is through its automated sync policies. Instead of manually clicking "Sync," you can configure Argo CD to automatically reconcile differences. In the application’s settings, change the "Sync Policy" to Automated. You can then choose Prune Resources (to delete resources no longer defined in Git) and Self-Heal (to automatically revert any manual changes made directly to the cluster). This ensures your cluster state is always what’s defined in Git, without human intervention.
When you’re ready to move beyond local port-forwarding, you’ll typically expose the argocd-server service using an Ingress controller. You’ll need to configure your Ingress resource to point to the argocd-server service and set up TLS certificates.
The next hurdle you’ll likely face is managing multiple environments (dev, staging, prod) and securing access for different teams.