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

Orientation: the platform you will run

You will play two roles at a small company: the platform team, who run the clusters, and team-checkout, a product team that wants to ship. Every change either of them makes is a GitHub issue, then a pull request, then something Argo CD reconciles. By the end you will have run that loop for infrastructure, platform capabilities and a product, and broken it on purpose in the ways real fleets break.

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

Concepts

End result vs full course

See the end result creates the finished fleet from the template in about 30 minutes, with few explanations: a preview, not a first step. This course builds the same fleet piece by piece, in the order a platform team would, and explains each piece.

Reference repo vs your repo

The reference repo is the finished implementation. Your repo starts empty; each module brings in one folder from the reference through a pull request. Argo CD watches your repo, never the reference.

Platform and product

The platform team owns clusters, Argo CD, policies and the namespace baseline. Product teams own their deployment config. CODEOWNERS turns that split into review rules.

The change journey

Requested, proposed, validated, previewed, approved, merged, reconciled, healthy. Every module shows which of these steps it practises.

Required vs flexible

Required: GitHub (issues, pull requests, Actions) and Git as the source of truth. Flexible: where Kubernetes runs. kind on your laptop is the default; AKS, EKS, GKE or any existing cluster work too.

Files to know

Where you are heading, in two minutes. These three files from the reference repo describe the finished fleet. 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, your repo): The map of the repo. Read the three tables, skip the prose.
  1. Reference repo, your repo, quick start, full course: what each one is L16–25
  2. Every folder and which team owns it L47–61
  3. What this workshop simplifies on purpose L111–120
• docs/fleet-architecture.md (reference, your repo): Where you are heading: the whole system in one picture.
  1. The layers, their files, and who owns each one L55–66
  2. Every Argo CD Application the repo creates, and from which file L68–81
• docs/operating-model.md (reference, your repo): How people work with the fleet. Two tables are enough for now.
  1. Who owns what: platform, product, shared L5–14
  2. The eight steps every change goes through L19–33

Steps

1. Tell the course who you are

Your GitHub user (or organisation), the name of the repo you will create, and where to clone it. Every command and link in the course uses these. They stay in your browser.

Set your GitHub user, repository and 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 clusters run

kind is free and needs no cloud account: recommended for the whole course. On a cloud track only module 02 differs (scripts instead of Terraform), and you pay while clusters run.

These notes show kind commands, with the cloud 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 a cloud CLI not logged in). Install what is missing your usual way, then run it again until it says All set. Python is for the repo's validation script; the GitHub CLI is optional, every step also works in the browser. Versions: Terraform 1.6+, Docker with 8 GB of memory on kind.

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 'terraform' 'terraform version' 'terraform version' 'installed, but it does not run' 'https://developer.hashicorp.com/terraform/install'
check 'kubectl' 'kubectl version --client' 'kubectl version --client' 'installed, but it does not run' 'https://kubernetes.io/docs/tasks/tools/'
check 'helm' 'helm version' 'helm version --short' 'installed, but it does not run' 'https://helm.sh/docs/intro/install/'
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/'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/' optional
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 'az' 'az account show' 'az version --query \"azure-cli\" -o tsv' 'installed, but not logged in: run az login' 'https://learn.microsoft.com/cli/azure/install-azure-cli'
check 'kubectl' 'kubectl version --client' 'kubectl version --client' 'installed, but it does not run' 'https://kubernetes.io/docs/tasks/tools/'
check 'helm' 'helm version' 'helm version --short' 'installed, but it does not run' 'https://helm.sh/docs/intro/install/'
check 'terraform' 'terraform version' 'terraform version' 'installed, but it does not run' 'https://developer.hashicorp.com/terraform/install'
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/'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/' optional
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 'aws' 'aws sts get-caller-identity' 'aws --version' 'installed, but no credentials: run aws configure (or aws sso login)' 'https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html'
check 'eksctl' 'eksctl version' 'eksctl version' 'installed, but it does not run' 'https://eksctl.io/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' 'helm version --short' 'installed, but it does not run' 'https://helm.sh/docs/intro/install/'
check 'terraform' 'terraform version' 'terraform version' 'installed, but it does not run' 'https://developer.hashicorp.com/terraform/install'
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/'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/' optional
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 'gcloud' 'gcloud auth print-access-token' 'gcloud --version' 'installed, but not logged in: run gcloud auth login' 'https://cloud.google.com/sdk/docs/install'
check 'gke-gcloud-auth-plugin' 'gke-gcloud-auth-plugin --version' 'gke-gcloud-auth-plugin --version' 'installed, but it does not run' 'gcloud components install gke-gcloud-auth-plugin'
check 'kubectl' 'kubectl version --client' 'kubectl version --client' 'installed, but it does not run' 'https://kubernetes.io/docs/tasks/tools/'
check 'helm' 'helm version' 'helm version --short' 'installed, but it does not run' 'https://helm.sh/docs/intro/install/'
check 'terraform' 'terraform version' 'terraform version' 'installed, but it does not run' 'https://developer.hashicorp.com/terraform/install'
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/'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/' optional
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

Quiz

1. Why does Argo CD watch your repo and not the reference repo?
   • GitOps is pull-based: you change the fleet by changing the repo Argo CD watches, so it must be one you can merge into
   • The reference repo is read-only for Argo CD, so it can only ever watch a repository you own, and that is the sole reason to fork it
   • Watching the reference repo would make every fleet change land in everyone's cluster at the same time, which no team would accept
2. Who owns the namespace baseline (quota, network policy, RBAC) of a product?
   • The product team, since it knows best which quota and network rules its own workloads need
   • The platform team
   • Whoever creates the namespace first, because ownership follows the first commit that mentions it
3. What is the difference between the end-result preview and the full course?
   • The preview runs on entirely different tools and templates, so nothing you build there carries over into the full course at all
   • They are the same exercise: the full course only adds longer explanations and a few extra clusters, but builds the identical repo in one go
   • The preview creates the finished fleet from the template; the full course builds it piece by piece and explains each piece

Field note

In every run of this workshop, the people who got the most out of it changed things only through pull requests, even when kubectl was quicker. The habit is the lesson.

Report a problem with this module