Advanced ArgoCD Features

When Basic Sync Wasn't Enough

We had a complex application: database migration → schema update → API deployment → cache warming.

Using basic ArgoCD sync, everything deployed at once:

Time 0s: All resources created simultaneously
├─ Database migration Job (needs to finish first)
├─ API Deployment (needs DB migration done)
└─ Cache warming Job (needs API running)

Result: API crashed (DB not ready), cache warming failed

I needed ordered deployment. That's when I discovered sync waves.

Then we grew to 5 clusters. Managing 5 separate Applications was tedious. ApplicationSets solved that.

Then we needed approval workflows, SSO, notifications, and multi-cluster management.

ArgoCD has advanced features for all of this. Let me show you.

Sync Waves: Ordered Deployment

Sync waves control the order in which resources are synced.

The Problem

# All created at the same time
---
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
# Needs to complete BEFORE API starts

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
# Needs db-migration DONE

The Solution: Sync Waves

# Phase 1: Run first
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/sync-wave: "1"  # Wave 1
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: flyway:latest
        command: ["flyway", "migrate"]
      restartPolicy: Never

---
# Phase 2: Run after wave 1
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  annotations:
    argocd.argoproj.io/sync-wave: "2"  # Wave 2
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: myapp/api:v1.0

---
# Phase 3: Run after wave 2
apiVersion: batch/v1
kind: Job
metadata:
  name: cache-warm
  annotations:
    argocd.argoproj.io/sync-wave: "3"  # Wave 3
spec:
  template:
    spec:
      containers:
      - name: warm-cache
        image: myapp/cache-warmer:v1.0
      restartPolicy: Never

Execution:

Wave 1 → db-migration (wait for completion)
  ↓
Wave 2 → api deployment (wait for healthy)
  ↓
Wave 3 → cache-warm (wait for completion)

Sync Wave Rules

• Lower numbers sync first (wave 1 before wave 2)

• Default wave: 0 (if no annotation)

• Negative waves allowed (wave -1 syncs before wave 0)

• ArgoCD waits for wave completion before moving to next

• Jobs must complete successfully

• Deployments must be healthy

Complex Example

# Wave -2: Secrets (needed by everything)
---
apiVersion: v1
kind: Secret
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "-2"

# Wave -1: ConfigMaps
---
apiVersion: v1
kind: ConfigMap
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "-1"

# Wave 0: Database (default, no annotation)
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres

# Wave 1: DB Migration
---
apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"

# Wave 2: Application
---
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "2"

# Wave 3: Ingress (last)
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "3"

Resource Hooks: Lifecycle Actions

Hooks let you run jobs at specific points in the sync lifecycle.

Hook Types

• PreSync - Before sync starts

• Sync - During normal sync (default)

• PostSync - After sync completes

• SyncFail - If sync fails

• Skip - Never sync (manual only)

PreSync Hook: Setup

# Run before sync
apiVersion: batch/v1
kind: Job
metadata:
  name: pre-sync-backup
  annotations:
    argocd.argoproj.io/hook: PreSync  # Hook type
    argocd.argoproj.io/hook-delete-policy: HookSucceeded  # Clean up after success
spec:
  template:
    spec:
      containers:
      - name: backup
        image: postgres:15
        command:
        - sh
        - -c
        - |
          pg_dump -h postgres -U app -d mydb > /backup/pre-sync-$(date +%s).sql
          echo "Backup completed"
      restartPolicy: Never

PostSync Hook: Verification

# Run after sync
apiVersion: batch/v1
kind: Job
metadata:
  name: post-sync-test
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      containers:
      - name: test
        image: curlimages/curl:latest
        command:
        - sh
        - -c
        - |
          echo "Testing API health..."
          curl -f http://api-service/health || exit 1
          echo "API is healthy!"
      restartPolicy: Never

SyncFail Hook: Rollback

# Run if sync fails
apiVersion: batch/v1
kind: Job
metadata:
  name: sync-fail-alert
  annotations:
    argocd.argoproj.io/hook: SyncFail
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: alert
        image: curlimages/curl:latest
        command:
        - sh
        - -c
        - |
          curl -X POST https://slack.com/api/chat.postMessage \
            -H "Authorization: Bearer $SLACK_TOKEN" \
            -d "text=ArgoCD sync failed for my-app!"
      restartPolicy: Never

Hook Delete Policies

• HookSucceeded - Delete if hook succeeds

• HookFailed - Delete if hook fails

• BeforeHookCreation - Delete before creating new hook (next sync)

Sync Flow with Hooks

ApplicationSets: Managing Multiple Applications

ApplicationSet generates multiple Applications from templates.

Use Cases

1. Multi-cluster deployments - Same app, many clusters

2. Multi-tenant - Same app, many namespaces

3. Monorepo apps - Many apps, one repo

Generator Types

• List: Static list of parameters

• Cluster: Generate per cluster

• Git: Generate from Git directories/files

• Matrix: Combine multiple generators

Example 1: Multi-Cluster Deployment

# Deploy to 3 clusters
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: api-multicluster
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - cluster: dev-cluster
        url: https://dev-cluster.example.com
        namespace: default
        replicas: "2"
      - cluster: staging-cluster
        url: https://staging-cluster.example.com
        namespace: default
        replicas: "5"
      - cluster: prod-cluster
        url: https://prod-cluster.example.com
        namespace: default
        replicas: "10"
  
  template:
    metadata:
      name: 'api-{{cluster}}'  # api-dev-cluster, api-staging-cluster, ...
    spec:
      project: default
      source:
        repoURL: https://github.com/mycompany/my-app.git
        targetRevision: main
        path: manifests
        helm:
          parameters:
          - name: replicas
            value: '{{replicas}}'  # Different per cluster
      destination:
        server: '{{url}}'
        namespace: '{{namespace}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Result: 3 Applications created automatically.

Example 2: Git Directory Generator

# Auto-create app for each directory
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: monorepo-apps
  namespace: argocd
spec:
  generators:
  - git:
      repoURL: https://github.com/mycompany/monorepo.git
      revision: main
      directories:
      - path: apps/*  # Match all apps/*/
  
  template:
    metadata:
      name: '{{path.basename}}'  # Directory name
    spec:
      project: default
      source:
        repoURL: https://github.com/mycompany/monorepo.git
        targetRevision: main
        path: '{{path}}'  # apps/api, apps/web, apps/worker
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true

Repository structure:

monorepo/
├── apps/
│   ├── api/
│   │   └── manifests/
│   ├── web/
│   │   └── manifests/
│   └── worker/
│       └── manifests/

Result: 3 Applications auto-created: api, web, worker.

Add new app:

mkdir apps/new-service
# ApplicationSet auto-creates new-service Application!

Example 3: Cluster Generator

# Auto-deploy to all registered clusters
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: monitoring-all-clusters
  namespace: argocd
spec:
  generators:
  - clusters: {}  # All clusters registered in ArgoCD
  
  template:
    metadata:
      name: 'monitoring-{{name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/mycompany/monitoring.git
        targetRevision: main
        path: manifests
      destination:
        server: '{{server}}'
        namespace: monitoring
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true

Register new cluster:

argocd cluster add new-cluster
# ApplicationSet auto-creates monitoring-new-cluster Application!

Multi-Cluster Management

ArgoCD can manage applications across multiple Kubernetes clusters.

Register External Cluster

# List available clusters (from kubeconfig)
kubectl config get-contexts

# Register cluster with ArgoCD
argocd cluster add staging-cluster

# List registered clusters
argocd cluster list
# SERVER                              NAME              VERSION  STATUS
# https://kubernetes.default.svc      in-cluster        1.28     Successful
# https://staging.example.com         staging-cluster   1.28     Successful

Deploy to External Cluster

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-staging-remote
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/mycompany/my-app.git
    targetRevision: main
    path: manifests
  destination:
    server: https://staging.example.com  # External cluster
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Hub-Spoke Architecture

One ArgoCD instance manages all clusters.

RBAC: Role-Based Access Control

Control who can do what in ArgoCD.

Default Roles

• role:admin - Full access

• role:readonly - Read-only access

Custom RBAC Policy

# ConfigMap: argocd-rbac-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly  # Default for all users
  
  policy.csv: |
    # Developers can view and sync apps
    p, role:developer, applications, get, */*, allow
    p, role:developer, applications, sync, */*, allow
    p, role:developer, applications, override, */*, allow
    p, role:developer, repositories, get, *, allow
    
    # Ops can do everything except delete production
    p, role:ops, applications, *, */*, allow
    p, role:ops, applications, delete, production/*, deny
    p, role:ops, clusters, get, *, allow
    p, role:ops, repositories, *, *, allow
    
    # Assign users to roles
    g, [email protected], role:developer
    g, [email protected], role:ops
    g, ops-team, role:ops

RBAC Format:

p, <role>, <resource>, <action>, <object>, <effect>
g, <user/group>, <role>

Project-Level RBAC

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  description: Team A's applications
  
  # Source repos team-a can use
  sourceRepos:
  - https://github.com/mycompany/team-a-*
  
  # Clusters team-a can deploy to
  destinations:
  - namespace: team-a-*
    server: https://kubernetes.default.svc
  
  # Deny dangerous actions
  namespaceResourceBlacklist:
  - group: ''
    kind: ResourceQuota
  - group: ''
    kind: LimitRange

SSO Integration

Integrate ArgoCD with corporate SSO.

GitHub SSO

# ConfigMap: argocd-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
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
          teams:
          - platform-team  # Only platform-team members

Google SSO

dex.config: |
  connectors:
  - type: oidc
    id: google
    name: Google
    config:
      issuer: https://accounts.google.com
      clientID: $GOOGLE_CLIENT_ID
      clientSecret: $GOOGLE_CLIENT_SECRET
      hostedDomains:
      - example.com  # Only @example.com emails

Okta SSO

dex.config: |
  connectors:
  - type: saml
    id: okta
    name: Okta
    config:
      ssoURL: https://mycompany.okta.com/app/abc123/sso/saml
      entityIssuer: https://argocd.example.com
      caData: <base64-encoded-cert>

Notifications

Get alerts when syncs succeed/fail.

Install Notifications Controller

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

Configure Slack Notifications

# ConfigMap: argocd-notifications-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.slack: |
    token: $slack-token
  
  template.app-deployed: |
    message: |
      Application {{.app.metadata.name}} synced successfully!
      Revision: {{.app.status.sync.revision}}
  
  template.app-sync-failed: |
    message: |
      Application {{.app.metadata.name}} sync FAILED!
      Error: {{.app.status.operationState.message}}
  
  trigger.on-deployed: |
    - when: app.status.sync.status == 'Synced'
      send: [app-deployed]
  
  trigger.on-sync-failed: |
    - when: app.status.sync.status == 'Failed'
      send: [app-sync-failed]

# Secret: argocd-notifications-secret
apiVersion: v1
kind: Secret
metadata:
  name: argocd-notifications-secret
  namespace: argocd
stringData:
  slack-token: xoxb-your-slack-bot-token

Subscribe Application to Notifications

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    notifications.argoproj.io/subscribe.on-deployed.slack: deployments-channel
    notifications.argoproj.io/subscribe.on-sync-failed.slack: alerts-channel

Key Takeaways

1. Sync waves enable ordered deployments

   • Annotate resources with argocd.argoproj.io/sync-wave

   • Lower numbers deploy first

   • ArgoCD waits for each wave to complete

2. Hooks add lifecycle actions

   • PreSync, Sync, PostSync, SyncFail, Skip

   • Run jobs at specific sync points

   • Useful for migrations, tests, backups

3. ApplicationSets scale application management

   • Generate multiple Applications from templates

   • List, Cluster, Git, Matrix generators

   • Perfect for multi-cluster, multi-tenant, monorepos

4. Multi-cluster management from single ArgoCD

   • Register external clusters

   • Hub-spoke architecture

   • Centralized control

5. RBAC controls access

   • Define roles and policies

   • Project-level isolation

   • SSO integration for enterprise auth

6. Notifications keep teams informed

   • Slack, email, webhook integrations

   • Trigger on sync events

   • Subscribe apps to channels

In the next article, we'll integrate GitOps with CI/CD: automated image builds, Git updates, and complete deployment pipelines with GitHub Actions.

---

Previous: Kustomize and Helm with ArgoCD Next: GitOps CI/CD Pipeline Integration