DEV Community

James Lee
James Lee

Posted on

Argo CD Application Management: Deploy to Multiple Clusters with a Unified View

#automation #devops #kubernetes #tutorial

In the previous article, we got Argo CD installed and running. Now let's use it. This article covers the full application management workflow — creating apps via CLI and Web UI, syncing to multiple clusters, and using Argo CD's unified view to manage application resources across environments.

1. Why Argo CD's Application Model Matters

Kubernetes is powerful, but it has a blind spot: there is no native concept of an "application". A typical cloud-native app spans multiple resource types — Deployments, Services, ConfigMaps, Secrets, PersistentVolumes — all scattered across the cluster with no unified view.

Argo CD solves this with the Application CRD: a custom resource that groups all Kubernetes resources belonging to an application into a single, manageable unit. This enables:

  • A unified topology view of all resources and their relationships
  • Centralized lifecycle management across multi-cluster, multi-cloud environments
  • Sync status tracking between Git (desired state) and the cluster (live state)

2. Supported Application Orchestration Types

Argo CD supports multiple manifest formats out of the box:

Type Description
Directory Plain Kubernetes YAML/JSON manifests (native K8s format)
Helm Helm charts (supports both Helm 2 and Helm 3)
Kustomize Kustomize overlays with prefix/suffix support
Ksonnet Ksonnet environment-based configuration
Plugin Custom tooling via user-defined plugins

The default type is Directory. Argo CD auto-detects Helm 2 vs Helm 3 based on the apiVersion field in Chart.yaml.

3. Prerequisites: Register Repo and Clusters

Before creating an application, you need to register the source repository and target clusters with Argo CD.

Register the Git Repository 

argocd repo add --name book-examples \
  https://github.com/haoshuwei/book-examples
Enter fullscreen mode Exit fullscreen mode 
repository 'https://github.com/haoshuwei/book-examples' added
Enter fullscreen mode Exit fullscreen mode

Register Target Clusters

Cloud cluster (production-aliyun):

argocd cluster add kubernetes-admin-c0f5bbc7634e8446db9f3bde2cafc5d8b \
  --name production-aliyun \
  --kubeconfig=kubeconfig-production-aliyun
Enter fullscreen mode Exit fullscreen mode 
INFO[0000] ServiceAccount "argocd-manager" created in namespace "kube-system"
INFO[0000] ClusterRole "argocd-manager-role" created
INFO[0000] ClusterRoleBinding "argocd-manager-role-binding" created
Cluster 'https://192.168.0.32:6443' added
Enter fullscreen mode Exit fullscreen mode

On-premise cluster (production-idc):

argocd cluster add minikube \
  --name production-idc \
  --kubeconfig=kubeconfig-production-idc
Enter fullscreen mode Exit fullscreen mode 
INFO[0000] ServiceAccount "argocd-manager" already exists in namespace "kube-system"
INFO[0000] ClusterRole "argocd-manager-role" updated
INFO[0000] ClusterRoleBinding "argocd-manager-role-binding" updated
Cluster 'https://192.168.0.238:8443' added
Enter fullscreen mode Exit fullscreen mode

When you register a cluster, Argo CD creates a ServiceAccount and ClusterRoleBinding in the target cluster's kube-system namespace. This is how the Application Controller gains access to manage resources in that cluster.

4. Create Applications via CLI

CLI Command Structure 

argocd app create <APP_NAME> \
  --project <PROJECT> \
  --repo <GIT_REPO_URL> \
  --revision <BRANCH_OR_TAG> \
  --path <SUBPATH_IN_REPO> \
  --dest-name <CLUSTER_NAME> \
  --dest-namespace <NAMESPACE>
Enter fullscreen mode Exit fullscreen mode

Every application creation requires 4 configuration groups:

Group Parameters
Basic config App name, project, sync policy
Source repo Repo URL, revision (branch/tag/commit), subpath
Target cluster Cluster API server URL or name, target namespace
Orchestration type Directory / Helm / Kustomize / Ksonnet / Plugin

Deploy guestbook-aliyun to Cloud Cluster 

argocd app create guestbook-aliyun \
  --project default \
  --repo https://github.com/haoshuwei/book-examples \
  --revision master \
  --path examples/guestbook/helm \
  --dest-server https://192.168.0.32:6443 \
  --dest-namespace guestbook
Enter fullscreen mode Exit fullscreen mode 
application 'guestbook-aliyun' created
Enter fullscreen mode Exit fullscreen mode

Check the application list:

argocd app list
Enter fullscreen mode Exit fullscreen mode 
NAME              CLUSTER                    NAMESPACE  PROJECT  STATUS     HEALTH   SYNCPOLICY  ...
guestbook-aliyun  https://192.168.0.32:6443  guestbook  default  OutOfSync  Missing  <none>      ...
Enter fullscreen mode Exit fullscreen mode

Why OutOfSync and Missing?

Creating an application without a sync policy uses manual sync by default. The app definition is registered in Argo CD, but nothing has been deployed to the cluster yet. The statuses mean:

  • OutOfSync — Git state and cluster state don't match (cluster has nothing yet)
  • Missing — Argo CD can't detect the app running in the cluster

This is expected. To actually deploy, run:

argocd app sync guestbook-aliyun
Enter fullscreen mode Exit fullscreen mode

Sync Output — What Actually Happens 

TIMESTAMP                  GROUP  KIND        NAMESPACE  NAME          STATUS       HEALTH
2020-10-10T16:07:12+08:00         Service     guestbook  redis-slave   OutOfSync    Missing
2020-10-10T16:07:12+08:00  apps   Deployment  guestbook  frontend      OutOfSync    Missing
...
2020-10-10T16:07:13+08:00         Service     guestbook  redis-master  Synced       Healthy
2020-10-10T16:07:13+08:00         Service     guestbook  redis-slave   Synced       Healthy
2020-10-10T16:07:13+08:00         Service     guestbook  frontend      Synced       Healthy
2020-10-10T16:07:13+08:00  apps   Deployment  guestbook  redis-slave   Synced       Progressing
2020-10-10T16:07:13+08:00  apps   Deployment  guestbook  redis-master  Synced       Progressing
2020-10-10T16:07:13+08:00  apps   Deployment  guestbook  frontend      Synced       Progressing

Sync Status:   Synced to master (14afbac)
Health Status: Progressing
Phase:         Succeeded
Duration:      1s
Message:       successfully synced (all tasks run)
Enter fullscreen mode Exit fullscreen mode

After sync completes, verify the final status:

argocd app list
Enter fullscreen mode Exit fullscreen mode 
NAME              CLUSTER                    NAMESPACE  PROJECT  STATUS  HEALTH   ...
guestbook-aliyun  https://192.168.0.32:6443  guestbook  default  Synced  Healthy  ...
Enter fullscreen mode Exit fullscreen mode

Application health lifecycle during deployment:

Missing  →  Progressing  →  Healthy
Enter fullscreen mode Exit fullscreen mode

Deploy guestbook-idc to On-Premise Cluster

The on-premise deployment uses a different Helm values file (values-idc.yaml) to customize the configuration for the IDC environment:

argocd app create guestbook-idc \
  --project default \
  --repo https://github.com/haoshuwei/book-examples \
  --revision master \
  --path examples/guestbook/helm \
  --dest-server https://192.168.0.238:8443 \
  --dest-namespace guestbook \
  --values values-idc.yaml
Enter fullscreen mode Exit fullscreen mode 
application 'guestbook-idc' created
Enter fullscreen mode Exit fullscreen mode 
argocd app sync guestbook-idc
Enter fullscreen mode Exit fullscreen mode

The --values flag lets you specify any Helm values file in the repo. This is how you maintain environment-specific configurations (cloud vs on-premise, prod vs staging) without duplicating your Helm charts.

5. Orchestration Type Options — CLI Reference

Type Key CLI Flags Notes
Directory --directory-recurse Set to true to deploy all YAML in subdirectories recursively
Kustomize --nameprefix, --namesuffix Auto-add prefix/suffix to all resource names
Helm --values <file>, --helm-set key=val Supports multiple values files; auto-detects Helm 2 vs 3
Ksonnet --env <environment> Specify the Ksonnet environment
Plugin --plugin-env key=val Pass environment variables to custom plugin

6. Create Applications via Web UI

The Web UI provides the same configuration options as the CLI, with a guided form interface.

Workflow:

Navigate to Applications page
        ↓
Click "NEW APP" / "CREATE APPLICATION"
        ↓
Fill in 4 config groups:
├── Basic: App name, project, sync policy
├── Source: Repo URL, revision, path
├── Destination: Cluster, namespace
└── Helm/Kustomize/Directory settings
        ↓
Click "CREATE"
        ↓
App appears in list with status: Missing / OutOfSync
        ↓
Click "SYNC" → "SYNCHRONIZE"
        ↓
Status transitions: Missing → Progressing → Healthy ✅
Enter fullscreen mode Exit fullscreen mode

The UI is particularly useful for first-time setup and for teams that prefer visual confirmation before syncing.

7. Unified Application View

Once both applications are deployed, Argo CD provides a unified view across all clusters and environments.

Application List View

The application list shows all managed apps at a glance — regardless of which cluster they're running on:

APP NAME           CLUSTER          NAMESPACE  STATUS  HEALTH
guestbook-aliyun   production-aliyun  guestbook  Synced  Healthy
guestbook-idc      production-idc     guestbook  Synced  Healthy
Enter fullscreen mode Exit fullscreen mode

Resource Topology View

Clicking into an application reveals its full resource topology — a visual graph of every Kubernetes resource the app owns and their relationships:

Application: guestbook-aliyun
│
├── Service: frontend          [Healthy] [Synced]
├── Service: redis-master      [Healthy] [Synced]
├── Service: redis-slave       [Healthy] [Synced]
├── Deployment: frontend       [Healthy] [Synced]
│     └── ReplicaSet → Pods
├── Deployment: redis-master   [Healthy] [Synced]
│     └── ReplicaSet → Pods
└── Deployment: redis-slave    [Healthy] [Synced]
      └── ReplicaSet → Pods

Sync Status:   Synced to master @ 14afbac
Health Status: Healthy
Enter fullscreen mode Exit fullscreen mode

Per-Resource Drill-Down

Clicking any resource in the topology view exposes:

  • Summary — resource metadata and current state
  • Events — Kubernetes events for that resource
  • Live Manifest — the actual YAML running in the cluster
  • Desired Manifest — the YAML declared in Git
  • Diff — a side-by-side comparison highlighting any divergence

This diff view is invaluable for debugging unexpected behavior or verifying that a manual change hasn't drifted from the declared state.

8. Summary

Operation CLI Command
Register repo argocd repo add --name <name> <url>
Register cluster argocd cluster add <context> --name <name>
Create app argocd app create <name> --repo ... --path ... --dest-server ...
List apps argocd app list
Sync app argocd app sync <name>
Check app status argocd app get <name>
Delete app argocd app delete <name>

Argo CD's Application model solves a real gap in Kubernetes: it gives you a first-class "application" concept that groups resources, tracks sync state, and provides a unified operational view across any number of clusters — all driven by Git.

Next in this series: Argo CD Application Updates & Rollbacks: Git-Driven Version Control in Practice (Part 10)

Follow the series — next up we cover how to update a live application and roll back to a previous Git revision with a single command.

Top comments (0)