I built a local environment for trying an Internal Developer Platform (IDP) with Backstage, Argo CD, Keycloak and Grafana. It requires a machine that can allocate at least 8 GiB of memory to Docker.

It's for people who want hands-on experience with a golden path: a standard workflow connecting service creation, deployment and operations, and the technologies behind it. No pre-existing Kubernetes cluster, cloud account or GitHub token is required.

With the prerequisite CLI tools installed, these commands bring it up. The walkthrough lists the tools and environment requirements. My local testing has been on Apple Silicon (ARM64). For changes covered by the platform workflow, CI also starts the environment on Linux x86-64 and checks authentication, service creation and deployment.

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

I run a Kubernetes homelab on three Raspberry Pi 5s and an x86 mini PC, and publish its configuration as kensan-lab. It's a reference implementation for practicing platform engineering at home, including enterprise-grade security and governance. Backstage, Argo CD and Keycloak connect application creation to delivery and operations.

It's also a place to put the technologies covered by Golden Kubestronaut into practice. Knowledge from separate certifications—Kubernetes, GitOps, networking, security and observability—comes together in one running system. I practiced on this homelab while earning Golden Kubestronaut myself.

Bootstrapping the physical homelab takes machines, networking and a somewhat involved setup. Its bootstrap scripts still need work, and getting started takes time and effort. To make the technologies easier to try, I added a kind environment with a startup command and a walkthrough to follow.

Architecture: connecting a service end to end

The kind environment: delivery, gateway authentication and observability

Everything runs in one kind cluster. kind runs Kubernetes nodes as Docker containers.

For delivery, Backstage runs the service creation template. Gitea hosts the generated repositories and CI, while a separate in-cluster registry stores container images. Argo CD reads deployment definitions from Git and reconciles Kubernetes with that desired state.

For access, browser requests enter through an Istio Gateway. oauth2-proxy connects the gateway's authentication check to Keycloak, the shared identity provider. Prometheus collects metrics, and Grafana displays them.

The environment reuses the homelab's application chart, values and policies. The physical homelab also includes monitoring from an external cloud environment, secure internet connectivity and strict NetworkPolicies. Its configuration is available in the same repository for anyone interested in going further.

What the walkthrough covers

Install Docker, kind, kubectl, helm, curl and make, then run make try. The initial image build can take several minutes. The walkthrough covers setup and exact commands. Here's what the experience looks like, switching between application developer and platform administrator.

1. Explore a GitOps-managed cluster

Sign in to Argo CD through Keycloak. The explore-root Application has created the Applications for the individual components. The portal, authentication and monitoring systems are managed through this GitOps structure.

Argo CD showing explore-root and its child Applications

2. Open the protected demo app

Open the existing demo application. Keycloak reuses the session, so there's no second password prompt. The app displays identity headers attached by the gateway, showing that the signed-in user's information reaches the application.

The demo application displaying identity headers after sign-in

3. Create a service in Backstage

Choose the Software Template, enter an application name and the other settings, and press Create. A service repository is created in Gitea, and CI runs tests and builds the image. Once the build succeeds, Backstage opens a PR to add the service to the platform configuration.

The service creation form in Backstage

4. Merge the automatically created PR

Switch to the platform administrator role and sign in to Gitea. Gitea does not share the Keycloak session, so it requires a separate login with the demo credentials, demo / demo.

Open the platform configuration PR that Backstage created in the previous step, review it and merge it. Argo CD detects the change and deploys the service. Because it polls Git, this can take about four minutes after the merge. The new app is available at a URL already protected by gateway authentication.

The automatically created platform configuration PR in Gitea

5. Generate load and observe it in Grafana

Press the app's load-generation button and inspect CPU usage, request rate and latency in Grafana. An action in the service produces a change in its metrics, making the monitoring setup something concrete to explore.

Grafana displaying application metrics during load generation

6. Compare a manual change with a Git change

First, change the replica count with kubectl scale. Argo CD restores the state declared in Git. Then change the replica count in the service's deploy/values.yaml and commit it to Git. That change is applied and retained as the desired state. The same scaling operation has a different outcome depending on where the change is made.

Run make explore-down to remove the environment when finished.

The following four design choices support this workflow.

Gitea keeps the delivery workflow local

The golden path saves generated code to Git, builds it in CI and deploys it through Argo CD. It needs a Git server where the workflow can create repositories and pull requests.

Using GitHub would require authentication and permissions for automated repository creation and writes, whether those repositories were public or private. I wanted to avoid making visitors prepare tokens or place generated code on an external service just to try the platform, so I included Gitea inside the kind cluster.

Backstage creates service repositories and platform configuration PRs there, and Argo CD reads deployment definitions from the same Gitea instance. Gitea Actions runs CI, and built images go to the in-cluster registry. Service creation and deployment can therefore complete without configuring access to an external Git service.

Software Templates connect service creation to operations

Generated service files and the division of responsibility around the shared chart

Backstage's Software Templates create a service with CI, deployment configuration, catalog metadata and documentation from a form. I wanted people to experience Backstage with these pieces connected.

After the template creates the service repository, CI runs tests, builds and publishes a container image, and records the image tag derived from the source commit SHA in deploy/values.yaml. Backstage waits for those steps to succeed before opening the platform configuration PR that introduces the service to Argo CD. That gives the platform administrator a review point with a built image already available.

Documentation grows alongside the service. The template includes docs/index.md for the content, mkdocs.yml for the MkDocs configuration, and catalog-info.yaml for registration in Backstage. The annotation backstage.io/techdocs-ref: dir:. connects the catalog entry to documentation in the same repository.

TechDocs turns that Markdown into a site using MkDocs and makes it accessible from the service's page in Backstage. Code changes and documentation updates can share Git history and PRs, while readers find documentation alongside ownership and API information. This environment configures local generation and publishing in Backstage, and the template supplies the required files.

The deployment responsibilities are also divided explicitly. The platform owns charts/app-base, a common Helm chart defining Kubernetes conventions. Each service owns its deploy/values.yaml, specifying its image, resources, replicas and other settings. The platform maintains the shared chart while application developers configure their service and focus on its implementation.

The gateway handles application authentication

The app implements no login flow of its own. An Istio AuthorizationPolicy on the gateway protects application hostnames by default and delegates authentication checks to oauth2-proxy through ext_authz. An unauthenticated browser goes through Keycloak login; authenticated requests carry identity headers to the application. The app can display that information without implementing OIDC.

The shared chart's gatewayOAuth2 setting adds an HTTPRoute for /oauth2 on each application's hostname. This sends login and callback requests to oauth2-proxy. The policy requiring authentication is managed separately at the gateway.

auth: gatewayOAuth2: enabled: true 

A new app's name is only known when it's created, so its hostname cannot be individually listed in advance. I configured the gateway to protect application hostnames by default, with exclusions for tools that handle their own login. A custom Backstage action registers the generated app's redirect URI with Keycloak, connecting service creation to the authentication system.

The platform tools also use Keycloak. Backstage, Argo CD and Grafana each have their own OIDC integration with the same provider. Authentication happens at different layers, but the shared Keycloak session means moving between these tools doesn't require entering the password again.

Another detail is keeping the OIDC issuer URL consistent even though the browser and pods see different networks. For the browser, sslip.io resolves the hostname to loopback; for pods, a CoreDNS rewrite routes it to the gateway. cert-manager issues the TLS certificates. The browser warns until the local CA is trusted, and startup leaves the host's trust store untouched.

Observability comes with the service

The generated FastAPI service includes HTTP metrics instrumentation and a /metrics endpoint. The accompanying ServiceMonitor connects it to Prometheus scraping, making request counts and latency available for monitoring. Grafana displays these alongside CPU usage collected through the cluster's monitoring infrastructure.

Deployment is the beginning of operating a service, so I wanted the golden path to include a way to inspect its behavior. The walkthrough links to the dashboard. Creating another app also creates its connection to monitoring.

Try the whole workflow

The kind environment focuses on trying service creation, deployment, authentication and observability on a laptop. It does not include the homelab’s Cilium, Vault or Longhorn components. For the definitions the environments share, CI checks chart-version drift.

The repository and walkthrough have the full details. Issues and feedback from trying it are welcome.

I used AI tools to help edit and translate this article.