Minikube ArgoCD GitOps Setup

This setup is designed to learn GitOps fundamentals using a hands-on approach with Minikube, ArgoCD, and Kustomize. By the end of this tutorial, you'll understand how modern teams deploy applications using GitOps principles.

[TOC]

What you'll learn

• GitOps workflows - How Git becomes your single source of truth
• ArgoCD deployment patterns - From simple apps to complex multi-environment setups
• Kustomize configurations - Managing different environments without duplicating code

How this project is organized

Everything is structured as following to make learning easier:

minikube-argo/
├── README.md
├── terraform/                  # Sets up ArgoCD infrastructure
├── argocd-infra/               # ArgoCD configuration (the "what to deploy")
│   ├── applications/           # Points ArgoCD to your apps
│   └── projects/               # Access controls and policies
├── applications/               # Your actual applications (the "things being deployed")
│   ├── 1-simple-app/           # Start here - basic Kubernetes
│   ├── 2-helm-app/             # Learn Helm integration
│   └── 3-kustomize-app/        # Environment-specific configs
└── docs/                       # Additional guides

terraform and argocd-infra/ contains instructions for ArgoCD (infrastructure layer), while applications/ contains your actual workloads (application layer)

Overview

We recommend following this path, but feel free to jump around:

Get infra running

1. Start your local Kubernetes cluster (minikube)
2. Deploy ArgoCD
3. Access the ArgoCD web interface

Deploy your first app

1. Understand how the project is structured
2. Deploy a simple application through ArgoCD
3. Make a change and watch GitOps magic happen

Phase 3: Advanced patterns

1. Try deploying with Helm charts
2. Explore environment-specific configs with Kustomize
3. Use the "App of Apps" pattern to manage everything

Before you start

Make sure you have these tools installed:

• Docker or Podman - for container runtime
• Minikube - for local Kubernetes
• kubectl - for Kubernetes management
• Terraform - for infrastructure setup (optional but recommended)
• Helm - for package management

I generally use arkade (marketplace) for installation of tools

ark install minikube
ark install kubectl
ark install terraform
ark install helm

Your machine should have at least 4GB RAM, 2 CPU cores, and 20GB disk space available.

Let's get started!

Step 1: Start your Kubernetes cluster

This setup works great with both Docker and Podman:

If you're using Docker:

minikube start --cpus=4 --memory=8192

If you prefer Podman:

minikube config set driver podman
minikube start --cpus=4 --memory=8192

Both work exactly the same way with ArgoCD. Let's get Minikube running with enough resources:

minikube start --cpus=4 --memory=8192 --disk-size=20GB

# Enable useful addons
minikube addons enable ingress
minikube addons enable metrics-server

Step 2: Deploy ArgoCD

We'll use Terraform to set up ArgoCD properly, but you can also do it manually if you prefer:

Using Terraform (recommended):

cd terraform
terraform init
terraform apply

Manual installation:

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

# Install ArgoCD with our custom configuration
helm install argocd --namespace argocd --create-namespace \
  --version 8.2.5 --values terraform/values.yaml \
  argo/argo-cd

Step 3: Access ArgoCD

Now let's connect to the ArgoCD web interface:

# Forward the ArgoCD server to your local machine
kubectl port-forward svc/argocd-server -n argocd 8080:80

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

Open your browser to http://localhost:8080 and log in with:

• Username: admin
• Password: (the output from the command above)

You should see the ArgoCD dashboard

Your first GitOps deployment

Let's deploy an application using ArgoCD

Step 4: Explore the structure

Take a moment to understand how everything fits together:

# Look at the main directories
ls -la

# Read about ArgoCD applications (the infrastructure layer)
cat argocd-infra/README.md

# Read about the sample applications (the workload layer)
cat applications/README.md

Step 5: Deploy your first app

Let's deploy a simple nginx application:

# Deploy the basic application
kubectl apply -f argocd-infra/applications/1-simple-app.yaml

# Go check the ArgoCD UI - you should see a new application!

In the ArgoCD interface, click on the simple-app application. You'll see ArgoCD synchronizing the application state from Git to your cluster.

Step 6: GitOps in action

Let's make a change (in your fork) and watch ArgoCD automatically sync it:

# Edit the application to scale it up
vim applications/1-simple-app/deployment.yaml
# Change "replicas: 2" to "replicas: 3"

# If you're using Git, commit the change
git add .
git commit -m "Scale simple app to 3 replicas"
git push

# Watch ArgoCD detect and sync the change automatically

Head back to the ArgoCD UI and watch it sync your changes. This is GitOps in action, your Git repository is the single source of truth!

Advanced deployment patterns

Once you're comfortable with the basics, try these more advanced scenarios:

Helm-based applications

# Deploy an application using a Helm chart
kubectl apply -f argocd-infra/applications/2-helm-app.yaml

Check the ArgoCD UI to see how it handles Helm charts differently from plain Kubernetes manifests.

Environment-specific configurations with Kustomize

# Deploy the same app to different environments
kubectl apply -f argocd-infra/applications/3a-kustomize-dev.yaml
kubectl apply -f argocd-infra/applications/3b-kustomize-prod.yaml

Notice how the same base application gets different configurations for development and production environments.

Accessing the Kustomize applications

After deploying the kustomize applications, you can access them using several methods:

Using curl with Host headers:

# Access development environment
curl -H "Host: nginx-dev.local" http://`minikube ip`

# Access production environment
curl -H "Host: nginx-prod.local" http://`minikube ip`

Using browser access:

Add minikube IP to your /etc/hosts file for browser access:

# Get minikube IP and add to /etc/hosts
echo "`minikube ip` nginx-dev.local nginx-prod.local" | sudo tee -a /etc/hosts

# Now you can access in browser:
# http://nginx-dev.local
# http://nginx-prod.local

Using port-forward:

# Port-forward development environment
kubectl port-forward svc/nginx-dev 8081:80 -n nginx-dev

# Port-forward production environment
kubectl port-forward svc/nginx-prod 8082:80 -n nginx-prod

# Access via:
# http://localhost:8081 (dev)
# http://localhost:8082 (prod)

App of Apps pattern

# Deploy all applications at once using the App of Apps pattern
kubectl apply -f argocd-infra/applications/app-of-apps.yaml

This creates a "master" application that manages all your other applications - very handy for complex environments

Common workflows

Adding your own application

1. Create your application manifests in the applications/ directory
2. Create an ArgoCD Application in argocd-infra/applications/ that points to your new app
3. Apply the ArgoCD Application: kubectl apply -f argocd-infra/applications/your-app.yaml
4. Watch ArgoCD deploy it automatically

Managing different environments

Use Kustomize to handle environment-specific configurations:

1. Put shared configuration in applications/your-app/base/
2. Create environment-specific overlays in applications/your-app/overlays/dev/ and applications/your-app/overlays/prod/
3. Point different ArgoCD Applications to different overlays

Debugging deployment issues

# Check what ArgoCD applications exist
kubectl get applications -n argocd

# Get detailed info about a specific application
kubectl describe application <your-app> -n argocd

# Check ArgoCD controller logs if something's not working
kubectl logs -n argocd deployment/argocd-repo-server

Troubleshooting common issues

Minikube won't start?

minikube delete
minikube start --cpus=4 --memory=8192

Can't access ArgoCD?

kubectl get pods -n argocd  # Check if pods are running
kubectl port-forward svc/argocd-server -n argocd 8080:443

Application won't sync?

# Force a sync if needed
kubectl patch application your-app -n argocd \
  --type merge --patch '{"operation": {"sync": {}}}}'

Applications stuck deleting?

# Check if application has deletionTimestamp but won't delete
kubectl get application -n argocd -o yaml | grep -A5 -B5 deletionTimestamp

# Remove finalizers to force deletion
kubectl patch application stuck-app -n argocd --type='merge' -p='{"metadata":{"finalizers":null}}'

# Verify deletion completed
kubectl get applications -n argocd

GitOps best practices

As you get more comfortable with GitOps, keep these principles in mind:

1. Everything in Git - Your Git repository should contain the complete desired state
2. Declarative configuration - Describe what you want, not how to get there
3. Automated deployment - Let ArgoCD handle the deployment process
4. Observable systems - Use the ArgoCD UI and logs to understand what's happening

Additional resources

• ArgoCD Documentation - The official ArgoCD docs
• GitOps Principles - Learn more about GitOps theory
• Kustomize Documentation - Deep dive into Kustomize