Your First ArgoCD Application

Deploying My First App with ArgoCD (And Understanding What Happened)

After installing ArgoCD, I was eager to deploy something. I found a tutorial:

argocd app create my-app \
  --repo https://github.com/mycompany/my-app-config.git \
  --path manifests \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace production

It worked! Sort of. The app showed up in ArgoCD UI as "OutOfSync". I clicked "Sync" and it deployed.

But I had questions:

• What did that command actually create?

• Why was it OutOfSync?

• What's the difference between manual and auto-sync?

• How does ArgoCD know if my app is healthy?

• What if I want to change the deployment?

Let me walk you through creating your first ArgoCD application properly, understanding every step.

What Is an ArgoCD Application?

An Application is a Kubernetes Custom Resource (CRD) that tells ArgoCD:

1. Where to get manifests (Git repo)

2. What manifests to deploy (path in repo)

3. Where to deploy them (cluster + namespace)

4. How to deploy them (sync policy, health checks)

It's the core concept in ArgoCD.

Preparing Your Git Repository

First, you need a Git repo with Kubernetes manifests.

Create a Simple Git Repo

# Create repo
mkdir my-app-manifests
cd my-app-manifests
git init

# Create simple deployment
cat > deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-app
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 200m
            memory: 256Mi
EOF

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

# Commit and push
git add .
git commit -m "Initial nginx deployment"
git remote add origin https://github.com/yourusername/my-app-manifests.git
git push -u origin main

Repository structure:

my-app-manifests/
├── deployment.yaml
└── service.yaml

Method 1: Creating Application via CLI

# Create ArgoCD application
argocd app create nginx-app \
  --repo https://github.com/yourusername/my-app-manifests.git \
  --path . \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --revision main

# Output:
# application 'nginx-app' created

Parameter breakdown:

• --repo: Git repository URL

• --path: Path within repo (. = root)

• --dest-server: Target Kubernetes cluster (use kubernetes.default.svc for the cluster where ArgoCD runs)

• --dest-namespace: Target namespace

• --revision: Git branch/tag/commit (default: HEAD)

Check application status:

argocd app get nginx-app

# Name:               nginx-app
# Server:             https://kubernetes.default.svc
# Namespace:          default
# URL:                https://argocd.example.com/applications/nginx-app
# Repo:               https://github.com/yourusername/my-app-manifests.git
# Target:             main
# Path:               .
# SyncWindow:         Sync Allowed
# Sync Policy:        <none>
# Sync Status:        OutOfSync from main (abc1234)
# Health Status:      Missing

Status explanation:

• Sync Status: OutOfSync - Git state ≠ Cluster state (nothing deployed yet)

• Health Status: Missing - Resources don't exist in cluster

Method 2: Creating Application via YAML

This is more GitOps-friendly (store Application definition in Git).

# nginx-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-app
  namespace: argocd  # Applications must be in argocd namespace
spec:
  # Source: Where to get manifests
  source:
    repoURL: https://github.com/yourusername/my-app-manifests.git
    targetRevision: main
    path: .
  
  # Destination: Where to deploy
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  
  # Project (we'll cover this later)
  project: default

# Apply to create application
kubectl apply -f nginx-app.yaml

# Verify
argocd app get nginx-app

Advantage: Application definition is version-controlled and declarative.

Method 3: Creating Application via Web UI

1. Open ArgoCD UI

2. Click "+ NEW APP"

3. Fill in form:

   • Application Name: nginx-app

   • Project: default

   • Sync Policy: Manual

   • Repository URL: https://github.com/yourusername/my-app-manifests.git

   • Revision: main

   • Path: .

   • Cluster URL: https://kubernetes.default.svc

   • Namespace: default

4. Click "CREATE"

Advantage: Visual, good for learning and one-off deployments.

Syncing Your Application

After creating the application, it's OutOfSync (not deployed).

Manual Sync

# Sync via CLI
argocd app sync nginx-app

# Output:
# TIMESTAMP                  GROUP        KIND         NAMESPACE  NAME            STATUS    HEALTH
# 2026-01-02T10:00:00+00:00              Deployment   default    nginx-app       OutOfSync Missing
# 2026-01-02T10:00:00+00:00              Service      default    nginx-service   OutOfSync Missing
# 
# Name:               nginx-app
# Sync Status:        Synced to main (abc1234)
# Health Status:      Progressing

Or via UI:

1. Click on application

2. Click "SYNC"

3. Click "SYNCHRONIZE"

Or via kubectl:

# Trigger sync by updating Application resource
kubectl patch application nginx-app -n argocd --type merge -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"normal"}}}'

Verify Deployment

# Check in Kubernetes
kubectl get all -l app=nginx

# NAME                             READY   STATUS    RESTARTS   AGE
# pod/nginx-app-7d8f9c-abc12       1/1     Running   0          30s
# pod/nginx-app-7d8f9c-xyz89       1/1     Running   0          30s
# 
# NAME                    TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)
# service/nginx-service   ClusterIP   10.96.100.50    <none>        80/TCP
# 
# NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
# deployment.apps/nginx-app   2/2     2            2           30s

# Check ArgoCD status
argocd app get nginx-app
# Sync Status:        Synced to main (abc1234)
# Health Status:      Healthy

Status now:

• Sync Status: Synced - Git state = Cluster state ✓

• Health Status: Healthy - All resources running ✓

Understanding the Application CRD

Let's look at the actual Application resource:

kubectl get application nginx-app -n argocd -o yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-app
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/yourusername/my-app-manifests.git
    targetRevision: main
    path: .
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  project: default
status:
  sync:
    status: Synced
    comparedTo:
      source:
        repoURL: https://github.com/yourusername/my-app-manifests.git
        targetRevision: main
        path: .
      destination:
        server: https://kubernetes.default.svc
        namespace: default
    revision: abc1234567890  # Git commit SHA
  health:
    status: Healthy
  resources:
  - group: apps
    kind: Deployment
    name: nginx-app
    namespace: default
    status: Synced
    health:
      status: Healthy
  - group: ""
    kind: Service
    name: nginx-service
    namespace: default
    status: Synced
    health:
      status: Healthy

Key fields:

• spec.source: Git repo details

• spec.destination: Target cluster/namespace

• status.sync.status: Synced or OutOfSync

• status.health.status: Healthy, Progressing, Degraded, Missing

• status.resources: List of all managed resources

Auto-Sync: The GitOps Magic

Manual sync requires clicking "Sync" every time you push to Git. Auto-sync automates this.

Enabling Auto-Sync

# nginx-app.yaml with auto-sync
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-app
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/yourusername/my-app-manifests.git
    targetRevision: main
    path: .
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  project: default
  
  # Auto-sync configuration
  syncPolicy:
    automated:
      prune: true      # Delete resources not in Git
      selfHeal: true   # Revert manual changes
      allowEmpty: false
    syncOptions:
    - CreateNamespace=true  # Auto-create namespace if missing

Or via CLI:

argocd app set nginx-app --sync-policy automated --auto-prune --self-heal

What happens now:

Test auto-sync:

# Update image version in Git
cd my-app-manifests
sed -i 's/nginx:1.25/nginx:1.26/' deployment.yaml
git commit -am "Update nginx to 1.26"
git push

# Wait ~3 minutes (ArgoCD reconciliation interval)
# Or force refresh
argocd app get nginx-app --refresh

# Check status
argocd app get nginx-app
# Sync Status:        Synced to main (def5678)  ← New commit!
# 
kubectl get deployment nginx-app -o jsonpath='{.spec.template.spec.containers[0].image}'
# nginx:1.26  ← Updated automatically!

Magic! Git push → Auto-deployed.

Auto-Sync Options Explained

prune: true

What it does: Deletes resources from cluster if removed from Git.

# Remove service from Git
cd my-app-manifests
git rm service.yaml
git commit -m "Remove nginx service"
git push

# Wait for sync
# ArgoCD deletes the service from cluster
kubectl get service nginx-service
# Error: service "nginx-service" not found ✓

prune: false (default):

• Resources removed from Git stay in cluster

• Must manually delete

selfHeal: true

What it does: Reverts manual changes to match Git.

# Manually scale deployment
kubectl scale deployment nginx-app --replicas=5

# Check replicas
kubectl get deployment nginx-app
# DESIRED: 5  ← Manually changed

# Wait ~3 minutes (or force refresh)
argocd app get nginx-app --refresh

# ArgoCD detects drift and reverts
kubectl get deployment nginx-app
# DESIRED: 2  ← Back to Git state (selfHeal)

selfHeal: false (default):

• Manual changes stay

• Application shows "OutOfSync"

• Must manually sync to revert

allowEmpty: false

What it does: Prevents syncing if Git path is empty.

Use case: Avoid accidentally deleting everything if you mess up the path.

Health Assessment

ArgoCD checks if your application is healthy by evaluating each resource.

Built-in Health Checks

ArgoCD has built-in health checks for common resources:

Deployment:

# Healthy if:
# - Desired replicas = Available replicas
# - No failed pods

# Progressing if:
# - Rolling out new version

# Degraded if:
# - Some pods crashing
# - Insufficient resources

Service:

# Always Healthy (Services don't have health concept)

Pod:

# Healthy if: Running and Ready
# Progressing if: Pending, ContainerCreating
# Degraded if: CrashLoopBackOff, Error

Ingress:

# Healthy if: Has load balancer IP
# Progressing if: Waiting for IP

Custom Health Checks

You can define custom health checks:

# ConfigMap: argocd-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  resource.customizations.health.argoproj.io_Rollout: |
    hs = {}
    if obj.status ~= nil then
      if obj.status.phase == "Healthy" then
        hs.status = "Healthy"
        hs.message = "Rollout is healthy"
        return hs
      end
      if obj.status.phase == "Degraded" then
        hs.status = "Degraded"
        hs.message = "Rollout is degraded"
        return hs
      end
    end
    hs.status = "Progressing"
    hs.message = "Waiting for rollout"
    return hs

Viewing Health in UI

ArgoCD UI shows health with visual indicators:

• 🟢 Healthy - All resources healthy

• 🟡 Progressing - Deployment in progress

• 🔴 Degraded - Some resources unhealthy

• ⚪ Missing - Resources don't exist

Sync Options

Fine-tune how ArgoCD syncs your application.

CreateNamespace

syncPolicy:
  syncOptions:
  - CreateNamespace=true  # Create namespace if missing

Without this: Sync fails if namespace doesn't exist.

PruneLast

syncPolicy:
  syncOptions:
  - PruneLast=true  # Delete resources after creating new ones

Use case: Avoid downtime during updates.

ApplyOutOfSyncOnly

syncPolicy:
  syncOptions:
  - ApplyOutOfSyncOnly=true  # Only apply changed resources

Use case: Faster syncs, less cluster load.

Validate=false

syncPolicy:
  syncOptions:
  - Validate=false  # Skip kubectl validation

Use case: Deploy resources that fail validation (not recommended).

ServerSideApply

syncPolicy:
  syncOptions:
  - ServerSideApply=true  # Use server-side apply

Use case: Handle large resources, better conflict resolution.

Making Changes to Your Application

Let's update our application properly.

Update 1: Change Image Version

cd my-app-manifests
sed -i 's/nginx:1.26/nginx:1.27/' deployment.yaml
git commit -am "Update nginx to 1.27"
git push

# Auto-sync enabled? Wait ~3 min
# Manual sync? Run: argocd app sync nginx-app

# Verify
kubectl get deployment nginx-app -o jsonpath='{.spec.template.spec.containers[0].image}'
# nginx:1.27

Update 2: Scale Replicas

sed -i 's/replicas: 2/replicas: 5/' deployment.yaml
git commit -am "Scale to 5 replicas"
git push

# Verify
kubectl get deployment nginx-app
# DESIRED: 5

Update 3: Add ConfigMap

cat > configmap.yaml <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
  labels:
    app: nginx
data:
  nginx.conf: |
    server {
      listen 80;
      location / {
        return 200 "Hello from GitOps!\n";
      }
    }
EOF

git add configmap.yaml
git commit -m "Add nginx config"
git push

# ArgoCD auto-syncs
# Verify
kubectl get configmap nginx-config

Rollback

Need to rollback? Just revert in Git.

# Rollback to previous commit
git revert HEAD
git push

# Or checkout previous version
git checkout HEAD~1 deployment.yaml
git commit -m "Rollback nginx to 1.26"
git push

# ArgoCD auto-syncs the rollback

Via ArgoCD UI:

1. Click application

2. Click "HISTORY AND ROLLBACK"

3. Select previous version

4. Click "ROLLBACK"

This creates a new sync with old manifests (doesn't change Git).

Deleting an Application

# Delete application (keeps resources in cluster)
argocd app delete nginx-app

# Delete application and all resources
argocd app delete nginx-app --cascade

# Or via kubectl
kubectl delete application nginx-app -n argocd

Cascade options:

• --cascade=foreground (default) - Wait for resources to delete

• --cascade=background - Delete app immediately, resources delete async

• --cascade=false - Delete app, keep resources

Key Takeaways

1. Application CRD is the core

   • Defines source (Git), destination (cluster), sync policy

   • Lives in argocd namespace

   • Can create via CLI, YAML, or UI

2. OutOfSync vs Synced

   • OutOfSync: Git ≠ Cluster

   • Synced: Git = Cluster

   • Auto-sync automates reconciliation

3. Auto-sync enables true GitOps

   • Git push → Auto-deployed

   • prune: Auto-delete removed resources

   • selfHeal: Auto-revert manual changes

4. Health checks ensure reliability

   • Built-in checks for common resources

   • Custom checks for CRDs

   • Visual indicators in UI

5. Git is the source of truth

   • Want to update? Commit to Git

   • Want to rollback? Revert Git commit

   • Want to see what's deployed? Check Git

In the next article, we'll explore using Kustomize and Helm with ArgoCD to manage multi-environment deployments (dev, staging, production) from a single Git repo.

---

Previous: Installing and Configuring ArgoCD Next: Kustomize and Helm with ArgoCD