🚀 Setting Up ArgoCD for GitOps: Simple Guide

Let me show you how to set up ArgoCD on Alpine Linux! ArgoCD makes deploying to Kubernetes super easy by using Git as the source of truth. It’s like having a robot that watches your Git repo and automatically updates your apps!

🤔 What is ArgoCD?

ArgoCD is a GitOps tool for Kubernetes. Think of it as an automatic deployment system - you push changes to Git, and ArgoCD makes sure your Kubernetes cluster matches what’s in Git. No more manual deployments or kubectl commands!

Why use ArgoCD?

• Automatic deployments
• Easy rollbacks
• Visual dashboard
• Git-based history
• Multi-cluster support

🎯 What You Need

Before starting, you’ll need:

• Alpine Linux with Kubernetes
• kubectl configured
• Git repository
• Basic Kubernetes knowledge
• About 30 minutes

📋 Step 1: Prepare Kubernetes

First, let’s set up Kubernetes:

# Install k3s (lightweight Kubernetes)
curl -sfL https://get.k3s.io | sh -

# Check if running
k3s kubectl get nodes

# Copy config for kubectl
mkdir -p ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config

# Install kubectl
apk add kubectl

# Verify cluster
kubectl cluster-info
kubectl get nodes

📋 Step 2: Install ArgoCD

Now install ArgoCD in your cluster:

# 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 pods to be ready
kubectl wait --for=condition=Ready pods --all -n argocd --timeout=300s

# Check installation
kubectl get pods -n argocd

# You should see:
# argocd-application-controller
# argocd-dex-server
# argocd-redis
# argocd-repo-server
# argocd-server

📋 Step 3: Access ArgoCD UI

Let’s access the ArgoCD dashboard:

# Get initial admin password
ARGO_PWD=$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d)
echo "Admin password: $ARGO_PWD"

# Expose ArgoCD server
# Option 1: Port forward (for testing)
kubectl port-forward svc/argocd-server -n argocd 8080:443 &

# Option 2: LoadBalancer (for production)
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

# Option 3: Ingress (recommended)
cat > argocd-ingress.yaml << 'EOF'
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  rules:
  - host: argocd.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80
EOF

kubectl apply -f argocd-ingress.yaml

# Access UI at https://localhost:8080
# Username: admin
# Password: (from above)

📋 Step 4: Install ArgoCD CLI

Install the command-line tool:

# Download ArgoCD CLI
wget https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
mv argocd-linux-amd64 /usr/local/bin/argocd
chmod +x /usr/local/bin/argocd

# Login to ArgoCD
argocd login localhost:8080 \
  --username admin \
  --password "$ARGO_PWD" \
  --insecure

# Change admin password
argocd account update-password \
  --current-password "$ARGO_PWD" \
  --new-password "YourNewPassword123!"

# List applications
argocd app list

📋 Step 5: Create Your First App

Let’s deploy a sample application:

# Create app manifests in Git
mkdir -p ~/gitops-demo
cd ~/gitops-demo

# Create namespace manifest
cat > namespace.yaml << 'EOF'
apiVersion: v1
kind: Namespace
metadata:
  name: demo-app
EOF

# Create deployment
cat > deployment.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-demo
  namespace: demo-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
        resources:
          limits:
            memory: "128Mi"
            cpu: "100m"
EOF

# Create service
cat > service.yaml << 'EOF'
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  namespace: demo-app
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP
EOF

# Initialize git repo
git init
git add .
git commit -m "Initial demo app"

# Push to your Git repository
# git remote add origin https://github.com/yourusername/gitops-demo.git
# git push -u origin main

📋 Step 6: Register App with ArgoCD

Now tell ArgoCD about your app:

# Create ArgoCD application
argocd app create demo-app \
  --repo https://github.com/yourusername/gitops-demo.git \
  --path . \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace demo-app \
  --sync-policy automated \
  --auto-prune \
  --self-heal

# Or using YAML manifest
cat > argocd-app.yaml << 'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/yourusername/gitops-demo.git
    targetRevision: HEAD
    path: .
  destination:
    server: https://kubernetes.default.svc
    namespace: demo-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
EOF

kubectl apply -f argocd-app.yaml

# Check app status
argocd app get demo-app
argocd app sync demo-app

📋 Step 7: Configure GitOps Workflow

Set up proper GitOps workflow:

# Create environments structure
mkdir -p ~/gitops-repo/{base,environments/{dev,staging,prod}}
cd ~/gitops-repo

# Base configuration
cat > base/deployment.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: myapp:latest
        ports:
        - containerPort: 8080
EOF

# Kustomization for base
cat > base/kustomization.yaml << 'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
EOF

# Dev environment override
cat > environments/dev/kustomization.yaml << 'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: dev
bases:
  - ../../base
patchesStrategicMerge:
  - deployment-patch.yaml
EOF

cat > environments/dev/deployment-patch.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: myapp
        image: myapp:dev
        env:
        - name: ENVIRONMENT
          value: "development"
EOF

# Create ArgoCD apps for each environment
argocd app create myapp-dev \
  --repo https://github.com/yourusername/gitops-repo.git \
  --path environments/dev \
  --dest-namespace dev \
  --dest-server https://kubernetes.default.svc

📋 Step 8: Advanced Features

Configure advanced ArgoCD features:

# Enable notifications
cat > argocd-notifications-cm.yaml << 'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.slack: |
    token: $slack-token
  template.app-deployed: |
    message: |
      {{if eq .serviceType "slack"}}:white_check_mark:{{end}} Application {{.app.metadata.name}} is now running new version.
  template.app-health-degraded: |
    message: |
      {{if eq .serviceType "slack"}}:exclamation:{{end}} Application {{.app.metadata.name}} has degraded.
  trigger.on-deployed: |
    - when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
      send: [app-deployed]
  trigger.on-health-degraded: |
    - when: app.status.health.status == 'Degraded'
      send: [app-health-degraded]
EOF

kubectl apply -f argocd-notifications-cm.yaml

# Set up RBAC
cat > argocd-rbac-cm.yaml << 'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    p, role:developer, applications, *, */*, allow
    p, role:developer, logs, get, */*, allow
    p, role:developer, exec, create, */*, allow
    g, dev-team, role:developer
EOF

kubectl apply -f argocd-rbac-cm.yaml

🎮 Practice Exercise

Try this GitOps workflow:

1. Create a Git repo
2. Add Kubernetes manifests
3. Create ArgoCD app
4. Make changes and watch sync

# Create practice app
mkdir -p ~/practice-app
cd ~/practice-app

# Create app manifests
cat > app.yaml << 'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  message: "Hello from GitOps!"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-gitops
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
      - name: hello
        image: hashicorp/http-echo
        args:
        - "-text=Hello GitOps!"
        ports:
        - containerPort: 5678
EOF

# Commit and push
git init
git add .
git commit -m "Initial app"

# Create ArgoCD app
argocd app create hello-gitops \
  --repo [YOUR_GIT_REPO] \
  --path . \
  --dest-namespace default \
  --dest-server https://kubernetes.default.svc \
  --sync-policy automated

# Make a change
sed -i 's/Hello GitOps!/Hello ArgoCD!/g' app.yaml
git add . && git commit -m "Update message" && git push

# Watch ArgoCD sync automatically!
argocd app get hello-gitops --refresh

🚨 Troubleshooting Common Issues

Sync Failed

Fix sync problems:

# Check app status
argocd app get myapp

# View sync details
argocd app sync myapp --dry-run

# Check logs
kubectl logs -n argocd deployment/argocd-application-controller

# Force sync
argocd app sync myapp --force

# Hard refresh
argocd app get myapp --hard-refresh

Repository Access Issues

Fix Git access:

# Add private repo
argocd repo add https://github.com/private/repo.git \
  --username myuser \
  --password mytoken

# Using SSH key
argocd repo add [email protected]:private/repo.git \
  --ssh-private-key-path ~/.ssh/id_rsa

# Check repo connection
argocd repo list
argocd repo get https://github.com/private/repo.git

OutOfSync Issues

Handle sync problems:

# Check differences
argocd app diff myapp

# Manual sync specific resource
argocd app sync myapp --resource apps:Deployment:myapp

# Prune resources
argocd app sync myapp --prune

# Reset to Git state
argocd app sync myapp --force --prune

💡 Pro Tips

Tip 1: App of Apps Pattern

Manage multiple apps:

cat > apps/argocd-apps.yaml << 'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: apps
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/gitops
    targetRevision: HEAD
    path: apps
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
EOF

Tip 2: Secrets Management

Handle secrets safely:

# Install Sealed Secrets
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.18.0/controller.yaml

# Create sealed secret
echo -n mypassword | kubectl create secret generic mysecret \
  --dry-run=client \
  --from-file=password=/dev/stdin \
  -o yaml | kubeseal -o yaml > mysealedsecret.yaml

# Commit sealed secret to Git
git add mysealedsecret.yaml
git commit -m "Add sealed secret"

Tip 3: Multi-Cluster

Deploy to multiple clusters:

# Add cluster
argocd cluster add my-other-cluster

# Create app targeting specific cluster
argocd app create myapp-prod \
  --repo https://github.com/myorg/gitops \
  --path environments/prod \
  --dest-name my-other-cluster \
  --dest-namespace production

✅ Best Practices

1. Repository Structure

   gitops-repo/
   ├── apps/           # ArgoCD app definitions
   ├── base/           # Base configurations
   ├── environments/   # Environment overlays
   │   ├── dev/
   │   ├── staging/
   │   └── prod/
   └── clusters/       # Cluster-specific configs

2. Sync Policies

   • Dev: Auto-sync enabled
   • Staging: Manual sync
   • Prod: Manual with approval

3. Resource Limits

   • Always set resource limits
   • Use namespace quotas
   • Monitor resource usage

4. Security

   • Use RBAC properly
   • Encrypt secrets
   • Audit access logs

🏆 What You Learned

Awesome work! You can now:

• ✅ Install and configure ArgoCD
• ✅ Create GitOps workflows
• ✅ Deploy apps automatically
• ✅ Manage multiple environments
• ✅ Troubleshoot sync issues

You’re now doing GitOps like a pro!

🎯 What’s Next?

Now that ArgoCD is running, explore:

• Progressive delivery with Flagger
• Advanced deployment strategies
• Multi-tenancy setup
• ArgoCD Image Updater

Keep automating with GitOps! 🚀