Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: Bootstrap a Platform from One Repository

Rebuild a whole cluster from Git: install Argo CD, apply a root Application, order platform add-ons with sync waves and onboard teams with ApplicationSets.

In this project you build the bootstrap of a platform: a brand-new cluster becomes a fully configured one by installing Argo CD and applying a single file. You combine ideas from earlier lessons: the app of apps pattern, ApplicationSets, secrets handling and RBAC. The cluster itself is not available on this site, so the steps are files and commands to run on your own cluster, and a stand-in checks the ordering logic.

The target

flowchart TB
  B["Bootstrap: install Argo CD, apply root"] --> R["root Application"]
  R --> W0["Wave 0: CRDs, namespaces, Argo CD self-management"]
  W0 --> W1["Wave 1: secrets (ESO), cert-manager, ingress"]
  W1 --> W2["Wave 2: monitoring, policies"]
  W2 --> W3["Wave 3: team ApplicationSets"]
  W3 --> T["Team applications"]

Platform components first, then the teams that depend on them.

Repository layout

TEXT
platform-gitops/
  bootstrap/
    root.yaml              # the only file applied by hand
  argocd/                  # Argo CD's own configuration (self-managed)
    kustomization.yaml     # install manifests + cm, rbac-cm patches
  platform/                # child Applications of the root
    00-crds.yaml
    10-external-secrets.yaml
    11-cert-manager.yaml
    12-ingress.yaml
    20-monitoring.yaml
    30-teams.yaml          # ApplicationSet generating team apps
  teams/
    shop/config.json
    search/config.json

Step 1: Install Argo CD

Use a pinned version from the official install manifests, through Kustomize so your configuration patches live in Git:

YAML
# argocd/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd
resources:
  - https://raw.githubusercontent.com/argoproj/argo-cd/v3.0.0/manifests/install.yaml
patches:
  - path: argocd-cm-patch.yaml
  - path: argocd-rbac-cm-patch.yaml

Replace the version with a release you have verified. For the first install, apply it once by hand with server-side apply (kubectl apply -k argocd --server-side), after creating the argocd namespace.

Step 2: The root Application

YAML
# bootstrap/root.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: platform
  source:
    repoURL: https://git.example.com/platform/platform-gitops.git
    targetRevision: main
    path: platform
  destination:
    name: in-cluster
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Apply it with kubectl apply -f bootstrap/root.yaml. The root creates every child Application found in platform/. Also register the repository credential first (a one-time step, or a Secret from your secret manager).

Step 3: Order with sync waves

Each child carries a wave annotation matching its dependency:

File Wave Why
00-crds.yaml 0 Custom resources need their CRDs first
10-external-secrets.yaml 1 Provides Secrets other components read
11-cert-manager.yaml 1 Issues certificates for ingress
12-ingress.yaml 2 Needs certificates and secrets
20-monitoring.yaml 3 Needs ingress and storage
30-teams.yaml 4 Team apps assume everything above
YAML
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "2"

Argo CD syncs wave by wave, waiting for each wave's resources to become healthy before starting the next. Application resources report health only when the child application is healthy, so the ordering holds across children. Keep the dependency list as a table in the repository README so reviewers can reason about it.

Step 4: Team onboarding with an ApplicationSet

YAML
# platform/30-teams.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: teams
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "4"
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
    - git:
        repoURL: https://git.example.com/platform/platform-gitops.git
        revision: main
        files:
          - path: "teams/*/config.json"
  template:
    metadata:
      name: "team-{{ .team }}"
    spec:
      project: "team-{{ .team }}"
      source:
        repoURL: "{{ .repo }}"
        targetRevision: main
        path: "{{ .path }}"
      destination:
        name: in-cluster
        namespace: "{{ .team }}"
      syncPolicy:
        automated: {prune: true, selfHeal: true}
        syncOptions: [CreateNamespace=true]

A team is onboarded by adding teams/<name>/config.json with team, repo and path. You would pair this with a generated AppProject per team (another ApplicationSet or a Kustomize component) that restricts repositories and namespaces, and RBAC group mappings so each team can only sync its own apps.

Step 5: Rehearse recovery

A bootstrap is only valuable if you can run it from nothing:

  1. Create a fresh cluster (a throwaway local one is fine).
  2. Restore the repository credential and your secret-manager access.
  3. Apply argocd/ and then bootstrap/root.yaml.
  4. Watch argocd app list until everything is Synced and Healthy.

Time it, write down what failed and fix the repository so it needs fewer manual steps. See Upgrades, Backup and Disaster Recovery.

Stand-in: wave planner

The stand-in checks a set of components with dependencies, assigns the earliest valid wave to each (a topological layering) and flags cycles. Use it as a pre-commit lint for the platform folder.

Python Stand-in: assign sync waves from dependencies

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stretch goals

  • Make Argo CD manage itself: add an Application for argocd/ in wave 0 with prune: false for the CRDs.
  • Add a cluster generator so add-ons install on every registered workload cluster.
  • Send notifications for failed waves to a platform channel.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file is applied by hand in a bootstrap?

    The root creates all children, so the one manual step is applying it.
  2. 2. Why do CRDs belong in an early sync wave?

    Applying a custom resource before its CRD exists fails.
  3. 3. How is a new team onboarded in this design?

    The Git files generator turns each config.json into an Application.
  4. 4. Why rehearse the bootstrap on a fresh cluster?

    An untested recovery path is an assumption.

Summary

  • A bootstrap is: install Argo CD, apply the root Application, and let it create everything else.
  • Sync waves order platform components by dependency; ApplicationSets onboard teams from small config files.
  • Keep Argo CD's own configuration in Git and rehearse the whole procedure on a fresh cluster.

Next: Practice: Argo CD Scenarios