Creating Applications

Learn how to create Argo CD applications using the UI, CLI, or declarative manifests

Argo CD provides three methods for creating applications: through the web UI, using the CLI, or declaratively with Kubernetes manifests. Each method offers different advantages depending on your workflow.

Creating Applications via UI

The web UI provides an intuitive interface for creating applications with guided forms.

Steps

1. Log in to the Argo CD UI

2. Click the + New App button

3. Fill in the application details:

   • Application Name: A unique name for your application
   • Project: The Argo CD project (default: default)
   • Sync Policy: Choose Manual or Automatic

4. Configure the source repository:

   • Repository URL: Your Git repository URL
   • Revision: Branch, tag, or commit (e.g., HEAD, main, or a specific tag)
   • Path: Path within the repository containing manifests

5. Set the destination:

   • Cluster URL: https://kubernetes.default.svc for in-cluster
   • Namespace: Target namespace for deployment

6. Click Create

The UI automatically validates your inputs and provides helpful error messages if required fields are missing.

Creating Applications via CLI

The Argo CD CLI is ideal for automation, scripting, and quick application creation from the terminal.

Basic Application Creation

argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

With Auto-Sync Enabled

argocd app create my-app \
  --repo https://github.com/example/repo.git \
  --path apps/production \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace production \
  --sync-policy automated \
  --auto-prune \
  --self-heal

Helm Application

argocd app create my-helm-app \
  --repo https://charts.example.com \
  --helm-chart my-chart \
  --revision 1.2.3 \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --helm-set replicaCount=3 \
  --helm-set-string image.tag=v1.0.0

Common CLI Options

--repo · string · required

Git repository URL or Helm chart repository

--path · string

Path within the repository (for Git sources)

--dest-server · string · required

Kubernetes API server URL

--dest-namespace · string · required

Target namespace for resources

--sync-policy · string

Set to automated for automatic sync

--project · string

Argo CD project name (default: default)

Creating Applications Declaratively

Declarative application manifests provide version control, consistency, and enable GitOps workflows for managing applications themselves.

Basic Application Manifest

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  
  destination:
    server: https://kubernetes.default.svc
    namespace: default

Application with Auto-Sync

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-app
  namespace: argocd
spec:
  project: default
  
  source:
    repoURL: https://github.com/example/app.git
    targetRevision: HEAD
    path: manifests
  
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  
  syncPolicy:
    automated:
      enabled: true
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

Helm Application Manifest

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-helm-app
  namespace: argocd
spec:
  project: default
  
  source:
    repoURL: https://charts.example.com
    chart: my-chart
    targetRevision: 1.2.3
    helm:
      releaseName: my-release
      parameters:
      - name: replicaCount
        value: "3"
      - name: image.tag
        value: v1.0.0
        forceString: true
      valueFiles:
      - values-prod.yaml
  
  destination:
    server: https://kubernetes.default.svc
    namespace: default

Kustomize Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kustomize-app
  namespace: argocd
spec:
  project: default
  
  source:
    repoURL: https://github.com/example/kustomize-app.git
    targetRevision: HEAD
    path: overlays/production
    kustomize:
      namePrefix: prod-
      commonLabels:
        env: production
      images:
      - my-app=gcr.io/my-repo/my-app:v1.2.3
  
  destination:
    server: https://kubernetes.default.svc
    namespace: production

Application with Finalizers

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  # Add finalizer for cascade deletion
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  
  source:
    repoURL: https://github.com/example/app.git
    targetRevision: HEAD
    path: manifests
  
  destination:
    server: https://kubernetes.default.svc
    namespace: default

The resources-finalizer.argocd.argoproj.io finalizer enables cascade deletion. When you delete the Application, all deployed resources will also be deleted. Use resources-finalizer.argocd.argoproj.io/background for background deletion.

Multi-Source Applications

Argo CD supports applications with multiple sources, useful for combining Helm charts with external values files or mixing different repositories.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: multi-source-app
  namespace: argocd
spec:
  project: default
  
  sources:
  - repoURL: https://github.com/example/helm-charts.git
    targetRevision: HEAD
    path: charts/my-app
    ref: my-repo
  
  - repoURL: https://github.com/example/app-values.git
    targetRevision: HEAD
    path: values/production
  
  destination:
    server: https://kubernetes.default.svc
    namespace: production

Application Info

You can add extra information to display in the Argo CD Application details tab:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  
  info:
  - name: 'Documentation'
    value: 'https://docs.example.com'
  - name: 'Slack Channel'
    value: '#team-platform'
  
  source:
    repoURL: https://github.com/example/app.git
    targetRevision: HEAD
    path: manifests
  
  destination:
    server: https://kubernetes.default.svc
    namespace: default

Applying Declarative Manifests

Once you’ve created your Application manifest, apply it to the cluster:

kubectl apply -f application.yaml

Or using the Argo CD CLI:

argocd app create -f application.yaml

Declarative application manifests should be stored in Git to follow GitOps principles. This enables the “App of Apps” pattern where Argo CD manages its own application definitions.

Verifying Application Creation

Using CLI

# List all applications
argocd app list

# Get detailed application status
argocd app get my-app

# Watch application sync status
argocd app sync my-app --watch

Using kubectl

# List applications
kubectl get applications -n argocd

# Describe application
kubectl describe application my-app -n argocd

Best Practices

Use Projects

Organize applications into projects for better access control and resource isolation.

Version Control

Store declarative manifests in Git to track changes and enable rollbacks.

Naming Conventions

Use consistent naming patterns: <team>-<app>-<env> helps with organization.

Start Manual

Begin with manual sync policy, then enable auto-sync once you’re confident.

Next Steps

Sync Options

Configure how applications sync to the cluster

Sync Waves

Control deployment order with sync waves

Resource Hooks

Run jobs before, during, or after sync

Tracking Strategies

Learn about Git tracking methods