TechDocs, Plugins, and Scorecards

1. 1

   Add docs to a service

   backstage.io/techdocs-ref: dir:. in catalog-info.yaml (already set in Mission 1.1) points TechDocs at this mkdocs.yml.

   site_name: checkout-api
   nav:
     - Overview: index.md
     - Runbook: runbook.md
     - Architecture decisions: adr/
   plugins: [techdocs-core]

2. 2

   Kubernetes and Argo CD on the entity page

   Install the plugins, configure cluster access (a read-only ServiceAccount per cluster, or IRSA for EKS), and add the tabs to the service page layout.

   import { EntityKubernetesContent } from '@backstage/plugin-kubernetes';
   import { EntityArgoCDOverviewCard, isArgocdAvailable } from '@roadiehq/backstage-plugin-argo-cd';
   
   // in serviceEntityPage:
   <EntityLayout.Route path="/kubernetes" title="Kubernetes">
     <EntityKubernetesContent refreshIntervalMs={30000} />
   </EntityLayout.Route>
   <EntityLayout.Route path="/deployments" title="Deployments" if={isArgocdAvailable}>
     <EntityArgoCDOverviewCard />
   </EntityLayout.Route>

3. 3

   Production configuration

   Real auth (GitHub or OIDC SSO, never the guest provider), PostgreSQL for the catalog and scaffolder, TechDocs from S3, and secrets from environment variables populated by External Secrets (GitOps course, Mission 2.1).

   app: { baseUrl: https://portal.shoplite.dev }
   backend:
     baseUrl: https://portal.shoplite.dev
     database:
       client: pg
       connection:
         host: ${POSTGRES_HOST}
         user: ${POSTGRES_USER}
         password: ${POSTGRES_PASSWORD}
   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
           signIn: { resolvers: [{ resolver: usernameMatchingUserEntityName }] }
   techdocs:
     builder: external
     publisher:
       type: awsS3
       awsS3: { bucketName: shoplite-techdocs, region: ap-south-1 }
   kubernetes:
     serviceLocatorMethod: { type: multiTenant }
     clusterLocatorMethods:
       - type: config
         clusters:
           - { name: prod-mumbai, url: https://ABC.gr7.ap-south-1.eks.amazonaws.com, authProvider: aws }

4. 4

   Build and deploy Backstage with the golden path

   The portal is itself a service: a container image built in CI and deployed with the same GitOps flow as everything else, which is good dogfooding. yarn build:backend plus the provided Dockerfile produces the image.

   terminalcopy cmd

   $ yarn install --immutable && yarn tsc && yarn build:backend

   docker build . -f packages/backend/Dockerfile -t 123456789012.dkr.ecr.ap-south-1.amazonaws.com/backstage:$(git rev-parse --short HEAD)

   argocd app get backstage-prod-mumbai | grep -E 'Sync|Health'

   ── expected output ──

   Sync Status: Synced to main (5e6f7a8)

   Health Status: Healthy

5. 5

   Define production-readiness checks

   Start with a short list everyone agrees on, and show it per service. This YAML describes the checks; with Tech Insights, each check is a fact retriever plus a rule (for example 'catalog-info has a runbook link', 'repo has CODEOWNERS', 'no critical CVEs in the latest image scan').

   scorecard: production-readiness
   checks:
     - { id: has-owner, description: Owned by an existing team }
     - { id: has-runbook, description: Runbook link in catalog-info }
     - { id: has-slo, description: SLO defined in Sloth/Pyrra config }
     - { id: pdb-and-probes, description: PDB and probes present (from Kyverno PolicyReport) }
     - { id: current-ci, description: Uses platform-workflows java-service.yml@v4 or newer }
     - { id: no-critical-cves, description: No critical CVEs in the deployed image }
   levels: { bronze: 3, silver: 5, gold: 6 }

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.