Airframe Quickstart

Tower → Create → NodeJSApplication

Every Bootstrap-tier stack — NodeJS, Spring Boot, Go, Python, InfraService — is a Backstage Scaffolder template generated from its XRD. Fill in:

Submitting opens a PR into gitops-cluster-dev-tenants at tenants/boarding-api/xr-requests/boarding-api.yaml. Merge it — the xr-requests ApplicationSet applies that file to the dev cluster as a NodeJSApplication XR.

Check the XR

$ kubectl get nodejsapplication boarding-api -n app-boarding-api-cicd
NAME           SYNCED   READY   COMPOSITION                         AGE
boarding-api   True     True    nodejsapplications.catalog.idp.io   3m

kubectl describe shows the two custom conditions this catalog adds: DevClusterReady and CicdOnboarded (Glidepath has picked the app up).

Crossplane creates the real boarding-api source repo and an empty gitops-boarding-api repo. The source repo starts with a hello-world index.js, a package.json, a Containerfile and a minimal cicd.yaml (build only, agent: nodejs-20, unit tests off). You have a repo — but no running pipeline, and nothing deployed.

Find the onboarding PR

Once the app is registered, Glidepath's onboarding hook notices your repo has no .tekton/onboarding-resync.yaml and opens a PR against boarding-api (and gitops-boarding-api) adding the generated .tekton/*.yaml files. Find it in GitHub or in Tower's Pull Requests tab.

Merge it

Until it's merged, pushing to main does nothing — PaC finds no pipeline to run. Once merged, a push runs the scaffolded build stage and publishes a multi-arch image to ghcr.io/<owner>/boarding-api.

These files are never hand-edited. Every later push that changes cicd.yaml opens a fresh PR regenerating .tekton/ if anything changed — merge those too. If nothing happens after you push, first check that the platform's GitHub App has access to the repo.

Declare the environment

boarding-api/platform/envs/dev.yaml ground

# envName, not env — env is a reserved key in the chart's container env-var list.
# rollout: null must be explicit — omitting it makes the chart render its own
# default rollout with an empty image (two InvalidImageName pods).
envName: dev
rollout: null

A dev-cluster-only ApplicationSet (boarding-api-lower-envs) watches platform/envs/*.yaml in your repo. Within a sync interval you get an empty namespace, app-boarding-api-dev, with the baseline ServiceAccount and NetworkPolicy and no workload.

Let the pipeline deploy to it

Replace the scaffolded cicd.yaml with a flow that builds, tests and deploys to dev:

boarding-api/cicd.yaml ground

apiVersion: platform/v1
kind: PipelineConfig

build:
  agent: nodejs-20
  unitTest:
    enabled: true         # runs ./test.sh, which the code you copied in provides

deploy:
  lowerEnvironments: [dev]

pipelines:
  ci:
    trigger: { source: git, event: push, branch: main }
    steps:
      - stage: build
      - stage: test
        env: dev
      - stage: deploy
        env: dev

Commit both files, merge the .tekton PR

Changing cicd.yaml triggers section 03's resync: a new PR regenerates .tekton/. Merge it. Separately, ArgoCD reads the new cicd.yaml and provisions the deploy RBAC for app-boarding-api-dev.

Run it, then look at it

Push to main. The deploy stage commits rollout.image.repository and rollout.image.tag directly into platform/envs/dev.yaml on main — no branch, no PR. git pull before your next push, or you'll be rebasing over the bot's commit.

platform/envs/dev.yaml after the first deploy

envName: dev
rollout:
  image:
    repository: ghcr.io/jfillman/boarding-api
    tag: 0.1.0-a1b2c3d

Chart defaults cover the rest: two replicas, port 8080 named http, no probes.

kubectl port-forward -n app-boarding-api-dev svc/boarding-api 8080:8080

Open http://localhost:8080. Look up AC123 twice: the second answer is a cache hit, a few milliseconds instead of ~400. Press Scan a boarding pass several times: the counter jumps around, because the two pods each count on their own (counter: memory). Keep that in mind for section 08. To change ground settings, edit platform/envs/dev.yaml directly.

Declare it in cicd.yaml

The release stage supplies the image to a flight env, and Tower's App Configuration tab builds its environment list from upperEnvironments:

boarding-api/cicd.yaml — additions flight

deploy:
  lowerEnvironments: [dev]
  upperEnvironments:
    - { name: staging, cluster: prod }

governance:
  allowedCommitSigners:
    - you@example.com   # with no signers every release fails the
                        # commit-signature gate

pipelines:
  ci:
    trigger: { source: git, event: push, branch: main }
    steps:
      - stage: build
      - stage: test
        env: dev
      - stage: deploy
        env: dev
      - stage: release
        env: staging

Merge the .tekton/ PR this push opens. Glidepath's examples/04-multi-env-promotion.yaml and 10-production-grade.yaml show the governance options.

Tower → Create → ApplicationEnvironment

The Crossplane Settings page can stay at its defaults. Submitting opens a PR into gitops-cluster-dev-tenants (tenants/boarding-api/xr-requests/boarding-api-prod-staging.yaml). Merge it. Crossplane commits a bootstrap values.yaml to gitops-boarding-api/prod/staging/ and an onboarding entry to prod's own tenants repo, so the prod cluster's own ArgoCD picks the env up — no cross-cluster credential is involved.

$ kubectl get applicationenvironment -n app-boarding-api-cicd
NAME                             SYNCED   READY   COMPOSITION                              AGE
boarding-api-prod-staging   True     True    applicationenvironments.catalog.idp.io   2m

kubectl describe shows ClusterReady: True and WorkloadDeployed: False. The bootstrap file is rollout: null: a namespace, no workload.

Configure it: Tower → boarding-api → App Configuration

Pick environment staging. The active environment is shown prominently at the top; check it before saving. Turn on the Deployment switch — an env with rollout: null deploys no Rollout, Service, HPA or PDB — and fill in:

Save opens a pull request into gitops-boarding-api — never a direct commit, in any environment. The tab validates the change against the chart's own values.schema.json first. Merge the PR. There is no image field: the image comes from the release pipeline in the next step, so until it runs the Rollout has no image to start.

Release an image

Push to main. After build, test and deploy to dev, the release stage opens a PR against gitops-boarding-api setting rollout.image for staging. Merge it as a signed commit — GitHub's merge button produces an unsigned one (see Glidepath's docs/admin/commit-signing.md, "Merge strategy matters"). The prod cluster's ArgoCD syncs it, and WorkloadDeployed flips to True once a real Rollout exists.

Start with v1 in flight

Section 07 done, image released. Port-forward to the staging Service and open the board: one solid bar, v1.0.0: 100%.

Make v2

Set "version": "2.0.0" in package.json, commit and push to main. The pipeline builds, tests, deploys to dev and opens a release PR for staging; merge it as a signed commit.

Watch the canary

The Rollout doesn't replace v1; it steps. With the default canary steps and four replicas the bar goes from all-v1 to about a quarter v2, then half, then all. The chart has no traffic router, so the split is by pod count, not request weight. A step that pauses without a duration waits for you.

kubectl argo rollouts get rollout boarding-api -n app-boarding-api-staging --watch
kubectl argo rollouts promote boarding-api -n app-boarding-api-staging   # if paused

Press Reset tally between steps to see the current mix rather than a running average. Look up AC123: only v2 pods show the boarding-group line, and answered by names the version you got.

Blue/green, or roll back

Set the env's rollout.strategy: blueGreen and the chart renders two Services, boarding-api (active) and boarding-api-preview. Port-forward to the preview to see v2 at 100% while active still shows v1; after promotion the bar flips in one step. To roll back, abort the rollout or revert the release PR.