Platform Engineering

Build internal developer platforms with Backstage and Port for streamlined developer workflows.

Quick Start

# app-config.yaml — Backstage configuration
app:
  title: Internal Developer Platform
  baseUrl: https://developer.example.com

backend:
  baseUrl: https://developer.example.com
  listen:
    port: 7007

organization:
  name: My Company

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

techdocs:
  builder: 'local'
  generators:
    techdocs: 'docker'

catalog:
  rules:
    - allow: [Component, API, Resource, System, Domain]
  locations:
    - type: url
      target: https://github.com/org/service-catalog/blob/main/catalog-info.yaml
      rules:
        - allow: [Component, API]

# catalog-info.yaml — Service entity definition
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Payment processing service
  annotations:
    github.com/project-slug: org/payment-service
    backstage.io/techdocs-ref: dir:.
    jenkins.io/github-folder: org/payment-service
spec:
  type: service
  lifecycle: production
  owner: platform-team
  system: payment-platform
  dependsOn:
    - resource:default/postgres-main
    - api:default/payment-api
  providesApis:
    - payment-api
  consumedApis:
    - fraud-detection-api

Key Concepts

Platform engineering treats the developer platform as a product. Backstage/Port provide service catalogs, software templates, tech docs, and scorecards. Golden paths reduce cognitive load on developers.

When to Use

• Organizations with 10+ microservices needing standardized management
• Teams spending too much time on infrastructure configuration
• Standardizing deployment workflows and environments
• Improving developer experience and reducing onboarding time

Step-by-Step

1. Bootstrap a developer portal: scaffold Backstage (`npx @backstage/create-app`) or create a Port blueprint with service metadata fields.

2. Model the golden path: define service templates for standard components (API, service, worker) using software templates / Port self-service actions.

3. Register the catalog: commit `catalog-info.yaml` for each service with owner, system, dependencies, and API boundaries.

4. Wire CI/CD: connect the SCM integration, add repository-backend events so new repos auto-register.

5. Publish docs: enable TechDocs from repo markdown with cookstyle/plugins to render living documentation.

6. Add governance: create scorecards with maturity checks (SLO covered, dependency updates, cost tags) and report in the portal.

Examples

# catalog-info.yaml — full entity with relations
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: payment-platform
  description: Core payments system
spec:
  owner: platform-team
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  annotations:
    github.com/project-slug: org/payment-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: platform-team
  system: payment-platform
  dependsOn:
    - resource:default/postgres-main
  providesApis: [payment-api]
  consumedApis: [fraud-detection-api]

# Add the entity to catalog locations, then push to trigger sync
kubectl port-forward svc/backstage-backend 7007:7007
curl http://localhost:7007/api/catalog/entities?filter=kind=component

Best Practices

• Define golden paths with self-service templates and guardrails.
• Use Backstage or Port for a developer portal and catalog.
• Standardize CI/CD, environments, and secrets across teams.
• Measure adoption and feedback; iterate on the platform.
• Automate provisioning with IaC and approval workflows.
• Keep platform teams accountable via SLOs for golden paths.

Troubleshooting

• Low adoption: reduce friction and document the golden path.
• Drift: enforce policies and templates in CI.
• Access issues: audit RBAC and portal roles.
• Slow onboarding: automate scaffolding end to end.

Validation

1. Backstage/Port starts and renders the service catalog

2. Software templates create repositories with correct scaffolding

3. TechDocs renders documentation from code repositories

4. Scorecards track service maturity metrics