In the past few years Kubernetes has become the de‑facto platform for cloud‑native workloads, and GitOps has emerged as the operational paradigm that turns a Git repository into the single source of truth for cluster state. The combination of Argo CD—a purpose‑built continuous delivery tool—and a local Linux environment gives teams a lightweight way to experiment with declarative deployments before pushing changes to production.

This article is aimed at senior or mid‑level DevOps engineers who already have a working Kubernetes cluster (minikube, kind, k3s, etc.) and want to:

1. Understand the core concepts that make GitOps work in practice.
2. Install and configure Argo CD on a local Linux host.
3. Deploy an application using the App‑of‑Apps pattern.
4. Verify the deployment, troubleshoot common issues, and clean up.

All commands are written for a bash shell; feel free to adapt them to your preferred shell or CI pipeline.

TL;DR:
“`bash

Install kind cluster

kind create cluster –name gitops-demo

Deploy Argo CD

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

Port‑forward and log in

kubectl port-forward svc/argocd-server -n argocd 8080:443 &
echo $(kubectl get secret -n argocd argocd-initial-admin-secret -o jsonpath=”{.data.password}” | base64 –decode)

Create a Git repository with an App‑of‑Apps manifest

git clone https://github.com/yourorg/gitops-demo.git
cd gitops-demo
argo app create demo-apps \
–repo https://github.com/yourorg/gitops-demo.git \
–path apps \
–dest-namespace default \
–dest-server https://kubernetes.default.svc \
–sync-policy automated

Sync and verify

argo app sync demo-apps
kubectl get pods -n default
“`

1. Why GitOps with Argo CD on Linux?

For teams that already use CI tools like GitHub Actions or Jenkins, Argo CD can be added as the final step in the pipeline: push → CI build → Helm chart/manifest → Argo CD sync.

2. Prerequisites

Tip: If you’re on Windows or macOS, the same steps apply inside WSL 2 or a local Docker Desktop cluster.

3. Setting Up a Local Kubernetes Cluster

We’ll use kind (Kubernetes in Docker) because it’s lightweight and works well with Argo CD.

# Install kind if you don’t have it
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x kind
sudo mv kind /usr/local/bin/

# Create a cluster named gitops-demo
kind create cluster --name gitops-demo

# Verify connectivity
kubectl get nodes

You should see a single node with status Ready.

4. Installing Argo CD

Argo CD ships as a set of Kubernetes manifests that you can apply directly.

# Create the namespace and install Argo CD
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for all pods to be ready
kubectl wait --for=condition=Ready pod -l app.kubernetes.io/name=argocd-server -n argocd --timeout=120s

4.1 Exposing the UI

For local development we’ll use port‑forwarding:

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

Now open https://localhost:8080 in your browser.

Login credentials
The initial admin password is stored as a Kubernetes secret. Retrieve it with:

export ADMIN_PASSWORD=$(kubectl get secret -n argocd argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 --decode)
echo $ADMIN_PASSWORD

Use admin / $ADMIN_PASSWORD to log in.

5. Preparing a Git Repository

Argo CD expects your manifests (YAML, Helm charts, Kustomize overlays) to live in a Git repo. For this demo we’ll create a simple repository with two applications:

1. nginx‑hello – A static site served by Nginx.
2. app‑of‑apps – An Argo CD application that deploys both of the above.

git init gitops-demo
cd gitops-demo

# Directory structure
mkdir -p apps/nginx-hello
mkdir -p apps/app-of-apps

5.1 nginx‑hello Deployment

Create apps/nginx-hello/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-hello
  template:
    metadata:
      labels:
        app: nginx-hello
    spec:
      containers:
      - name: nginx
        image: nginx:1.25-alpine
        ports:
        - containerPort: 80

Create a Service:

apiVersion: v1
kind: Service
metadata:
  name: nginx-hello
spec:
  selector:
    app: nginx-hello
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

Commit the files:

git add apps/nginx-hello/*
git commit -m "Add nginx‑hello app"

5.2 App‑of‑Apps Manifest

Create apps/app-of-apps/argo-app.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo-apps
spec:
  project: default
  source:
    repoURL: https://github.com/<your-username>/gitops-demo.git
    targetRevision: HEAD
    path: apps/nginx-hello
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated: {}

Commit:

git add apps/app-of-apps/argo-app.yaml
git commit -m "Add App‑of‑Apps"

Push to a remote (e.g., GitHub):

git remote add origin https://github.com/<your-username>/gitops-demo.git
git push -u origin main

Note: Replace <your-username> with your actual GitHub username. If you prefer a local repo, skip the remote steps and point Argo CD to the local path.

6. Adding the Application to Argo CD

# Create an Argo CD application that points to the repo
argocd app create demo-apps \
  --repo https://github.com/<your-username>/gitops-demo.git \
  --path apps/app-of-apps \
  --dest-namespace default \
  --dest-server https://kubernetes.default.svc \
  --sync-policy automated

# Verify the application is registered
argocd app list

You should see demo-apps with status Synced.

6.1 Syncing Manually (Optional)

If you want to force a sync:

argocd app sync demo-apps

The output will show the resources that were created or updated.

7. Verifying the Deployment

# Check pods
kubectl get pods -l app=nginx-hello -o wide

# Expose via port‑forward to test HTTP
kubectl port-forward svc/nginx-hello 8081:80 &
curl http://localhost:8081

You should receive the default Nginx welcome page.

8. Troubleshooting Common Issues

9. Cleaning Up

# Delete Argo CD resources
kubectl delete ns argocd

# Destroy kind cluster
kind delete cluster --name gitops-demo

If you pushed the repo to GitHub and want to keep it, skip deleting the remote.

10. Extending the Demo

11. Takeaways

1. Argo CD turns a Git repo into the single source of truth for Kubernetes clusters.
2. Installing it on a local Linux host is trivial—just apply the manifest and port‑forward the UI.
3. The App‑of‑Apps pattern lets you compose multiple applications under one logical umbrella, simplifying management at scale.
4. With automated sync policies, any change committed to Git is instantly reflected in the cluster, giving you instant feedback loops.

Whether you’re a seasoned Kubernetes operator or just starting with GitOps, this hands‑on exercise demonstrates how quickly you can spin up a fully functional GitOps pipeline on your local machine. Happy deploying!

Frequently Asked Questions (FAQ)

What is the App‑of‑Apps pattern in Argo CD?

The App‑of‑Apps pattern lets a single root application manage multiple child applications. It simplifies large deployments by keeping one Git folder that references other manifests, enabling hierarchical sync and easier rollback of grouped services.

How do I enable automated sync for an application?

Add the --sync-policy automated flag when creating or editing an app (e.g., argo app create … --sync-policy automated). This tells Argo CD to continuously reconcile the desired state from Git without manual intervention, optionally with a prune strategy.

Where can I find the initial admin password for Argo CD?

Run:

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

This outputs the default password; you should change it immediately after login for security.

How do I troubleshoot a sync failure?

Check the application’s status in the Argo CD UI or via CLI (argo app get <name>). Look for error messages under “Sync Status” and inspect pod logs with kubectl logs. Common issues include missing manifests, RBAC restrictions, or image pull errors.

Related Articles

• Linux Kubernetes Autoscaling – From Event‑Driven Triggers to Scale‑to‑Zero
• Linux‑Kubernetes Networking: Building a Robust, Composable Fabric
• Linux Docker Fundamentals