Installing and Configuring ArgoCD

My First ArgoCD Installation (And the Mistakes I Made)

I was excited to try ArgoCD. I found a blog post that said "Just run this one command!"

kubectl apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Done! ArgoCD installed in 30 seconds. Easy!

But then:

• How do I access the UI?

• What's the admin password?

• How do I connect my Git repo?

• Why can't I access it from outside the cluster?

I spent 2 hours figuring out what that "simple" installation actually did.

This article is the guide I wish I had: a complete, production-ready ArgoCD installation with explanations.

Prerequisites

Before installing ArgoCD, you need:

1. Kubernetes Cluster

# Check if you have a cluster
kubectl cluster-info
# Kubernetes control plane is running at https://...

# Check version (ArgoCD needs 1.20+)
kubectl version --short
# Server Version: v1.28.0

Options if you don't have a cluster:

• Local: minikube start or kind create cluster

• Cloud: GKE, EKS, AKS

• Development: Docker Desktop Kubernetes

2. kubectl Configured

# Test kubectl access
kubectl get nodes
# NAME           STATUS   ROLES    AGE
# control-plane  Ready    master   10d

3. Cluster Admin Access

# ArgoCD needs to create ClusterRoles and CRDs
kubectl auth can-i create clusterrole
# yes

kubectl auth can-i create customresourcedefinitions
# yes

4. Enough Cluster Resources

Minimum requirements:

• 2 CPU cores

• 4GB RAM

• 10GB storage

# Check available resources
kubectl top nodes
# NAME    CPU   MEMORY
# node1   20%   40%    ← Good, has headroom

Installation Methods

There are three ways to install ArgoCD:

1. Raw manifests (what we'll use) - Simple, explicit

2. Helm chart - For Helm users, customizable

3. Operator - For automated management

We'll use raw manifests for clarity.

Step 1: Create ArgoCD Namespace

# Create dedicated namespace
kubectl create namespace argocd

# Verify
kubectl get namespace argocd
# NAME     STATUS   AGE
# argocd   Active   5s

Why a dedicated namespace?

• Isolates ArgoCD components

• Easier RBAC management

• Clean separation from applications

Step 2: Install ArgoCD

Download Manifests (Recommended)

# Download for inspection
curl -O https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Review what will be installed
less install.yaml
# CustomResourceDefinitions, ServiceAccounts, Deployments, etc.

# Install
kubectl apply -n argocd -f install.yaml

Or Direct Install

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

What Gets Installed

# Check installed resources
kubectl get all -n argocd

# Output:
# NAME                                      READY   STATUS    RESTARTS   AGE
# pod/argocd-application-controller-0       1/1     Running   0          1m
# pod/argocd-dex-server-xxx                 1/1     Running   0          1m
# pod/argocd-redis-xxx                      1/1     Running   0          1m
# pod/argocd-repo-server-xxx                1/1     Running   0          1m
# pod/argocd-server-xxx                     1/1     Running   0          1m
# pod/argocd-notifications-controller-xxx   1/1     Running   0          1m

# NAME                                  TYPE        CLUSTER-IP      PORT(S)
# service/argocd-dex-server             ClusterIP   10.96.1.100     5556,5557
# service/argocd-redis                  ClusterIP   10.96.1.101     6379
# service/argocd-repo-server            ClusterIP   10.96.1.102     8081
# service/argocd-server                 ClusterIP   10.96.1.103     80,443

# Custom Resource Definitions
kubectl get crd | grep argoproj
# applications.argoproj.io
# applicationsets.argoproj.io
# appprojects.argoproj.io

What was created:

• 5 Deployments/StatefulSets (server, repo-server, controller, dex, notifications)

• 4 Services

• 3 CRDs (Application, ApplicationSet, AppProject)

• ConfigMaps, Secrets, ServiceAccounts, Roles

Step 3: Verify Installation

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

# Check pod status
kubectl get pods -n argocd
# All should show STATUS: Running, READY: 1/1

Troubleshooting if pods aren't ready:

# Check specific pod
kubectl describe pod argocd-server-xxx -n argocd

# Check logs
kubectl logs -n argocd argocd-server-xxx

# Common issues:
# - ImagePullBackOff: Check internet connectivity
# - CrashLoopBackOff: Check logs for errors
# - Pending: Check resources (kubectl describe node)

Step 4: Access ArgoCD UI

By default, ArgoCD server is ClusterIP (not accessible externally).

Option 1: Port Forward (Quick Testing)

# Forward local port 8080 to ArgoCD server
kubectl port-forward svc/argocd-server -n argocd 8080:443

# Access in browser
# https://localhost:8080
# (Ignore SSL warning - self-signed cert)

Pros: Simple, no cluster changes Cons: Only accessible from your machine, need to keep terminal open

Option 2: NodePort (Development)

# Change service type to NodePort
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "NodePort"}}'

# Get NodePort
kubectl get svc argocd-server -n argocd
# NAME            TYPE       CLUSTER-IP      PORT(S)                      
# argocd-server   NodePort   10.96.1.103     80:30080/TCP,443:30443/TCP

# Access via node IP
# https://<node-ip>:30443

Pros: Accessible from network Cons: High port number, not production-ready

Option 3: LoadBalancer (Cloud Clusters)

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

# Wait for external IP (only works on cloud providers)
kubectl get svc argocd-server -n argocd -w
# NAME            TYPE           EXTERNAL-IP
# argocd-server   LoadBalancer   <pending>
# argocd-server   LoadBalancer   35.123.45.67  ← Cloud provider assigns this

# Access via external IP
# https://35.123.45.67

Pros: Production-ready, real IP Cons: Costs money (cloud load balancer), requires cloud provider

Option 4: Ingress (Production Recommended)

# argocd-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    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-server-tls

# Apply ingress
kubectl apply -f argocd-ingress.yaml

# Access via domain
# https://argocd.example.com

Pros: Custom domain, SSL/TLS, production-ready Cons: Requires ingress controller, DNS setup

Step 5: Get Admin Password

# Default admin password is auto-generated
kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -d
# xJ8fK2mP9qLnR7vT

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

Login credentials:

• Username: admin

• Password: <output from above command>

Important: Change this password immediately after first login!

Step 6: Install ArgoCD CLI

The CLI is optional but highly recommended.

macOS

# Using Homebrew
brew install argocd

# Verify
argocd version
# argocd: v2.9.3+...

Linux

# Download binary
curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64

# Make executable
chmod +x argocd

# Move to PATH
sudo mv argocd /usr/local/bin/

# Verify
argocd version

Windows

# Download from GitHub releases
# https://github.com/argoproj/argo-cd/releases/latest

# Or using Chocolatey
choco install argocd-cli

Step 7: Login via CLI

# Login (with port-forward)
argocd login localhost:8080

# Or with external access
argocd login argocd.example.com

# Enter credentials
# Username: admin
# Password: xJ8fK2mP9qLnR7vT
# WARNING: Self-signed certificate
# Proceed? (y/n): y

# Verify login
argocd account get-user-info
# Logged In: true
# Username: admin

Step 8: Change Admin Password

Via UI:

1. Login to Web UI

2. Click "User Info" (top right)

3. Click "Update Password"

4. Enter new password

Via CLI:

# Update password
argocd account update-password

# Current password: <old-password>
# New password: <new-password>
# Confirm password: <new-password>

# Password updated successfully

Best practice: Delete the initial secret after changing password

kubectl delete secret argocd-initial-admin-secret -n argocd

Step 9: Connect Git Repository

Via CLI

# Add public Git repo (no authentication)
argocd repo add https://github.com/argoproj/argocd-example-apps.git

# Add private Git repo with SSH
argocd repo add [email protected]:mycompany/myrepo.git \
  --ssh-private-key-path ~/.ssh/id_rsa

# Add private Git repo with HTTPS
argocd repo add https://github.com/mycompany/myrepo.git \
  --username myuser \
  --password mytoken

# List repos
argocd repo list
# TYPE  NAME                                              URL
# git   https://github.com/argoproj/argocd-example-apps  https://...

Via UI

1. Go to Settings → Repositories

2. Click "Connect Repo"

3. Choose connection method:

   • HTTPS

   • SSH

   • GitHub App

4. Enter credentials

5. Click "Connect"

Via YAML

# argocd-repo-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/mycompany/myrepo.git
  username: myuser
  password: ghp_xxxxxxxxxxxx  # GitHub personal access token

kubectl apply -f argocd-repo-secret.yaml

Step 10: Create First Application (Quick Test)

# Create application from example repo
argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

# Sync application
argocd app sync guestbook

# Check status
argocd app get guestbook
# Name:               guestbook
# Server:             https://kubernetes.default.svc
# Namespace:          default
# URL:                https://argocd.example.com/applications/guestbook
# Repo:               https://github.com/argoproj/argocd-example-apps.git
# Target:             HEAD
# Path:               guestbook
# Sync Status:        Synced
# Health Status:      Healthy

Verify in cluster:

kubectl get all -n default -l app=guestbook
# Deployment, Service, etc. created!

Configuration Options

Enable Auto-Sync Globally

# Edit ConfigMap
kubectl edit configmap argocd-cm -n argocd

# Add under data:
data:
  application.instanceLabelKey: argocd.argoproj.io/instance
  timeout.reconciliation: 180s  # Reconcile every 3 minutes (default)

Configure Resource Limits

# Increase resources for large deployments
kubectl edit deployment argocd-server -n argocd

spec:
  template:
    spec:
      containers:
      - name: argocd-server
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi

Enable Metrics

# ArgoCD exposes Prometheus metrics by default
kubectl port-forward svc/argocd-metrics -n argocd 8082:8082

# Access metrics
curl http://localhost:8082/metrics
# argocd_app_info{...}
# argocd_app_sync_total{...}

Security Hardening

1. Disable Admin User

# After creating other users/SSO
kubectl patch configmap argocd-cm -n argocd --type merge -p '{"data":{"admin.enabled":"false"}}'

2. Enable RBAC

# ConfigMap: argocd-rbac-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly  # Default role for new users
  policy.csv: |
    p, role:developers, applications, get, */*, allow
    p, role:developers, applications, sync, */*, allow
    g, developers-team, role:developers

3. Use SSO (Dex)

# ConfigMap: argocd-cm
data:
  url: https://argocd.example.com
  dex.config: |
    connectors:
    - type: github
      id: github
      name: GitHub
      config:
        clientID: $GITHUB_CLIENT_ID
        clientSecret: $GITHUB_CLIENT_SECRET
        orgs:
        - name: mycompany

4. Network Policies

# Restrict ArgoCD network access
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: argocd-network-policy
  namespace: argocd
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/part-of: argocd
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: ingress-nginx
    ports:
    - protocol: TCP
      port: 8080
  egress:
  - to:
    - namespaceSelector: {}
    ports:
    - protocol: TCP
      port: 443  # Git HTTPS
  - to:
    - podSelector:
        matchLabels:
          app.kubernetes.io/name: argocd-redis
    ports:
    - protocol: TCP
      port: 6379

Common Issues and Solutions

Issue 1: Can't Access UI

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

# Check port-forward is running
# Try: kubectl port-forward svc/argocd-server -n argocd 8080:443

# Check firewall rules

Issue 2: Login Failed

# Reset admin password
kubectl patch secret argocd-secret -n argocd -p \
  '{"stringData": {"admin.password": "'$(htpasswd -nbBC 10 "" password | tr -d ':\n')'"}}'

# Or delete and let ArgoCD regenerate
kubectl delete secret argocd-initial-admin-secret -n argocd
# Wait for pod restart

Issue 3: Can't Connect to Git Repo

# Test from repo-server pod
kubectl exec -it argocd-repo-server-xxx -n argocd -- sh
$ git clone https://github.com/mycompany/myrepo.git
# Check error message

# Common causes:
# - Wrong credentials
# - Private repo needs authentication
# - Network policy blocking egress
# - SSH key not configured

Issue 4: High Memory/CPU Usage

# Check resource usage
kubectl top pods -n argocd

# Scale components
kubectl scale deployment argocd-server -n argocd --replicas=2
kubectl scale deployment argocd-repo-server -n argocd --replicas=2

# Enable controller sharding (see previous article)

Verifying Installation

Checklist:

# 1. All pods running
kubectl get pods -n argocd
# All STATUS: Running

# 2. Can access UI
# https://localhost:8080 or custom domain

# 3. Can login
argocd login <server>

# 4. Can connect to Git
argocd repo add <repo-url>

# 5. Can create application
argocd app create test --repo <repo> --path <path> --dest-server https://kubernetes.default.svc --dest-namespace default

# 6. Can sync application
argocd app sync test

# 7. Application healthy
argocd app get test
# Sync Status: Synced
# Health Status: Healthy

Key Takeaways

1. Installation is straightforward

   • Create namespace

   • Apply manifests

   • Wait for pods

   • Access UI

2. Multiple access methods

   • Port-forward: Quick testing

   • LoadBalancer: Cloud production

   • Ingress: On-prem production

   • NodePort: Development

3. Security from day 1

   • Change admin password

   • Enable RBAC

   • Use SSO

   • Delete initial secret

4. CLI is powerful

   • Install argocd CLI

   • Login and manage via terminal

   • Scriptable and automatable

5. Configuration is in ConfigMaps

   • argocd-cm: General config

   • argocd-rbac-cm: RBAC policies

   • argocd-cmd-params-cm: Command parameters

In the next article, we'll deploy our first real application using ArgoCD, exploring the Application CRD, sync policies, and health checks.

---

Previous: ArgoCD Architecture and Components Next: Your First ArgoCD Application