How wnqueiroz/platform-engineering-backstack works
1. Overall shape
This repo is a multi-component platform engineering lab centered on a single local Kubernetes cluster named platform (created with kind). The cluster hosts the platform services, while the repo provides GitOps manifests, Crossplane definitions, Backstage configuration, and bootstrap scripts to bring everything up.
2. Primary control-plane flow
The operational entrypoint is the root Makefile plus the .bootstrap/**/up.sh scripts. Those scripts install or apply the initial platform components into the cluster. After that, Argo CD becomes the main reconciler: it watches the argocd/ tree and syncs the platform apps from Git into Kubernetes.
3. Argo CD as application orchestrator
The argocd/ directory is organized as an app-of-apps style setup. It defines Argo CD applications for:
- backstage
- crossplane
- crossview
- kyverno
- localstack
This makes Argo CD the boundary between Git-defined desired state and the live cluster.
4. Crossplane as infrastructure control plane
The crossplane/ folder contains the declarative infrastructure model:
- xrds/xqueue.yaml defines the platform abstraction.
- compositions/aws/xqueue.yaml binds that abstraction to concrete resources.
- providers/ and providers-config/ define the resource providers and their credentials/config.
- claims/ contains example user-facing requests for infrastructure.
In practice, developers create a claim, Crossplane turns it into composed resources, and those resources are reconciled against either AWS or the local emulator.
5. LocalStack as the external cloud boundary
LocalStack is deployed inside the cluster to emulate AWS services locally. The Crossplane AWS provider is wired to LocalStack through provider config, letting the platform simulate cloud provisioning without a real AWS account. This is a key architectural substitute for external cloud infrastructure.
6. Backstage as the developer portal
The backstage/ tree is a full Backstage app split into frontend and backend packages. It provides the developer-facing entrypoint for the platform:
- catalog definitions live under backstage/catalog/
- template scaffolding lives under backstage/catalog/templates/
- the backend includes a custom crossplane-entity-provider.ts
This means Backstage is not just documentation/search; it also acts as a discovery surface for Crossplane-managed platform entities.
7. Backstage-to-Crossplane integration
The Backstage catalog includes an xqueue-claim template that generates claim YAML, which is the user-facing abstraction for requesting infrastructure. That creates a workflow where a developer uses Backstage to instantiate a Crossplane claim, and Crossplane handles the provisioning lifecycle in the cluster.
8. Crossview as observability for the control plane
crossview/ deploys a separate UI for inspecting Crossplane resources. Its manifests include a namespace, Postgres, RBAC, config, secrets, service, and deployment, indicating it has its own application state and permissions. Architecturally, Crossview is the diagnostic/visualization layer for understanding XRDs, compositions, claims, and their relationships.
9. Kyverno as policy enforcement
kyverno/validate-xqueue-fields.yaml contains cluster policy for validating platform resource fields. This is the admission/policy boundary: it constrains what claims or resources are considered valid before they are accepted by the cluster. The GitHub workflow validate-claims.yaml suggests these rules are also checked in CI.
10. Bootstrap layer vs steady-state GitOps
The .bootstrap/ manifests represent the initial installation path for each subsystem, including Argo CD, Backstage, Crossplane, Crossview, Kyverno, and LocalStack. The repository’s roadmap explicitly aims to shift more of this setup into Argo CD, so the long-term model is for GitOps to manage not only apps and claims, but also more of the cluster bootstrap itself.
11. Runtime and infrastructure assumptions
The stack relies on Kubernetes tooling (kind, kubectl, helm) and a local Docker-based environment. The repo also requires a GitHub personal access token for Backstage-related repo access and PR workflows. These are not product features, but they materially shape how the platform is bootstrapped and operated.
12. Main data/control flows to diagram
The most important flows to capture are:
- Git repo → Argo CD → Kubernetes apps
- Backstage user action → generated claim YAML → Crossplane reconciliation
- Crossplane claim → composed resources → LocalStack/AWS provider
- Kyverno policy → admission control for platform resources
- Crossview → reads cluster/Crossplane state for visualization
13. Notable boundary between concerns
The repository cleanly separates:
- developer experience: Backstage
- delivery/sync: Argo CD
- infrastructure provisioning: Crossplane
- policy: Kyverno
- cloud emulation: LocalStack
- operational visibility: Crossview
That separation is the core architecture of the repo and is the key to drawing an accurate system diagram.
Main entry points: Makefile Makefile · apps.yaml App of apps · app.yaml Crossplane app · cncf-campinas-talk.yaml Claims
Components 25
Bootstrap
One-time cluster bring-up scripts and manifests.
- Makefile · Top-level operational entrypoint for the repo.
Makefile - Argo CD up · Initial installs for Argo CD into the local cluster.
.bootstrap/argocd/up.sh - Backstage up · Bootstraps the Backstage deployment and config.
.bootstrap/backstage/up.sh - Crossplane up · Bootstraps Crossplane credentials and install state.
.bootstrap/crossplane/up.sh - Crossview up · Bootstraps Crossview namespace, database, and app.
.bootstrap/crossview/up.sh - Kyverno up · Bootstraps Kyverno policy enforcement.
.bootstrap/kyverno/up.sh - LocalStack up · Bootstraps the AWS emulator into the cluster.
.bootstrap/localstack/up.sh
GitOps
Argo CD root and application definitions.
- App of apps · Argo CD root application that fans out platform apps.
argocd/apps.yaml - Backstage app · Argo CD application for Backstage.
argocd/apps/backstage/app.yaml - Crossplane app · Argo CD application for Crossplane.
argocd/apps/crossplane/app.yaml - Crossview app · Argo CD application for Crossview.
argocd/apps/crossview/app.yaml - Kyverno app · Argo CD application for Kyverno.
argocd/apps/kyverno/app.yaml - LocalStack app · Argo CD application for LocalStack.
argocd/apps/localstack/app.yaml
Developer portal
Backstage app, catalog, and scaffolding flow.
- Backstage · Developer portal UI and backend for catalog and templates.
backstage/packages/app/src/App.tsx - Catalog · Catalog entities and aggregated sources.
backstage/catalog/all.yaml - Xqueue template · Template that generates Crossplane claim YAML.
backstage/catalog/templates/xqueue-claim/template.yaml - Entity provider · Custom provider that surfaces Crossplane entities to Backstage.
backstage/packages/backend/src/crossplane-entity-provider.ts
Infrastructure control
Crossplane abstractions, compositions, providers, and claims.
- XQueue XRD · Platform abstraction for queue-like infrastructure.
crossplane/xrds/xqueue.yaml - AWS composition · Maps the XQueue abstraction to concrete resources.
crossplane/compositions/aws/xqueue.yaml - Claims · Example user-facing infrastructure requests.
crossplane/claims/cncf-campinas-talk.yaml - Providers · AWS and Kubernetes providers used by Crossplane.
crossplane/providers/aws/sqs.yaml - Provider config · Provider configuration for local and cluster-backed endpoints.
crossplane/providers-config/localstack-provider-config.yaml
Policy
Admission and validation for platform resources.
- Xqueue policy · Validation policy for xqueue fields.
kyverno/validate-xqueue-fields.yaml
Visibility
Crossplane inspection and diagnostic UI.
- Crossview · Separate UI for viewing Crossplane resources and relationships.
.bootstrap/crossview/manifests/deployment.yaml
Runtime boundary
Local cloud emulation and target services.
- LocalStack · Local cloud boundary that emulates AWS services.
.bootstrap/localstack/manifests/deployment.yaml
Connections 33
- Makefile → Argo CD up: boots · Runs cluster bootstrap for Argo CD.
- Makefile → Backstage up: boots · Runs cluster bootstrap for Backstage.
- Makefile → Crossplane up: boots · Runs cluster bootstrap for Crossplane.
- Makefile → Crossview up: boots · Runs cluster bootstrap for Crossview.
- Makefile → Kyverno up: boots · Runs cluster bootstrap for Kyverno.
- Makefile → LocalStack up: boots · Runs cluster bootstrap for LocalStack.
- Argo CD up → App of apps: installs · Seeds the GitOps root application.
- App of apps → Backstage app: syncs · Argo CD fans out the Backstage app.
- App of apps → Crossplane app: syncs · Argo CD fans out the Crossplane app.
- App of apps → Crossview app: syncs · Argo CD fans out the Crossview app.
- App of apps → Kyverno app: syncs · Argo CD fans out the Kyverno app.
- App of apps → LocalStack app: syncs · Argo CD fans out the LocalStack app.
- Backstage app → Backstage: deploys · Deploys the developer portal.
- Crossplane app → XQueue XRD: applies · Delivers Crossplane platform definitions.
- Crossplane app → AWS composition: applies · Delivers compositions.
- Crossplane app → Providers: applies · Delivers provider packages.
- Crossplane app → Provider config: applies · Delivers provider configuration.
- Crossplane app → Claims: applies · Delivers sample claims.
- Crossview app → Crossview: deploys · Deploys the inspection UI.
- Kyverno app → Xqueue policy: applies · Installs admission policy.
- LocalStack app → LocalStack: deploys · Deploys the AWS emulator.
- Backstage → Catalog: loads · Backstage reads catalog sources.
- Backstage → Xqueue template: scaffolds · Users generate claims from the template.
- Backstage → Entity provider: extends · Backend surfaces Crossplane entities.
- Xqueue template → Claims: generates · Template outputs claim manifests.
- Claims → XQueue XRD: matches · Claims target the XQueue abstraction.
- XQueue XRD → AWS composition: binds · XRD is implemented by the composition.
- AWS composition → Providers: uses · Composition drives provider resources.
- Provider config → LocalStack: targets · Provider config points AWS provider at LocalStack.
- Providers → LocalStack: provisions · Provider manages emulated AWS services.
- Xqueue policy → Claims: validates · Policy constrains accepted queue claims.
- Crossview → XQueue XRD: inspects · Crossview visualizes the Crossplane model.
- Crossview → Claims: inspects · Crossview visualizes claims and status.