Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

Your First Argo CD Application: Deploy from Git

Create and sync your first Argo CD Application from a Git repository: the repo layout, the Application manifest, what happens on sync, and how to change and delete it safely.

Time to deploy something. An Argo CD Application is a Kubernetes custom resource that says "take the manifests at this path of this Git repository and make them exist in that namespace of that cluster". In this lesson you will build a tiny repository, write the Application that points at it, sync it and then change it through Git.

You need your own cluster with Argo CD installed (Installing Argo CD). The YAML and commands are read-only here; the two runnable blocks are stand-ins that validate and summarize manifests so you can check your own files before committing them.

Step 1: a Git repository with manifests

Create a repository (any Git host works) with this layout:

TEXT
gitops-demo/
โ””โ”€โ”€ apps/
    โ””โ”€โ”€ hello/
        โ”œโ”€โ”€ deployment.yaml
        โ””โ”€โ”€ service.yaml

apps/hello/deployment.yaml:

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: web
          image: nginxdemos/hello:plain-text
          ports:
            - containerPort: 80

apps/hello/service.yaml:

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

Notice there is no namespace: in the manifests. Argo CD applies them to the namespace chosen in the Application, which keeps the same files reusable.

Step 2: the Application manifest

YAML
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/gitops-demo.git
    targetRevision: main
    path: apps/hello
  destination:
    server: https://kubernetes.default.svc
    namespace: hello
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

Field by field:

  • metadata.namespace: argocd: Application objects live in Argo CD's own namespace.
  • project: the AppProject that governs it; default allows everything and is fine for learning (AppProjects explains why you will outgrow it).
  • source: repository URL, branch/tag/commit (targetRevision) and directory (path).
  • destination: the cluster (https://kubernetes.default.svc means the cluster Argo CD runs in) and the target namespace.
  • CreateNamespace=true lets Argo CD create the hello namespace.

Apply it once with kubectl apply -n argocd -f hello-app.yaml. (Later you will keep Application manifests in Git too.) For a public repository no credentials are needed.

Step 3: look, then sync

The new application appears as OutOfSync and Missing: Git describes resources that do not exist yet. A manual sync is the default, so nothing is created until you ask:

Terminal
argocd app diff hello
argocd app sync hello
argocd app wait hello --health

Or press Sync and then Synchronize in the UI. Argo CD creates the namespace, applies the Deployment and Service, and watches the pods until they are ready. When finished you see Synced and Healthy.

What really happened

  1. The repo server cloned the repository at main and read apps/hello as a plain directory of YAML.
  2. The controller found nothing live, so the diff showed two resources to create.
  3. The sync applied them with server-side or client-side apply (you choose later) and recorded the revision in the Application's history.
  4. Health checks watched the Deployment until the ReplicaSet reported available replicas.

Step 4: change it through Git

Edit replicas: 2 to replicas: 3, commit and push. Within three minutes (or immediately after a manual Refresh) the app turns OutOfSync, and the diff shows exactly one line changed. Sync again and the third pod appears. You never ran kubectl against the Deployment.

Now try the opposite, a manual change:

Terminal
kubectl -n hello scale deployment hello --replicas=1

Argo CD reports the app OutOfSync again, because live now differs from Git. Syncing restores 3. Turning that restoration into an automatic behavior is the job of self-heal (Sync Policies).

Stand-in: check manifests before you commit

This model parses a small YAML-like list of objects (already converted to JavaScript objects) and applies a few checks that Argo CD or Kubernetes would otherwise complain about later.

JS Stand-in: manifest pre-flight check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: simulate the first sync

The second stand-in walks the lifecycle you just read about: Missing, sync, Progressing, Healthy.

JS Stand-in: first sync timeline

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Cleaning up

Terminal
argocd app delete hello --cascade

With cascade (the default when a finalizer is set) Argo CD deletes the resources it created. Without a finalizer on the Application, deleting only the Application leaves the Deployment running as an orphan. Finalizers are covered in the next chapters.

Common first-time mistakes

  • Pointing path at the wrong directory (the app then shows an error about no manifests).
  • A private repository without credentials (Repositories and Credentials).
  • Hard-coded namespace: fields in manifests that fight the destination.
  • Expecting a push to deploy instantly without a webhook or refresh.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which namespace must an Application custom resource normally live?

    Application objects are stored in Argo CD's namespace; destination.namespace is where the workloads go.
  2. 2. What does https://kubernetes.default.svc mean as a destination server?

    It is the in-cluster Kubernetes API address, used for the local cluster.
  3. 3. A new Application with manual sync shows OutOfSync and Missing. What should you expect?

    Manual sync is the default; Argo CD only reports the difference until you sync.
  4. 4. You scale the Deployment with kubectl. What does Argo CD report?

    Live state no longer matches Git, so the app is OutOfSync until you sync (or self-heal does it).

Summary

  • An Application ties a Git source to a cluster destination, governed by a project.
  • Plain directories of YAML are the simplest source type.
  • Manual sync creates and updates resources; the result is Synced and Healthy.
  • Change things through Git commits; manual cluster edits show up as drift.
  • Avoid hard-coded namespaces and always point path at the right folder.

Next: GitOps Principles