Skip to content

Try it in one command

This is the shortest path through kensan-lab. In about ten minutes you will inspect a GitOps-managed cluster, open an SSO-protected demo, create a second application through Backstage, merge its pull request, watch its CPU usage change in Grafana, and scale it twice — once the way the platform accepts, once the way it undoes.

Pull requests that touch the platform stand this same environment up on CI and sign in to it, so what follows is checked rather than merely written down.

The bare-metal cluster is not required, and that is why this page exists. kensan-lab runs on hardware at home, and the bootstrapping guide documents that cluster as a reference — it describes what is running, not a clean-room install, and standing one up from nothing is not automated yet. So the way in is a disposable, single-node kind cluster that runs the same manifests and binds its gateway only to 127.0.0.1.

1. Start the platform

You need Docker with at least 8 GiB of memory, plus kind, kubectl, helm, curl, and make.

Install Docker Desktop, set Settings → Resources → Memory to at least 8 GiB, then install the command-line tools:

brew install kind kubectl helm

Install Docker Engine and the kind, kubectl, and Helm CLIs.

Then clone and start the environment:

git clone https://github.com/yu-min3/kensan-lab
cd kensan-lab
make try

make try checks the prerequisites, builds the demo and Backstage images from your checkout, creates the cluster, and waits until every Argo CD Application is healthy. The initial image build can take several minutes; later runs reuse Docker's layer cache.

The account used across the platform is fixed for this disposable environment:

User Password Used for
demo demo Demo apps, Argo CD SSO, Backstage, Grafana SSO, and Gitea

2. Accept the local certificate

Every browser URL uses HTTPS. cert-manager creates a local certificate authority and signs *.127-0-0-1.sslip.io, but your browser does not trust that new CA. The Your connection is not private warning is therefore expected.

For a quick walkthrough, choose Advanced and then Proceed to …127-0-0-1.sslip.io (unsafe). The gateway listens only on localhost.

If you prefer to trust the generated root explicitly, export it before opening the sites:

kubectl -n cert-manager get secret explore-ca-tls \
    -o jsonpath='{.data.ca\.crt}' | base64 --decode \
    > /tmp/kensan-lab-explore-ca.crt
sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain \
    /tmp/kensan-lab-explore-ca.crt

Remove it when the walkthrough is finished:

sudo security delete-certificate -c "kensan-lab explore" \
    /Library/Keychains/System.keychain

Open the browser's certificate settings, import /tmp/kensan-lab-explore-ca.crt under Authorities, and allow it to identify websites. Remove the kensan-lab explore authority afterwards.

Importing the root is optional. The environment never changes the host trust store automatically.

3. See GitOps in Argo CD

Open Argo CD and choose Log in via Keycloak. Sign in with demo / demo.

Open explore-root. It is the root Application that creates the platform's other Applications. app-demo, backstage, grafana, and the rest should be Synced and Healthy.

Argo CD is the GitOps controller for this cluster. It continuously traces the kensan-lab repository in the in-cluster Gitea, renders the declared Helm and Kubernetes resources, and reconciles them into the cluster. A green Synced / Healthy application therefore means both that the live resources match Git and that their workloads are running successfully.

Argo CD showing explore-root and the Applications it created

The same state is available from the terminal:

make explore-status

4. Open the existing demo

Open the demo application. Keycloak should reuse the session from Argo CD, so no second password prompt appears.

The app displays its name, theme, greeting, and the identity headers attached by the gateway. The application itself contains no login implementation: Istio asks oauth2-proxy to authenticate the request before it reaches the pod. The load button near the bottom belongs to step 7; leave it alone for now.

The existing demo application after signing in

sequenceDiagram
    participant Browser
    participant Gateway as Istio Gateway
    participant Auth as oauth2-proxy + Keycloak
    participant App as demo app
    Browser->>Gateway: HTTPS request
    Gateway->>Auth: Is this session valid?
    Auth-->>Gateway: Yes + user identity
    Gateway->>App: Request + identity headers
    App-->>Browser: Render the demo

5. Create a different app in Backstage

Open Backstage, then select Create → Golden Path Application. The Explore catalog has one owner, demo-team, so the walkthrough does not ask you to choose among production teams.

The Golden Path Application form in Backstage

The application name is yours. One field decides what the platform builds, so the rest of this page writes it as <name> in the text and $APP in the commands. The screenshots were taken with app2.

Field Value
Application Name <name> — anything you like
Description Second walkthrough application
Repository owner demo, repository <name>
Theme night
Greeting Hello from the golden path

Everything the platform names after it:

Thing Named With app2
Argo CD Application, namespace app-<name> app-app2
Deployment, Service <name> app2
Hostname <name>.127-0-0-1.sslip.io app2.127-0-0-1.sslip.io
Gitea repository demo/<name> demo/app2

Set the name once in the terminal you are going to use, and every command below works unchanged:

APP=app2   # whatever you typed in the form

Review the values and press Create. Backstage now:

flowchart TD
    A[Backstage form] --> B[Create NAME repository in local Gitea]
    B --> F[Gitea Actions tests and builds NAME]
    F --> G[Push commit-SHA image]
    G --> H[Record image tag in deploy/values.yaml]
    H --> C[Open platform-config PR]
    C --> D[Register NAME in the catalog]
    C --> E[Register the new SSO callback]
    C --> I{You merge the PR}
    I --> J
    J[Argo CD discovers app-NAME]
    J --> K[NAME is running]

The task stays open while Gitea Actions tests the generated source, builds an image for that repository alone, pushes it, and writes its immutable commit SHA into deploy/values.yaml. A failed build fails the Backstage task and no platform pull request is created. A completed task means the pull request is safe to review and merge.

6. Merge the local pull request

Follow Review the kensan-lab pull request from Backstage, or open the kensan-lab pull requests in Gitea. Gitea does not share the Keycloak browser session, but it uses the same memorable credentials: sign in with demo / demo.

You are the platform administrator for this part of the walkthrough. The new Platform Config PR should already be waiting in demo/kensan-lab. It adds two files under environments/kind/generated-applications/app-<name>/; merge it.

Gitea showing the platform pull request ready for review

Merging does not deploy from Gitea directly. It updates the Git source of truth; Argo CD notices that change on its next poll, creates the child Application, and reconciles the workload. This can take about four minutes after the merge.

flowchart LR
    M[1. Merge PR<br/>in Gitea] --> G[2. main changes<br/>in demo/kensan-lab]
    G -->|Argo CD polls Git| A[3. Argo CD<br/>creates app-NAME]
    A --> K[4. Kubernetes<br/>deploys the SHA image]
    K --> B[5. Open<br/>NAME.127-0-0-1.sslip.io]

Watch the new Argo CD Application appear:

kubectl -n argocd get application app-$APP -w

When it is Synced and Healthy, open https://<name>.127-0-0-1.sslip.io and compare it with the original demo. Your service runs an image built from its own repository, and its night theme and greeting came from Git-managed runtime values rather than from that image.

Editing the service's own source and watching a new image reach the cluster is the natural next question. It costs a build, so it lives in Source change exercise rather than here.

7. Watch CPU rise and fall in Grafana

Open the Explore App Runtime dashboard in Grafana. Choose Sign in with Keycloak if asked. It shows one Deployment's CPU, desired and available replicas, request rate, and request latency.

It opens on the built-in demo application. Set the Namespace picker to app-<name> and the Workload picker to <name> first. Both pickers are filled from the cluster, so they list whatever you called your service — and the panels stay empty until they point at a workload that exists.

Then open your application in another tab and press Generate load for 90s. It is the same button you saw on the demo app in step 4, and it belongs to the service you just deployed: it occupies one core inside the pod and counts down while it does.

The Explore App Runtime dashboard while the load button is running

The line does not jump the moment you press: Grafana is reading the pod's real CPU through Prometheus, so it climbs over the next few samples, holds, and drops back once the ninety seconds are up.

8. Scale it, and watch Git win

The Replicas panel is where the GitOps contract becomes visible. Change the replica count twice — once from the cluster, once from Git — and watch which one survives.

From the cluster. Argo CD puts this back within a second or two:

kubectl -n app-$APP scale deployment/$APP --replicas=3
kubectl -n app-$APP get deployment/$APP -w

Argo CD is faster than one scrape interval, so the Replicas panel usually never shows the 3 at all: the cluster was only briefly wrong.

From Git. In your service's repository in Gitea:

  1. open deploy/values.yaml
  2. change replicas: 1 to replicas: 3 with the edit button
  3. commit to main

Nothing pushes this one back. Argo CD polls Git every three minutes and a change can miss one tick, so give it up to five — or press Refresh on the app-<name> Application in Argo CD to skip the wait. Argo CD then shows three pods under the Deployment, and the Replicas panel in Grafana climbs to 3.

Argo CD showing the Deployment with three running pods

flowchart TD
    S["Deployment<br/>1 replica"]
    S -->|"kubectl scale --replicas=3"| X["3 replicas,<br/>for a second or two"]
    X -->|"Argo CD: Git still says 1"| S
    S -->|"commit replicas: 3<br/>to deploy/values.yaml"| Y["Argo CD syncs<br/>Application shows 3/3 Healthy"]
    Y --> Z["Deployment<br/>3 replicas"]

No image is built for that one. The workflow ignores deploy/, because what lives there is read at runtime rather than baked into the image:

What you change Image rebuilt What you see
frontend/src/App.tsx yes New SHA tag, Argo CD replaces the pod
deploy/values.yaml no Argo CD applies the value on the next sync
kubectl scale — Undone; Git never said 3

9. Clean up

If you imported the local CA, remove it from the trust store first. Then delete the entire disposable cluster:

make explore-down

Want the details?

Continue to How the kind environment works for the component map, per-application build path, Gateway API and certificate design, optional Kyverno/storage/CNI exercises, limitations, and troubleshooting.

For the hardware side, the bare-metal bootstrap guide is the reference described above; Ansible and Makefile automation is planned.