Kubernetes Installation

Install Argo CD on Kubernetes using standard manifests

This guide covers the standard (non-HA) installation of Argo CD on Kubernetes. This installation is suitable for testing, demonstrations, and non-production environments.

The standard installation is not recommended for production use. For production deployments, use the High Availability installation.

Prerequisites

• Kubernetes cluster (version 1.27+)
• kubectl CLI configured to access your cluster
• Cluster-admin access (for standard installation)

Installation

1. Create the namespace

   Create a dedicated namespace for Argo CD:

   kubectl create namespace argocd
   
2. Apply the installation manifest

   Install Argo CD using the stable release:

   kubectl apply -n argocd --server-side --force-conflicts \
     -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
   

   The --server-side --force-conflicts flags are required because some Argo CD CRDs exceed the size limit for client-side apply.

   For a specific version, replace stable with the version tag:

   kubectl apply -n argocd --server-side --force-conflicts \
     -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.14.0/manifests/install.yaml
   
3. Verify installation

   Wait for all pods to be ready:

   kubectl get pods -n argocd
   

   You should see the following components:

   NAME                                               READY   STATUS
   argocd-application-controller-0                    1/1     Running
   argocd-applicationset-controller-xxx               1/1     Running
   argocd-dex-server-xxx                              1/1     Running
   argocd-notifications-controller-xxx                1/1     Running
   argocd-redis-xxx                                   1/1     Running
   argocd-repo-server-xxx                             1/1     Running
   argocd-server-xxx                                  1/1     Running
   

Installed Components

The standard installation includes the following components:

Core Components

API Server (argocd-server)

• Type: Deployment (1 replica)
• Purpose: Provides the Web UI and gRPC/REST API
• Exposes: Port 8080 (HTTP), 8083 (HTTPS)

Application Controller (argocd-application-controller)

• Type: StatefulSet (1 replica)
• Purpose: Monitors applications and reconciles desired state
• Watches: Git repositories and Kubernetes clusters

Repository Server (argocd-repo-server)

• Type: Deployment (1 replica)
• Purpose: Clones Git repos and generates manifests
• Supports: Helm, Kustomize, Jsonnet, and custom plugins

Supporting Services

Redis (argocd-redis)

• Type: Deployment (1 replica)
• Purpose: Caching and state management
• Note: Single instance (not HA)

Dex (argocd-dex-server)

• Type: Deployment (1 replica)
• Purpose: OIDC identity provider
• Supports: SSO integrations

ApplicationSet Controller

• Type: Deployment (1 replica)
• Purpose: Manages ApplicationSet resources
• Enables: Multi-cluster application templating

Notifications Controller

• Type: Deployment (1 replica)
• Purpose: Sends notifications for application events
• Integrates: Slack, email, webhooks, etc.

Manifest Structure

The install.yaml manifest contains:

# CustomResourceDefinitions
- Application CRD
- ApplicationSet CRD
- AppProject CRD

# Namespace Resources
- ServiceAccounts
- Roles and RoleBindings
- Deployments and StatefulSets
- Services
- ConfigMaps
- Secrets

# Cluster Resources
- ClusterRole (argocd-application-controller)
- ClusterRoleBinding

The ClusterRoleBinding is bound to the ServiceAccount in the argocd namespace. If you change the namespace, update the ClusterRoleBinding accordingly.

Accessing Argo CD

Port Forwarding

Access the API server using kubectl port-forward:

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

Then access the UI at https://localhost:8080

Load Balancer

Expose the API server using a LoadBalancer service:

kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

Get the external IP:

kubectl get svc argocd-server -n argocd

Ingress

Create an Ingress resource for the API server:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    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:
              name: https
  tls:
  - hosts:
    - argocd.example.com
    secretName: argocd-server-tls

Initial Admin Password

Retrieve the initial admin password:

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

Login with:

• Username: admin
• Password: (retrieved from command above)

Change the admin password after first login and delete the argocd-initial-admin-secret secret.

Namespace-Level Installation

For installations that only deploy to external clusters, use the namespace-install variant:

# Install CRDs first
kubectl apply --server-side --force-conflicts \
  -k https://github.com/argoproj/argo-cd/manifests/crds\?ref\=stable

# Install namespace-scoped resources
kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/namespace-install.yaml

The namespace-install.yaml does not include:

• ClusterRole or ClusterRoleBinding
• CRDs (must be installed separately)
• Ability to deploy to the local cluster without explicit credentials

Installing with Kustomize

Create a kustomization.yaml file:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: argocd

resources:
  - https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Optional: Add customizations
patches:
  - patch: |-
      - op: replace
        path: /spec/replicas
        value: 2
    target:
      kind: Deployment
      name: argocd-repo-server

Apply with:

kustomize build . | kubectl apply --server-side --force-conflicts -f -

Custom Namespace

To install in a custom namespace:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: my-argocd

resources:
  - https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

patches:
  - patch: |-
      - op: replace
        path: /subjects/0/namespace
        value: my-argocd
    target:
      kind: ClusterRoleBinding

Upgrading

To upgrade to a new version:

kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/<version>/manifests/install.yaml

Replace <version> with the desired version tag (e.g., v2.14.0).

Always review the upgrade notes before upgrading to a new version.

Uninstalling

To remove Argo CD:

kubectl delete -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl delete namespace argocd

Next Steps

Configure SSO

Set up Single Sign-On authentication

Add Repositories

Connect Git repositories to Argo CD

Create Applications

Deploy your first application

High Availability

Upgrade to HA for production

Troubleshooting

Pods stuck in Pending state

Check resource requests and node capacity:

kubectl describe pod -n argocd <pod-name>
kubectl describe nodes

The standard installation requires moderate resources. Consider adjusting resource requests if needed.

Cannot access the UI

Verify the argocd-server service is running:

kubectl get svc argocd-server -n argocd
kubectl logs -n argocd deploy/argocd-server

Check if port-forwarding is active and not blocked by firewalls.

CRD size limit errors

If you see errors about CRD size limits, ensure you’re using the --server-side --force-conflicts flags:

kubectl apply -n argocd --server-side --force-conflicts -f <manifest>