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:
Install Docker Engine and the kind, kubectl, and Helm CLIs.
Then clone and start the environment:
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:
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.
The same state is available from the terminal:
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.
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 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:
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.
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:
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 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:
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:
- open
deploy/values.yaml - change
replicas: 1toreplicas: 3with the edit button - 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.
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:
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.





