ArgoCD Setup & Configuration

ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes. It provides a web UI, CLI, and API for managing applications deployed to Kubernetes clusters. ArgoCD continuously monitors Git repositories and automatically syncs the desired state to your clusters.

What is ArgoCD?

ArgoCD is a CNCF incubating project that implements GitOps principles for Kubernetes. It:

Monitors Git repositories for changes
Compares desired state (Git) with actual state (cluster)
Automatically or manually syncs applications
Provides visualization of application status
Supports multiple sources (Git, Helm, Kustomize)

ArgoCD Architecture

graph TB A[Git Repository] --> B[Repo Server] B --> C[Application Controller] C --> D[Kubernetes API] D --> E[Cluster Resources] F[User] --> G[ArgoCD UI] F --> H[ArgoCD CLI] G --> I[API Server] H --> I I --> C C --> J[Status Updates] J --> I I --> G style B fill:#e1f5ff style C fill:#e8f5e9 style I fill:#fff4e1 style G fill:#f3e5f5

Core Components

API Server - REST API and gRPC server, exposes UI and CLI
Repository Server - Maintains Git repository caches, generates manifests
Application Controller - Monitors applications, compares states, syncs resources
Redis - Caches application state and repository data

Installation

Prerequisites

Kubernetes cluster (v1.19+)
kubectl configured to access your cluster
Cluster admin permissions (for installation)

Method 1: Using kubectl (Quick Start)

The simplest way to install ArgoCD:

# Create namespace
kubectl create namespace argocd

# Install ArgoCD
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for all pods to be ready
kubectl wait --for=condition=ready pod --all -n argocd --timeout=300s

This installs:

ArgoCD application controller
API server
Repository server
Redis
Application set controller
Notifications controller

Method 2: Using Helm (Recommended for Production)

Helm provides better control over configuration:

# Add ArgoCD Helm repository
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

# Install ArgoCD
helm install argocd argo/argo-cd \
  --namespace argocd \
  --create-namespace \
  --set server.service.type=LoadBalancer

Method 3: Using ArgoCD Operator

For advanced scenarios, use the ArgoCD Operator:

# Install ArgoCD Operator
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-operator/master/deploy/crds/argoproj.io_argocds_crd.yaml
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-operator/master/deploy/operator.yaml

# Create ArgoCD instance
kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: ArgoCD
metadata:
  name: argocd
  namespace: argocd
spec:
  server:
    service:
      type: LoadBalancer
EOF

Initial Access

Get Admin Password

ArgoCD creates an initial admin user. Retrieve the password:

# Get admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

Note: The secret is automatically deleted after first login. Change the password immediately.

Access ArgoCD UI

Port Forwarding (Development)

# Port forward to access UI
kubectl port-forward svc/argocd-server -n argocd 8080:443

# Access at https://localhost:8080
# Username: admin
# Password: <from previous step>

LoadBalancer (Production)

If you installed with LoadBalancer service type:

# Get LoadBalancer address
kubectl get svc argocd-server -n argocd

# Access at https://<EXTERNAL-IP>

Ingress (Production)

Configure Ingress for external access:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-password-file: /etc/nginx/ssl-password
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
spec:
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80
  tls:
  - hosts:
    - argocd.example.com
    secretName: argocd-secret

Install ArgoCD CLI

macOS

brew install argocd

Linux

# Download latest version
VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')

# Install
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

Windows

# Using Chocolatey
choco install argocd

# Or download from GitHub releases

# Login to ArgoCD server
argocd login <ARGOCD_SERVER> --username admin --password <PASSWORD>

# Or use port-forward
argocd login localhost:8080 --username admin --password <PASSWORD>

Configuration

Change Admin Password

# Via CLI
argocd account update-password --account admin

# Via UI
# User Info → Update Password

Configure Repository Access

ArgoCD needs credentials to access your Git repositories.

Using Username/Password

argocd repo add https://github.com/your-org/your-repo \
  --username <USERNAME> \
  --password <PASSWORD>

Using SSH Key

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "argocd" -f ~/.ssh/argocd

# Add public key to Git provider (GitHub, GitLab, etc.)

# Add repository with SSH
argocd repo add [email protected]:your-org/your-repo.git \
  --ssh-private-key-path ~/.ssh/argocd

Using Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: repo-credentials
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  password: <PASSWORD>
  username: <USERNAME>

Using Access Token (GitHub)

# Create GitHub personal access token with repo scope
argocd repo add https://github.com/your-org/your-repo \
  --username <GITHUB_USERNAME> \
  --password <GITHUB_TOKEN>

Configure Cluster Access

ArgoCD can manage multiple clusters.

Add External Cluster

# Get cluster credentials
argocd cluster add <CONTEXT_NAME>

# Or manually
argocd cluster add <CONTEXT_NAME> \
  --name production \
  --server https://prod-cluster.example.com:6443

In-Cluster Access

ArgoCD automatically has access to the cluster it’s installed in via the argocd ServiceAccount.

RBAC Configuration

ArgoCD supports role-based access control for fine-grained permissions.

Built-in Roles

role:readonly - Read-only access
role:admin - Full access
role:org-admin - Organization admin (multi-tenancy)

Create Custom Role

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |
    # Policy rules
    p, role:developer, applications, get, */*, allow
    p, role:developer, applications, sync, */*, allow
    p, role:developer, applications, create, */*, allow
    p, role:developer, applications, update, */*, allow
    p, role:developer, applications, delete, */*, allow
    
    # Role bindings
    g, developers, role:developer

Assign Roles to Users

# Via CLI
argocd account can-i <ACTION> <RESOURCE> --account <USERNAME>

# Update user role
argocd account update-password --account <USERNAME>

OIDC Integration

Configure OIDC for SSO:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  url: https://argocd.example.com
  oidc.config: |
    name: Okta
    issuer: https://dev-123456.okta.com
    clientId: <CLIENT_ID>
    clientSecret: $oidc.okta.clientSecret
    requestedScopes: ["openid", "profile", "email", "groups"]

Create secret for client secret:

apiVersion: v1
kind: Secret
metadata:
  name: argocd-secret
  namespace: argocd
type: Opaque
stringData:
  oidc.okta.clientSecret: <CLIENT_SECRET>

High Availability Setup

For production, configure HA:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-application-controller
  namespace: argocd
spec:
  replicas: 2  # Multiple replicas
  template:
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                  - argocd-application-controller
              topologyKey: kubernetes.io/hostname

Redis HA

Use Redis HA for production:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  redis.server: argocd-redis-ha:6379

Install Redis HA:

helm install argocd-redis-ha argo/redis-ha \
  --namespace argocd

Security Best Practices

1. Change Default Password

Always change the admin password immediately after installation.

2. Use RBAC

Configure RBAC to limit access based on roles and responsibilities.

3. Secure Repository Credentials

Use SSH keys instead of passwords when possible
Rotate credentials regularly
Use separate credentials per repository
Store secrets in external secret management (e.g., Vault)

4. Enable TLS

Always use TLS for ArgoCD server:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  server.insecure: "false"

5. Network Policies

Restrict network access to ArgoCD components:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: argocd-server
  namespace: argocd
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: argocd-server
  policyTypes:
  - Ingress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: argocd
    ports:
    - protocol: TCP
      port: 8080

6. Audit Logging

Enable audit logging:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  server.log.level: info
  server.log.format: json

7. Resource Limits

Set resource limits to prevent resource exhaustion:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  controller.resources.limits.cpu: "1000m"
  controller.resources.limits.memory: "2Gi"
  controller.resources.requests.cpu: "100m"
  controller.resources.requests.memory: "256Mi"

Troubleshooting

Pods Not Starting

# Check pod status
kubectl get pods -n argocd

# Check logs
kubectl logs -n argocd <POD_NAME>

# Check events
kubectl describe pod -n argocd <POD_NAME>

Cannot Access UI

# Check service
kubectl get svc -n argocd argocd-server

# Check ingress
kubectl get ingress -n argocd

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

Repository Connection Issues

# Test repository connection
argocd repo get <REPO_URL>

# Check repository server logs
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-repo-server

Sync Failures

# Check application status
argocd app get <APP_NAME>

# Check sync history
argocd app history <APP_NAME>

# Get application details
argocd app get <APP_NAME> --show-operation

Verification

After installation, verify everything works:

# Check all pods are running
kubectl get pods -n argocd

# Check ArgoCD version
argocd version --client
argocd version --server

# List repositories (should be empty initially)
argocd repo list

# List applications (should be empty initially)
argocd app list

Next Steps

Once ArgoCD is installed and configured:

Add Git Repository - Connect your repository with Kubernetes manifests
Create Application - Define your first ArgoCD Application
Configure Sync Policies - Set up automated or manual sync
Set Up Projects - Organize applications with Projects

See the Applications & Projects guide to get started with your first application.