ArgoCD Installation and Configuration

Setting up ArgoCD in a Kubernetes cluster requires careful planning and configuration. This guide walks through installation methods, initial configuration, and essential security setup to prepare ArgoCD for production use.

Installation Methods

ArgoCD can be installed using several approaches, each suited to different environments and requirements.

Kubectl Installation

The simplest installation method uses kubectl to apply ArgoCD manifests directly:

# Create argocd namespace
kubectl create namespace argocd

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

# Verify installation
kubectl get pods -n argocd

This method deploys all ArgoCD components with default configurations. The installation includes the API server, repository server, application controller, and supporting services.

Helm Chart Installation

For more control over configuration, use the official Helm chart:

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

# Create values file for customization
cat <<EOF > argocd-values.yaml
server:
  replicas: 2
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

repoServer:
  replicas: 2
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 1Gi

controller:
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 2Gi
EOF

# Install ArgoCD with custom values
helm install argocd argo/argo-cd \
  --namespace argocd \
  --create-namespace \
  --values argocd-values.yaml

The Helm chart approach provides better control over resource limits, replica counts, and advanced configuration options.

GitOps Installation

For a fully GitOps approach, bootstrap ArgoCD to manage itself:

# argocd-installation.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://argoproj.github.io/argo-helm
    chart: argo-cd
    targetRevision: 5.51.0
    helm:
      values: |
        server:
          replicas: 2
        repoServer:
          replicas: 2
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

This creates an ArgoCD Application that manages ArgoCD itself, enabling self-service upgrades through Git commits.

graph TD
    A[Installation Method Selection] --> B{Environment Type}
    B -->|Quick Testing| C[kubectl Install]
    B -->|Production with Customization| D[Helm Install]
    B -->|Full GitOps| E[Self-Managing ArgoCD]
    
    C --> F[Default Configuration]
    D --> G[Custom Values File]
    E --> H[ArgoCD Application]
    
    F --> I[ArgoCD Running]
    G --> I
    H --> I
    
    I --> J[Access Configuration]
    
    style E fill:#e1f5ff
    style H fill:#e1f5ff

Accessing ArgoCD

After installation, access the ArgoCD UI and CLI through several methods.

Port Forwarding

For quick access during testing or development:

# Forward API server port to localhost
kubectl port-forward svc/argocd-server -n argocd 8080:443

# Access UI at https://localhost:8080
# Login: admin
# Password retrieved with:
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

Port forwarding provides immediate access without exposing ArgoCD externally, suitable for local development and initial configuration.

Ingress Configuration

For production environments, expose ArgoCD through an Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 443
  tls:
  - hosts:
    - argocd.example.com
    secretName: argocd-tls-cert

The Ingress exposes ArgoCD at a specific domain with TLS termination, enabling team access through a stable URL.

LoadBalancer Service

In cloud environments, convert the ArgoCD server service to LoadBalancer type:

# Patch service to LoadBalancer type
kubectl patch svc argocd-server -n argocd \
  -p '{"spec": {"type": "LoadBalancer"}}'

# Get external IP
kubectl get svc argocd-server -n argocd

This assigns a cloud provider load balancer IP address, providing direct external access without requiring Ingress configuration.

sequenceDiagram
    participant User
    participant Ingress
    participant Service
    participant Pod
    
    User->>Ingress: HTTPS Request (argocd.example.com)
    Ingress->>Ingress: TLS Termination
    Ingress->>Service: Forward to argocd-server
    Service->>Pod: Route to ArgoCD API Server
    Pod->>Pod: Process Request
    Pod->>Service: Response
    Service->>Ingress: Response
    Ingress->>User: HTTPS Response

Initial Configuration

After installation, configure essential settings for secure operation.

Changing Admin Password

The default admin password should be changed immediately:

# Login with initial password
argocd login argocd.example.com --username admin

# Change password
argocd account update-password

# Delete initial secret (optional but recommended)
kubectl -n argocd delete secret argocd-initial-admin-secret

Adding Git Repositories

Register Git repositories containing application manifests:

# Add public repository (HTTPS)
argocd repo add https://github.com/organization/k8s-manifests

# Add private repository with SSH key
argocd repo add git@github.com:organization/k8s-manifests.git \
  --ssh-private-key-path ~/.ssh/id_rsa

# Add private repository with username/password
argocd repo add https://github.com/organization/k8s-manifests \
  --username git-user \
  --password personal-access-token

Repository credentials are stored encrypted in Kubernetes secrets, enabling secure access to private repositories.

Adding Target Clusters

Add external Kubernetes clusters to deploy applications across multiple environments:

# Add cluster using kubeconfig context
argocd cluster add prod-cluster-context

# List registered clusters
argocd cluster list

# Get cluster details
argocd cluster get https://prod-cluster.example.com

Each cluster registration stores connection credentials and enables multi-cluster deployments from a single ArgoCD instance.

Security Configuration

Proper security configuration is critical for production ArgoCD deployments.

RBAC Configuration

ArgoCD uses Projects and RBAC policies to control access. Create a custom RBAC policy:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |
    # Grant developers read-only access
    p, role:developer, applications, get, */*, allow
    p, role:developer, applications, sync, */*, deny
    
    # Grant operators full access to specific projects
    p, role:operator, applications, *, production/*, allow
    p, role:operator, repositories, *, *, allow
    
    # Map groups to roles
    g, dev-team, role:developer
    g, ops-team, role:operator
  
  policy.default: role:readonly

RBAC policies define who can view, sync, delete, or modify applications based on project membership and user roles.

SSO Integration

Integrate with identity providers using Dex (included with ArgoCD):

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  url: https://argocd.example.com
  
  dex.config: |
    connectors:
    - type: oidc
      id: okta
      name: Okta
      config:
        issuer: https://company.okta.com
        clientID: argocd-client-id
        clientSecret: $dex.okta.clientSecret
        redirectURI: https://argocd.example.com/api/dex/callback
        
    - type: github
      id: github
      name: GitHub
      config:
        clientID: github-oauth-app-id
        clientSecret: $dex.github.clientSecret
        orgs:
        - name: organization-name

SSO integration centralizes authentication, eliminating the need for separate ArgoCD credentials and enabling group-based access control.

Network Policies

Restrict network traffic to ArgoCD components:

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

Network policies implement defense-in-depth by limiting communication paths between components and external access points.

Resource Management

Configure resource limits for stable performance under load:

# controller resource limits
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: argocd-application-controller
  namespace: argocd
spec:
  template:
    spec:
      containers:
      - name: application-controller
        resources:
          requests:
            cpu: 500m
            memory: 1Gi
          limits:
            cpu: 2000m
            memory: 4Gi
        env:
        - name: ARGOCD_RECONCILIATION_TIMEOUT
          value: "180s"
        - name: ARGOCD_REPO_SERVER_TIMEOUT_SECONDS
          value: "60"

Resource configuration prevents component crashes under heavy load and ensures predictable performance when managing many applications.

High Availability Setup

For production environments, configure ArgoCD for high availability:

# Multi-replica configuration
server:
  replicas: 3
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: argocd-server
        topologyKey: kubernetes.io/hostname

repoServer:
  replicas: 3
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: argocd-repo-server
        topologyKey: kubernetes.io/hostname

controller:
  replicas: 1  # Application controller must be singleton

High availability configuration ensures ArgoCD remains operational during node failures, with anti-affinity rules distributing replicas across different nodes.

graph LR
    subgraph Node1
        A1[API Server Pod 1]
        R1[Repo Server Pod 1]
    end
    
    subgraph Node2
        A2[API Server Pod 2]
        R2[Repo Server Pod 2]
    end
    
    subgraph Node3
        A3[API Server Pod 3]
        R3[Repo Server Pod 3]
        C[Controller Pod]
    end
    
    LB[Load Balancer] --> A1
    LB --> A2
    LB --> A3
    
    A1 --> R1
    A2 --> R2
    A3 --> R3
    
    style LB fill:#fff4e6
    style C fill:#ffe6e6

Common Pitfalls

Insufficient Resources: The application controller requires adequate CPU and memory when managing many applications. Monitor resource usage and adjust limits based on scale.

Missing Repository Access: Private repositories require proper credentials. Always test repository connectivity with argocd repo list after adding credentials.

Network Policy Conflicts: Overly restrictive network policies can prevent ArgoCD components from communicating. Test connectivity between components when implementing policies.

Single Replica Controllers: Running multiple application controller replicas causes conflicts. The controller must be a singleton (single replica).

Key Takeaways