Capstone Part 4: Backstage Self-Service Portal

npx @backstage/create-app@latest --path platform-portal
cd platform-portal
yarn install

# run it locally first — frontend on :3000, backend on :7007
yarn dev

# platform-portal/app-config.yaml
app:
  baseUrl: http://backstage.platform.svc.cluster.local:7007
backend:
  baseUrl: http://backstage.platform.svc.cluster.local:7007
  listen: { port: 7007 }
  database:
    client: better-sqlite3            # fine for this throwaway lab cluster;
    connection: ':memory:'            # a real deployment needs Postgres — see backstage.html

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}          # a scoped PAT is fine for a lab; a GitHub App for anything real

techdocs:
  builder: 'local'                    # fine for this lab; use 'external' + object storage in production
  generator: { runIn: 'docker' }
  publisher: { type: 'local' }

catalog:
  rules:
    - allow: [Component, API, Resource, System, Domain, Group, User, Location, Template]
  locations:
    - type: url
      target: https://github.com/YOU/platform-capstone/blob/main/catalog/ledger/catalog-info.yaml
    - type: url
      target: https://github.com/YOU/platform-capstone/blob/main/catalog/templates/golden-path-service/template.yaml
      rules: [ { allow: [Template] } ]

kubernetes:
  serviceLocatorMethod: { type: 'multiTenant' }
  clusterLocatorMethods:
    - type: 'config'
      clusters:
        - name: platform-dev
          url: https://kubernetes.default.svc
          authProvider: 'serviceAccount'

yarn build:all
yarn build:backend --config app-config.yaml
docker image build . -f packages/backend/Dockerfile --tag platform-portal:1

kind load docker-image platform-portal:1 --name platform-dev

# platform-addons/backstage/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
  namespace: platform
  labels: { app: backstage }
spec:
  replicas: 1
  selector: { matchLabels: { app: backstage } }
  template:
    metadata: { labels: { app: backstage } }
    spec:
      containers:
        - name: backstage
          image: platform-portal:1
          imagePullPolicy: IfNotPresent   # image was kind-loaded, not pulled from a registry
          ports:
            - containerPort: 7007
          env:
            - name: GITHUB_TOKEN
              valueFrom:
                secretKeyRef: { name: backstage-github-token, key: token }
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits: { cpu: 500m, memory: 512Mi }
---
# platform-addons/backstage/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: backstage
  namespace: platform
spec:
  selector: { app: backstage }
  ports:
    - port: 7007
      targetPort: 7007

# apps/backstage.yaml — one more child of the Part 1 App-of-Apps root
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: backstage
  namespace: platform
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/YOU/platform-capstone.git
    targetRevision: main
    path: platform-addons/backstage
  destination:
    server: https://kubernetes.default.svc
    namespace: platform
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions: [ CreateNamespace=true ]

kubectl -n platform create secret generic backstage-github-token \
  --from-literal=token=$GITHUB_TOKEN

git add platform-addons/backstage apps/backstage.yaml
git commit -m "add Backstage to the platform"
git push

kubectl -n platform get applications backstage -w
# NAME        SYNC STATUS   HEALTH STATUS
# backstage   Synced        Healthy

kubectl -n platform port-forward svc/backstage 7007:7007
# open http://localhost:7007

# platform-capstone/catalog/ledger/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ledger
  title: Ledger Service
  description: Small payments/ledger-style service — the capstone's one running workload.
  tags: [payments, capstone]
  annotations:
    backstage.io/techdocs-ref: dir:.
    backstage.io/kubernetes-id: ledger              # matches the app=ledger label on its pods
    argocd/app-name: ledger                         # lights up the Argo CD tab — Part 1's Application
    github.com/project-slug: YOU/platform-capstone
  links:
    - url: https://github.com/YOU/platform-capstone/tree/main/ledger
      title: Manifests
      icon: github
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
  system: capstone
  dependsOn:
    - resource:default/ledger-db
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: ledger-db
  description: >-
    A LedgerDatabase custom resource (Part 3) — reconciled by the ledger-db-operator
    into a Postgres StatefulSet, headless Service and credentials Secret in the ledger namespace.
spec:
  type: database
  owner: group:default/platform-team
  system: capstone
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: platform-team
spec:
  type: team
  children: []
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: capstone
  description: Everything built across the six capstone parts.
spec:
  owner: group:default/platform-team

git add catalog/ledger/catalog-info.yaml
git commit -m "register ledger in the Software Catalog"
git push

curl -s -X POST http://localhost:7007/api/catalog/locations \
  -H 'Content-Type: application/json' \
  -d '{"type":"url","target":"https://github.com/YOU/platform-capstone/blob/main/catalog/ledger/catalog-info.yaml"}'

curl -s "http://localhost:7007/api/catalog/entities/by-name/component/default/ledger" | jq '.metadata.name, .spec.owner'

platform-capstone/
├── apps/
├── ledger/
├── catalog/
│   └── ledger/
│       ├── catalog-info.yaml
│       ├── mkdocs.yml
│       └── docs/
│           ├── index.md
│           └── runbook.md

# catalog/ledger/mkdocs.yml
site_name: 'Ledger Service'
nav:
  - Home: index.md
  - Runbook: runbook.md
plugins:
  - techdocs-core

# catalog/ledger/docs/runbook.md — the first real page a future on-call reads
# Ledger runbook

Ledger is a small payments/ledger-style service. It ships through Argo CD from
`ledger/` in this repo, via an Argo Rollouts canary (10% -> 50% -> 100%, see Part 2).

## If it's Degraded
1. `kubectl -n ledger get pods` — look for CrashLoopBackOff or ImagePullBackOff.
2. `kubectl -n ledger describe pod <pod>` for the real event.
3. `argocd app get ledger` — confirm Synced vs Healthy are not the same thing.

## Rollback
`argocd app rollback ledger <revision>` — then fix Git, or selfHeal reverts you again.

platform-capstone/catalog/templates/golden-path-service/
├── template.yaml
└── skeleton/
    ├── Dockerfile
    ├── ci-pipeline.yaml            # Tekton Pipeline + PipelineRun, Kaniko build
    ├── catalog-info.yaml           # ${{ values.* }} placeholders
    └── gitops/
        ├── application.yaml        # -> becomes apps/<name>.yaml in platform-capstone
        ├── namespace.yaml
        ├── rollout.yaml             # Argo Rollouts canary, same shape as ledger's
        ├── ledger-database.yaml     # a LedgerDatabase claim — Part 3's CRD, one click
        ├── service.yaml
        └── kustomization.yaml

# catalog/templates/golden-path-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: golden-path-service
  title: New Service (Golden Path)
  description: A repo, a Tekton+Kaniko pipeline, an Argo Rollouts canary, and a LedgerDatabase — wired into platform-capstone automatically.
  tags: [recommended, capstone]
spec:
  owner: group:default/platform-team
  type: service

  parameters:                                   # ── the form Dot fills in ──
    - title: Service details
      required: [name, owner]
      properties:
        name:
          title: Service name
          type: string
          pattern: '^[a-z][a-z0-9-]{2,29}$'
        owner:
          title: Owning team
          type: string
          ui:field: OwnerPicker
          ui:options: { catalogFilter: { kind: Group } }
        replicas:
          title: Starting replica count
          type: integer
          default: 2
          enum: [1, 2, 3]
        storageGB:
          title: Database size (GB)
          type: integer
          default: 5
          minimum: 1                    # matches LedgerDatabaseSpec's own +kubebuilder:validation range
          maximum: 100                   # the CRD's admission validation would reject anything outside this anyway

  steps:                                        # ── what runs on submit ──
    - id: fetch-service
      name: Render the service skeleton
      action: fetch:template
      input:
        url: ./skeleton
        targetPath: ./service
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          replicas: ${{ parameters.replicas }}

    - id: publish-service
      name: Create the service's own repo
      action: publish:github
      input:
        repoUrl: github.com?owner=YOU&repo=${{ parameters.name }}
        sourcePath: ./service
        defaultBranch: main
        repoVisibility: internal

    - id: fetch-gitops-pr
      name: Render the platform-capstone additions
      action: fetch:template
      input:
        url: ./skeleton/gitops
        targetPath: ./gitops-pr
        values:
          name: ${{ parameters.name }}
          replicas: ${{ parameters.replicas }}
          storageGB: ${{ parameters.storageGB }}
          serviceRepoUrl: ${{ steps.publish-service.output.remoteUrl }}

    - id: pr-gitops
      name: Open a PR against platform-capstone
      action: publish:github:pull-request
      input:
        repoUrl: github.com?owner=YOU&repo=platform-capstone
        branchName: add-${{ parameters.name }}
        title: "Add ${{ parameters.name }} to the golden path"
        description: Scaffolded by Backstage — adds apps/${{ parameters.name }}.yaml and ${{ parameters.name }}/
        sourcePath: ./gitops-pr

    - id: register
      name: Register the new service in the catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish-service.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: Service repository
        url: ${{ steps.publish-service.output.remoteUrl }}
      - title: platform-capstone pull request
        url: ${{ steps.pr-gitops.output.remoteUrl }}
      - title: Open in catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}

# skeleton/ci-pipeline.yaml — Tekton, mirroring Part 2's build for ledger
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: ${{ values.name }}-build
spec:
  params:
    - name: image-tag
  workspaces:
    - name: source
  tasks:
    - name: build-and-push
      taskRef: { name: kaniko }
      workspaces: [ { name: source, workspace: source } ]
      params:
        - name: IMAGE
          value: registry.local/${{ values.name }}:$(params.image-tag)
---
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: ${{ values.name }}-build-run
spec:
  pipelineRef: { name: "${{ values.name }}-build" }
  params: [ { name: image-tag, value: "0.1.0" } ]
  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteOnce]
          resources: { requests: { storage: 1Gi } }

# skeleton/gitops/rollout.yaml — same 10% -> 50% -> 100% canary shape as ledger's, Part 2
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: ${{ values.name }}
  namespace: ${{ values.name }}
spec:
  replicas: ${{ values.replicas }}
  selector: { matchLabels: { app: "${{ values.name }}" } }
  template:
    metadata: { labels: { app: "${{ values.name }}" } }
    spec:
      containers:
        - name: ${{ values.name }}
          image: registry.local/${{ values.name }}:0.1.0
          ports: [ { containerPort: 8080 } ]
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: { duration: 60 }
        - setWeight: 50
        - pause: { duration: 60 }
        - setWeight: 100
---
# skeleton/gitops/ledger-database.yaml — Part 3's CRD, requested with a form instead of eight hand-written lines
apiVersion: platform.acme.io/v1alpha1
kind: LedgerDatabase
metadata:
  name: ${{ values.name }}-db
  namespace: ${{ values.name }}
spec:
  engine: postgres
  storageGB: ${{ values.storageGB }}
  highAvailability: false
---
# skeleton/gitops/application.yaml -> committed as apps/${{ values.name }}.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ${{ values.name }}
  namespace: platform
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/YOU/platform-capstone.git
    targetRevision: main
    path: ${{ values.name }}
  destination:
    server: https://kubernetes.default.svc
    namespace: ${{ values.name }}
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions: [ CreateNamespace=true ]

curl -s "http://localhost:7007/api/catalog/entities/by-name/template/default/golden-path-service" \
  | jq '.metadata.name'

curl -s -X POST http://localhost:7007/api/scaffolder/v2/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "templateRef": "template:default/golden-path-service",
    "values": { "name": "invoices", "owner": "group:default/platform-team", "replicas": 2, "storageGB": 5 }
  }' | jq '.id'

# watch it run
curl -s "http://localhost:7007/api/scaffolder/v2/tasks/<task-id>/eventstream"

gh pr merge add-invoices --repo YOU/platform-capstone --merge

kubectl -n platform get applications invoices -w
# NAME       SYNC STATUS   HEALTH STATUS
# invoices   Synced        Healthy

kubectl -n invoices get rollout,svc,ldb
# rollout.argoproj.io/invoices        healthy
# service/invoices                    ClusterIP
# ledgerdatabase.platform.acme.io/invoices-db   postgres   5   Running   True