Installing ArgoCD on Kubernetes: The Definitive Enterprise Guide

Quick Answer: What is the Best Way to Install ArgoCD in Production?

For enterprise production environments, the industry standard is to install ArgoCD using the official Argo Helm Chart configured in High Availability (HA) mode. This topology deploys a clustered Redis Sentinel pair, multiple stateless instances of the ArgoCD API Server and Repo Server, and leverages leader election for the Application Controller.

Once the initial Helm installation is complete, the setup should be immediately transitioned to a self-managed GitOps pattern (also known as bootstrapping), where ArgoCD manages its own Helm release and configuration via Git.

Introduction to ArgoCD Installation

Deploying ArgoCD in an enterprise environment requires moving far beyond the simple kubectl apply -f install.yaml quickstart command. In an enterprise setting, ArgoCD is the gatekeeper of your entire infrastructure and application state. A poorly configured ArgoCD installation can introduce massive security vulnerabilities, create single points of failure, lead to performance degradation, and cause catastrophic cascading outages across your Kubernetes clusters.

This guide provides an exhaustive, step-by-step walkthrough for installing ArgoCD on Kubernetes. We will cover architectural topologies, security hardening, high-availability configurations, multi-tenant RBAC, Single Sign-On (SSO) integration, and the "GitOps of GitOps" bootstrapping pattern.

What You Will Learn

• How to evaluate and choose the right ArgoCD installation topology (HA vs. Non-HA vs. Core).
• How to deploy ArgoCD using vanilla manifests and enterprise-grade Helm charts.
• How to configure high availability, including Redis Sentinel, replica distribution, and resource limits.
• How to implement the GitOps bootstrapping pattern to make ArgoCD self-managing.
• How to secure ArgoCD using TLS, Network Policies, and OIDC-based Single Sign-On (SSO).
• How to scale ArgoCD to manage hundreds of clusters and thousands of applications.

Prerequisites

Before proceeding with this guide, ensure your environment meets the following requirements:

• Kubernetes Cluster: A running Kubernetes cluster (v1.24 or higher) with administrative access (cluster-admin cluster role).
• Command Line Tools: Local installations of kubectl and helm (v3.x or higher).
• Domain Name & DNS: A valid domain name (e.g., argocd.example.com) with DNS records pointing to your Kubernetes Ingress controller or LoadBalancer.
• Ingress Controller: An ingress controller (such as ingress-nginx or AWS Load Balancer Controller) installed and configured in your cluster.
• Git Repository: A private or public Git repository (GitHub, GitLab, or Bitbucket) to hold your GitOps manifests.

If you are new to GitOps concepts, we highly recommend reading our previous lessons: Introduction to GitOps and ArgoCD Architecture Deep Dive.

ArgoCD Installation Topologies

ArgoCD can be deployed in several topologies depending on your security requirements, cluster scale, and operational model. Understanding these topologies is critical for making correct architectural decisions.

ArgoCD Component Architecture

Before deploying, let's look at how the components interact in a High Availability (HA) environment. The following diagram illustrates the network and control flow between the high-availability components:

+---------------------------------------------------------------------------------+
|                                 Kubernetes Cluster                              |
|                                                                                 |
|   +-----------------------+       +-------------------+                         |
|   |  Ingress Controller   | ----> |   argocd-server   | (Stateless Replicas)    |
|   +-----------------------+       +---------+---------+                         |
|                                             |                                   |
|                                             v                                   |
|   +-----------------------+       +-------------------+                         |
|   |  argocd-repo-server   | <---- |    Redis Master   |                         |
|   |  (Stateless Replicas) |       +---------+---------+                         |
|   +-----------+-----------+                 |                                   |
|               |                             v                                   |
|               |                   +-------------------+                         |
|               |                   |   Redis Sentinel  | (HA Failover Monitor)   |
|               v                   +---------+---------+                         |
|   +-----------------------+                 ^                                   |
|   |  argocd-app-controller| ----------------+                                   |
|   |  (Leader Election)    |                                                     |
|   +-----------+-----------+                                                     |
|               |                                                                 |
|               v                                                                 |
|   +-----------------------+                                                     |
|   | Target Cluster APIs   |                                                     |
|   +-----------------------+                                                     |
+---------------------------------------------------------------------------------+

Method 1: Manifest-Based Installation

Manifest-based installation is the most direct way to install ArgoCD. It involves applying raw, pre-compiled manifests provided by the Argo project. This is highly useful for quick setups, air-gapped installations, or environments where Helm is not permitted.

1. Non-HA (Development) Installation

To install the standard, non-HA version of ArgoCD, create a namespace and apply the official installation manifest:

# Create the namespace
kubectl create namespace argocd

# Apply the standard non-HA installation manifests
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

2. High Availability (Production) Installation

For production environments, the HA manifest configures multiple replicas of the API server and repository server, and deploys a Redis cluster with HA proxying via Redis Sentinel:

# Create the namespace
kubectl create namespace argocd

# Apply the HA installation manifests
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml

Deep Dive: Analyzing the Manifest Components

When you apply the HA manifest, Kubernetes creates several key resources. Let's examine what they do and why they are configured this way:

• Custom Resource Definitions (CRDs): Registers custom resources like Applications, AppProjects, and ApplicationSets. These must be created before any controllers start.
• argocd-server: The API and UI server. In HA mode, this deployment is configured with 3 replicas. It is stateless and can be scaled horizontally behind a Kubernetes Service.
• argocd-repo-server: Responsible for cloning Git repositories, caching contents, and generating Kubernetes manifests from templating engines (Helm, Kustomize). The HA manifest runs 3 replicas of this pod.
• argocd-application-controller: The active synchronization engine that compares live cluster state against Git. In HA mode, it uses Kubernetes leader election so only one replica actively synchronizes applications at a time, preventing race conditions.
• argocd-redis-ha: A StatefulSet running Redis with Sentinel. If the Redis master pod fails, Sentinel automatically promotes a replica to master, ensuring zero data loss for the caching layer.

Method 2: Helm-Based Installation (The Enterprise Standard)

While manifests are easy to apply, they are difficult to customize and maintain. For enterprise deployments, Helm is the standard package manager used to install, upgrade, and configure ArgoCD.

Creating a Production-Grade values.yaml

To deploy a secure, highly available, and performant ArgoCD instance, you must customize the default Helm values. Below is a comprehensive, production-grade values.yaml file. It configures high availability, resource limits, security contexts, Node affinity, and ingress with TLS termination.

# production-values.yaml
# Production-grade ArgoCD Helm configuration

global:
  domain: argocd.example.com
  image:
    tag: "v2.8.4"
    imagePullPolicy: IfNotPresent

# Enable High Availability mode across components
configs:
  cm:
    admin.enabled: "false" # Disable local admin user in favor of SSO
    timeout.reconciliation: "180s" # Adjust reconciliation frequency
    kustomize.buildOptions: "--enable-alpha-plugins"
  
  params:
    # Reduce log level verbosity for production
    server.log.level: "info"
    controller.log.level: "info"

# High Availability Configuration
redis-ha:
  enabled: true
  sysctlImage:
    enabled: true
  haproxy:
    enabled: true
    resources:
      limits:
        cpu: 200m
        memory: 128Mi
      requests:
        cpu: 50m
        memory: 64Mi

controller:
  replicas: 1 # Application Controller uses leader election if scaled, but 1 is standard unless sharding is configured
  resources:
    limits:
      cpu: "2"
      memory: 2Gi
    requests:
      cpu: "500m"
      memory: 512Mi
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true

dex:
  enabled: true
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi

server:
  replicas: 3
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 5
    targetCPUUtilizationPercentage: 80
  resources:
    limits:
      cpu: "1"
      memory: 1Gi
    requests:
      cpu: "200m"
      memory: 256Mi
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
  
  # Configure Ingress for TLS termination at the Ingress Controller
  ingress:
    enabled: true
    ingressClassName: "nginx"
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    hosts:
      - argocd.example.com
    tls:
      - secretName: argocd-server-tls
        hosts:
          - argocd.example.com

repoServer:
  replicas: 3
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
    targetCPUUtilizationPercentage: 80
  resources:
    limits:
      cpu: "2"
      memory: 2Gi
    requests:
      cpu: "500m"
      memory: 512Mi
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true

# Security Hardening: Ensure pods do not run as root
configs:
  securityContext:
    runAsNonRoot: true
    runAsUser: 999
    fsGroup: 999

Executing the Helm Deployment

With your custom values.yaml ready, run the following commands to add the official community repository and install the chart:

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

# Update local chart cache
helm repo update

# Install the chart using our custom production values
helm install argocd argo/argo-cd \
  --namespace argocd \
  --create-namespace \
  -f production-values.yaml

Verify that all pods are running successfully and distributed across your nodes:

kubectl get pods -n argocd

Method 3: Declarative Self-Managed ArgoCD (The GitOps Way)

The ultimate evolution of an ArgoCD installation is to have ArgoCD manage itself. This is known as the bootstrapping pattern. If ArgoCD manages its own installation manifests via Git, any upgrades, configuration changes, or RBAC modifications can be executed via Pull Requests, providing full auditability and disaster recovery capabilities.

Step-by-Step Bootstrap Process

To bootstrap ArgoCD declaratively, follow this workflow:

1. Install a minimal instance of ArgoCD manually (using Helm or manifests).
2. Create a Git repository (e.g., gitops-control-plane) containing the ArgoCD configuration manifests.
3. Create an ArgoCD Application manifest that points to this Git repository and targets the argocd namespace.
4. Apply this application manifest to the cluster. ArgoCD will take control of its own deployment resources.

The Bootstrap Manifests

Create a folder structure in your Git repository:

gitops-control-plane/
├── bootstrap/
│   └── argocd-bootstrap.yaml
└── infrastructure/
    └── argocd/
        ├── Chart.yaml
        └── values.yaml

In infrastructure/argocd/Chart.yaml, define the ArgoCD Helm chart dependency:

apiVersion: v2
name: argocd-bootstrap
description: Declarative self-managed ArgoCD deployment
type: application
version: 1.0.0
appVersion: "1.0.0"
dependencies:
  - name: argo-cd
    version: 5.46.7
    repository: https://argoproj.github.io/argo-helm

In bootstrap/argocd-bootstrap.yaml, define the ArgoCD Application pointing to your repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd-bootstrap
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: 'https://github.com/your-org/gitops-control-plane.git'
    targetRevision: HEAD
    path: infrastructure/argocd
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply the bootstrap application manifest to your cluster. ArgoCD will read its own configuration from Git and transition to a fully self-managed state:

kubectl apply -f bootstrap/argocd-bootstrap.yaml

Post-Installation Configuration & Hardening

Once ArgoCD is installed, you must perform initial configurations and secure the control plane before exposing it to users.

1. Retrieving the Initial Admin Password

During installation, ArgoCD generates a random secure password for the default admin user and stores it in a Kubernetes secret named argocd-initial-admin-secret. Retrieve it using:

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

Note: It is highly recommended to delete this secret after configuring Single Sign-On (SSO) and disabling the local admin account.

2. Accessing the User Interface

To access the UI locally without exposing it via an Ingress, use port-forwarding:

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

Open your browser and navigate to https://localhost:8080.

3. Configuring Single Sign-On (SSO) with GitHub (OAuth)

To secure access, you should integrate ArgoCD with your organization's identity provider. Below is a production configuration using Dex (packaged with ArgoCD) to authenticate users via GitHub.

First, register a new OAuth application in your GitHub organization with the callback URL set to: https://argocd.example.com/api/dex/callback.

Next, configure the argocd-cm ConfigMap (or your Helm values) with the following block:

# Add this block to your values.yaml under configs.cm
configs:
  cm:
    url: https://argocd.example.com
    dex.config: |
      connectors:
        - type: github
          id: github
          name: GitHub
          config:
            clientID: "your-github-client-id"
            clientSecret: "$github-secret:dex.github.clientSecret" # Reference to a Kubernetes secret
            orgs:
              - name: your-github-org
                teams:
                  - platform-engineering
                  - developers

Create the Kubernetes secret to hold the client secret securely:

apiVersion: v1
kind: Secret
metadata:
  name: dex
  namespace: argocd
type: Opaque
stringData:
  dex.github.clientSecret: "your-github-client-secret-token"

4. Configuring Role-Based Access Control (RBAC)

Once SSO is enabled, map GitHub teams to custom ArgoCD roles using the argocd-rbac-cm ConfigMap. This prevents unauthorized users from modifying applications.

# Add this block to your values.yaml under configs.rbac
configs:
  rbac:
    policy.default: role:readonly
    policy.csv: |
      # Format: p, subject, resource, action, object, effect
      
      # Platform Engineering team gets full admin rights
      g, "your-github-org:platform-engineering", role:admin
      
      # Developer team can sync and view, but not create/delete apps in production
      p, role:developer, applications, get, */*, allow
      p, role:developer, applications, sync, */*, allow
      p, role:developer, projects, get, *, allow
      g, "your-github-org:developers", role:developer

5. Network Security Hardening

ArgoCD controllers require access to your Git repositories and the Kubernetes API server. However, the UI and API servers do not need unrestricted network access. Implement a NetworkPolicy to isolate the ArgoCD namespace:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: argocd-server-network-policy
  namespace: argocd
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: argocd-server
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # Allow traffic from your Ingress Controller namespace only
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: ingress-nginx
      ports:
        - protocol: TCP
          port: 8080
        - protocol: TCP
          port: 8081

Enterprise Scaling & Performance Tuning

As your enterprise scales to hundreds of applications and dozens of clusters, a default ArgoCD installation will run into resource exhaustion and performance degradation. Use the following scaling strategies to optimize your installation.

1. Application Controller Sharding

By default, a single argocd-application-controller pod manages all registered clusters and applications. This leads to high CPU usage and slow reconciliation loops. You can scale the controller horizontally using sharding.

When sharding is enabled, ArgoCD automatically distributes clusters across multiple controller replicas based on a hashing algorithm.

# Enable controller sharding in values.yaml
controller:
  replicas: 3
  env:
    - name: ARGOCD_CONTROLLER_REPLICAS
      value: "3"

2. Scaling the Repository Server

The argocd-repo-server performs heavy operations like running helm template and kustomize build. If many applications sync simultaneously, this pod can run out of memory or experience high latency.

To scale this component:

• Enable Horizontal Pod Autoscaling (HPA) for the repo-server.
• Increase the manifest generation timeout (default is 90s) to handle complex charts.
• Configure parallel processing limits to prevent a single repository from starving others.

# Add to values.yaml
repoServer:
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
  env:
    - name: ARGOCD_REPO_SERVER_MAX_COMBINED_GENERATE_TASKS
      value: "100"
    - name: ARGOCD_REPO_SERVER_GENERATE_TIMEOUT
      value: "180s"

3. Tuning Redis Caching

ArgoCD heavily relies on Redis to cache Git manifest generation results. If Redis runs out of memory, performance collapses. Ensure Redis has persistent storage or a clear eviction policy, and scale it using Redis Sentinel.

Monitoring & Observability

To maintain production reliability, you must monitor ArgoCD's internal metrics. ArgoCD exposes Prometheus metrics on port 8082 (for the controller) and 8083 (for the server).

Configuring Prometheus ServiceMonitors

If you are using the Prometheus Operator, enable ServiceMonitors in your Helm values to automatically discover and scrape ArgoCD targets:

# Enable Prometheus metrics scraping in values.yaml
controller:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
      interval: 30s

server:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
      interval: 30s

repoServer:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
      interval: 30s

Critical Metrics to Alert On

Monitor the following metrics in your Grafana dashboards and configure alerts for anomalies:

Troubleshooting Common Installation Issues

When deploying ArgoCD for the first time, you may encounter several common failure modes. Below is a guide to diagnosing and fixing these issues.

1. Redis Pod in CrashLoopBackOff

Symptom: The argocd-redis pod fails to start, displaying a CrashLoopBackOff or OOMKilled status.

Cause: This usually happens in secure environments where the pod security standard blocks the default Redis image from running, or when Redis exceeds its allocated memory limits.

Resolution: Increase the memory limit in your values file or adjust the security context. If using Redis HA, ensure that your Kubernetes nodes have sysctl vm.overcommit_memory=1 set, or enable the sysctl init container in the Helm chart:

# Fix in values.yaml
redis-ha:
  sysctlImage:
    enabled: true

2. Repository Connection Timeout

Symptom: Applications remain in a ComparisonError state with logs showing connection timeouts to GitHub/GitLab.

Cause: The argocd-repo-server cannot reach the external Git hosting service due to egress network restrictions or proxy configurations.

Resolution: Verify DNS resolution within the namespace and check if your enterprise requires an HTTP proxy to access the internet. If a proxy is required, inject the proxy environment variables into the repo-server:

# Inject proxy configuration in values.yaml
repoServer:
  env:
    - name: HTTP_PROXY
      value: "http://proxy.example.com:8080"
    - name: HTTPS_PROXY
      value: "http://proxy.example.com:8080"
    - name: NO_PROXY
      value: "kubernetes.default.svc,127.0.0.1"

3. Sync Delays (No Webhook Configured)

Symptom: Changes pushed to Git take up to 3 minutes to reflect in the ArgoCD UI.

Cause: By default, ArgoCD polls Git repositories every 3 minutes. It does not know a commit occurred until the next poll cycle.

Resolution: Configure a webhook in GitHub/GitLab pointing to your ArgoCD API server endpoint (https://argocd.example.com/api/webhook). This forces an instantaneous sync when a push occurs.

Enterprise Case Study: Scale Migration

Let's look at how a real-world financial services company migrated their CD pipelines to an HA ArgoCD installation.

The Challenge: The company had 450 microservices running across 8 Kubernetes clusters. Their legacy Jenkins pipeline used kubectl apply commands directly, which took up to 25 minutes per deployment, lacked auditing, and suffered from frequent configuration drift.

The Solution:

• They deployed a centralized, High Availability ArgoCD instance in a dedicated "management" cluster.
• They configured OIDC authentication with Okta and mapped roles using AD groups.
• They bootstrapped the installation using the GitOps pattern described in Method 3.
• They enabled controller sharding (3 replicas) to distribute the monitoring load of 8 target clusters.

The Results:

• Deployment times dropped from 25 minutes to under 45 seconds.
• Configuration drift was eliminated; ArgoCD automatically corrected manual changes within 180 seconds.
• Compliance and auditing requirements were met entirely through Git commit histories.

Scenario-Based Interview Questions & Answers

Question 1: Why does ArgoCD HA use Redis Sentinel instead of a standard Redis Cluster?

Answer: ArgoCD uses Redis primarily as a transient cache for Git manifest generation and index data. Redis Sentinel provides high availability with automatic failover (Master/Slave promotion) which is perfect for ArgoCD's single-key caching patterns. A full Redis Cluster is designed for horizontal write-scaling across shards, which introduces unnecessary networking complexity and overhead that ArgoCD's caching layer does not require.

Question 2: If the ArgoCD API Server (argocd-server) goes down completely, will running applications be impacted?

Answer: No. The argocd-server is stateless and only serves the UI, CLI, and API requests. If it goes down, administrators cannot view or manually trigger syncs via the UI, but the underlying applications running on Kubernetes will continue to run without interruption. The argocd-application-controller (which runs as a separate pod) will also continue to reconcile state in the background.

Question 3: How does ArgoCD handle cluster credentials securely when managing remote Kubernetes clusters?

Answer: When you add a remote target cluster to ArgoCD, it creates a Kubernetes Secret in the ArgoCD namespace. This secret contains the cluster's API endpoint URL and the service account token or certificate authority (CA) data required to authenticate. These secrets are labeled with argocd.argoproj.io/secret-type: cluster, allowing the application controller to read them and dynamically configure connection clients.

Question 4: What is the risk of setting the reconciliation timeout (timeout.reconciliation) to a very low value, like 10 seconds?

Answer: Setting a very low reconciliation timeout forces ArgoCD to poll Git and compare cluster states continuously. This will cause CPU and memory starvation on the argocd-repo-server and argocd-application-controller, trigger API rate-limiting from your Git provider (e.g., GitHub secondary rate limits), and overload the Kubernetes API server with constant read requests.

Frequently Asked Questions (FAQs)

Can I install ArgoCD without cluster-admin permissions?

Yes. You can install ArgoCD in "Namespace-scoped" mode. In this mode, ArgoCD only monitors and deploys resources within the single namespace it is installed in, requiring only namespace-level RBAC rather than cluster-wide roles.

What is the difference between ArgoCD and ArgoCD Autopilot?

ArgoCD is the core product. ArgoCD Autopilot is an opinionated tool built on top of ArgoCD that automates the creation of Git repositories, structures your application deployment folders, and manages updates to ArgoCD itself.

How do I upgrade an existing ArgoCD installation?

If using Helm, update your chart repository and run helm upgrade with your values file. If using the GitOps bootstrapping method, simply update the chart version in your Git repository's Chart.yaml and let ArgoCD apply the upgrade to itself.

Should I run ArgoCD in the same cluster as my production workloads?

For enterprise environments, the best practice is to run ArgoCD in a dedicated "Management" or "Control Plane" cluster. This isolates the deployment engine from application resource starvation and prevents a security compromise in a production application from affecting the deployment orchestrator.

How does ArgoCD decrypt secrets stored in Git?

ArgoCD itself does not decrypt secrets. It integrates with external secrets management solutions like HashiCorp Vault, AWS Secrets Manager, or Sealed Secrets. These are typically resolved at render time using plugins like ArgoCD Vault Plugin or processed in-cluster via operators like the External Secrets Operator.

Why does ArgoCD show "OutOfSync" immediately after a successful sync?

This occurs when there is a conflict between the manifest defined in Git and an in-cluster mutation (e.g., a mutating admission webhook or an controller changing default values like adding sidecars). To fix this, you must configure ArgoCD to ignore those specific mutated fields using the ignoreDifferences configuration block.

Summary & Next Steps

In this lesson, we covered the critical pathways for installing ArgoCD on Kubernetes. We explored manual manifests, built a production-grade high-availability Helm deployment, and established a declarative self-managed bootstrapping pattern. We also covered post-installation security configurations, scaling methodologies, and troubleshooting techniques.

Now that your ArgoCD control plane is successfully installed and secured, you are ready to configure applications and start deploying workloads.