Module 00 · Orientation · 20 min · You are: Platform and product

Orientation: what Argo CD is and where it fits

Before GitOps, deploying meant a CI job with cluster-admin credentials running kubectl apply or helm upgrade. Nobody could say what was really running, a manual fix lasted until the next deploy, and every pipeline held the keys to production. Argo CD flips the direction: it runs inside the cluster, reads Git, and keeps the cluster equal to what Git says. In this course you play the platform team, who run Argo CD, and team-checkout, a product team that ships through it.

Open this module in the interactive course to track progress and switch tracks.

Concepts

What Argo CD is

A Kubernetes controller that continuously compares what Git declares with what runs in the cluster, shows the difference, and makes them equal: on request or automatically.

Pull, not push

CI builds and tests; it never touches the cluster. Argo CD pulls from Git with read-only access. No cluster credentials in pipelines, and every running object has a commit behind it.

Where it fits

Between your Git repositories and your clusters, owned by the platform team and used by every product team. The table below shows the layers.

Three repositories

argocd-platform (platform team), checkout-app (the application: chart and code), checkout-config (what runs in each environment). You create all three during the course.

A stand-in product

"checkout" is a made-up product. Its image is ghcr.io/stefanprodan/podinfo, a small public demo web app, so you need no code or CI. checkout-config is not the product's code repo: it holds only the Kubernetes files that say how the product runs. In a real company the code lives in another repo, and its CI builds the image these files point at.

This course and Fleet GitOps

Here: one cluster, Argo CD inside out. Fleet GitOps then takes it to many clusters with ApplicationSets, Terraform and a full change workflow. Nothing here is repeated there.

Where Argo CD fits in a platform

Argo CD is the delivery layer: it does not build images, run tests or create clusters.

Files to know

Where you are heading, in two minutes. These three files from the reference repo describe the finished setup. Click Quick look on each: it opens the real file right here, with numbered circles on the lines that matter. Skim them now; later modules come back to them.

Open them in your editor or on GitHub; the bullets say what to look at.

• README.md (reference): The map of the reference repo. Read the tables, skip the prose.
  1. The reference folders, the repo each becomes, and who owns it L15–26
  2. Every version is pinned, and where L30–37
  3. What the course simplifies on purpose L39–47
• docs/repositories.md (reference): Why three repositories, and what goes where.
  1. The three kinds side by side L3–11
  2. A rule worth remembering L21–29
• docs/operating-model.md (reference): How product teams work with Argo CD. You build towards this.
  1. Who owns what L3–13

Steps

1. Tell the course who you are

Your GitHub user (or organisation) and a folder for the three repos and the reference clone. Every command and link uses them. They stay in your browser.

Set your GitHub user and workspace folder in the interactive course or the form at the top of the notes index; these notes then show your values.

2. Pick where your cluster runs

kind is free and needs nothing but Docker: recommended. On an existing cluster you need cluster-admin and an ingress controller; only modules 01, 05 and 06 differ.

These notes show kind commands, with the existing-cluster variants folded underneath.

3. Check your tools

Paste this into a terminal. Each tool reports ok (with its version), MISSING (with where to get it) or PROBLEM (installed but not usable yet, like Docker not running or gh not logged in). Install what is missing your usual way (Homebrew, apt, the links), then run it again until it says All set. Versions: kind 0.27+, Helm 4, Docker with 4 GB of memory. kubeseal is used later in the course.

check() {  # tool, works-check, version, problem, where-to-get-it, optional
  if ! command -v "$1" >/dev/null 2>&1; then
    if [ -n "$6" ]; then printf '  optional  %-22s not installed (%s)\n' "$1" "$5"
    else printf '  MISSING   %-22s install it: %s\n' "$1" "$5"; bad=$((bad+1)); fi
  elif ! eval "$2" >/dev/null 2>&1; then printf '  PROBLEM   %-22s %s\n' "$1" "$4"; [ -n "$6" ] || bad=$((bad+1))
  else printf '  ok        %-22s %s\n' "$1" "$(eval "$3" 2>&1 | head -n 1)"; fi
}
bad=0
check 'git' 'git --version' 'git --version' 'installed, but it does not run' 'https://git-scm.com/downloads'
check 'docker' 'docker info' "docker version --format '{{.Server.Version}}'" 'installed, but the Docker daemon is not running: start Docker Desktop (or the docker service)' 'https://docs.docker.com/get-docker/'
check 'kind' 'kind version' 'kind version' 'installed, but it does not run' 'https://kind.sigs.k8s.io/docs/user/quick-start/#installation'
check 'kubectl' 'kubectl version --client' 'kubectl version --client' 'installed, but it does not run' 'https://kubernetes.io/docs/tasks/tools/'
check 'helm' "helm version --short | grep -q '^v4'" 'helm version --short' 'Helm 3 found: this course uses Helm 4' 'https://helm.sh/docs/intro/install/'
check 'argocd' 'argocd version --client' 'argocd version --client --short' 'installed, but it does not run' 'https://argo-cd.readthedocs.io/en/stable/cli_installation/'
check 'kubeseal' 'kubeseal --version' 'kubeseal --version' 'installed, but it does not run' 'https://github.com/bitnami-labs/sealed-secrets#kubeseal'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/'
check 'perl' 'perl -v' "perl -e 'print qq(perl $^V)'" 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
check 'openssl' 'openssl version' 'openssl version' 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
check 'python3' "python3 -c 'import yaml, jsonschema'" 'python3 --version' 'installed, but modules are missing: python3 -m pip install --user pyyaml jsonschema' 'https://www.python.org/downloads/'
if [ "$bad" -eq 0 ]; then echo "All set: every tool is ready."; else echo "$bad tool(s) need attention. Install or fix them, then run this check again."; fi

check() {  # tool, works-check, version, problem, where-to-get-it, optional
  if ! command -v "$1" >/dev/null 2>&1; then
    if [ -n "$6" ]; then printf '  optional  %-22s not installed (%s)\n' "$1" "$5"
    else printf '  MISSING   %-22s install it: %s\n' "$1" "$5"; bad=$((bad+1)); fi
  elif ! eval "$2" >/dev/null 2>&1; then printf '  PROBLEM   %-22s %s\n' "$1" "$4"; [ -n "$6" ] || bad=$((bad+1))
  else printf '  ok        %-22s %s\n' "$1" "$(eval "$3" 2>&1 | head -n 1)"; fi
}
bad=0
check 'git' 'git --version' 'git --version' 'installed, but it does not run' 'https://git-scm.com/downloads'
check 'kubectl' "kubectl auth can-i '*' '*' --all-namespaces" 'kubectl config current-context' 'installed, but you are not cluster-admin on the current context: check kubectl config current-context' 'https://kubernetes.io/docs/tasks/tools/'
check 'helm' "helm version --short | grep -q '^v4'" 'helm version --short' 'Helm 3 found: this course uses Helm 4' 'https://helm.sh/docs/intro/install/'
check 'argocd' 'argocd version --client' 'argocd version --client --short' 'installed, but it does not run' 'https://argo-cd.readthedocs.io/en/stable/cli_installation/'
check 'kubeseal' 'kubeseal --version' 'kubeseal --version' 'installed, but it does not run' 'https://github.com/bitnami-labs/sealed-secrets#kubeseal'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/'
check 'perl' 'perl -v' "perl -e 'print qq(perl $^V)'" 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
check 'openssl' 'openssl version' 'openssl version' 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
check 'python3' "python3 -c 'import yaml, jsonschema'" 'python3 --version' 'installed, but modules are missing: python3 -m pip install --user pyyaml jsonschema' 'https://www.python.org/downloads/'
if [ "$bad" -eq 0 ]; then echo "All set: every tool is ready."; else echo "$bad tool(s) need attention. Install or fix them, then run this check again."; fi

4. Clone the reference repo

The finished implementation. You copy from it; you never push to it.

mkdir -p ~/work && git clone -q https://github.com/platformengr/argocd-gitops.git ~/work/argocd-gitops

Check that it arrived. You should see folders such as cluster, platform, checkout-config and docs: one per thing you will build.

ls ~/work/argocd-gitops

Quiz

1. What does Argo CD do that a CI job running kubectl apply does not?
   • It keeps comparing the cluster with Git after the deploy, shows drift, and can correct it
   • It builds and scans container images before every deploy, so a CI job is no longer needed
   • It runs the same kubectl apply, only faster, because it caches manifests inside the cluster
2. Why is pull-based delivery safer?
   • Pulling is encrypted end to end, while a pipeline pushing to the cluster always sends credentials in clear text
   • No pipeline holds cluster credentials; Argo CD only needs read access to Git
   • Argo CD can only ever read from Git, so a bad commit cannot change anything in the cluster, whoever merges it
3. Which repository says which version runs in prod?
   • The application repository (checkout-app), because every merge there ends up as a new running version in prod
   • The platform repository, because it holds the cluster add-ons and therefore decides what every team runs
   • The environment repository (checkout-config)

Field note

In every workshop, the people who learned the most were the ones who resisted kubectl edit, even when it was quicker. Argo CD will undo your shortcut anyway; the habit is the lesson.

Report a problem with this module