backstage-deployment

Backstage Deployment Skill

Deploys the upstream open-source Backstage developer portal on Azure AKS or locally via Docker Desktop.

Official Docs via MCP: Use backstagedocs_* tools from the mcp-ecosystem for live official documentation:

• backstagedocs_get_page slug=deployment/docker — Docker deployment guide
• backstagedocs_get_page slug=deployment/k8s — Kubernetes deployment guide
• backstagedocs_get_page slug=auth/github/provider — GitHub auth provider docs
• backstagedocs_get_page slug=auth/microsoft/provider — Microsoft auth provider docs
• backstagedocs_search query="app-config" — search configuration docs

Scope

Azure MVP Deployment (rg-<platform>-<env>)

Resources

Service Principal

Kubernetes Components

External URLs

1. Prerequisites

CLI Tools

# Required
az --version        # >= 2.55
terraform --version # >= 1.5
kubectl version     # >= 1.28
helm version        # >= 3.13
docker --version    # >= 24.0
node --version      # >= 20.0
yarn --version      # >= 4.0
gh auth status      # GitHub CLI authenticated

Azure

az login
az account set --subscription "<SUBSCRIPTION_ID>"
az provider register -n Microsoft.ContainerService
az provider register -n Microsoft.KeyVault
az provider register -n Microsoft.Storage

Configuration Files

2. Azure AKS Deployment

Terraform

cd terraform

# Initialize
terraform init -backend-config=environments/dev-backend.hcl

# Plan
terraform plan \
  -var-file=environments/dev.tfvars \
  -var="portal_name=<client-portal-name>" \
  -var="location=centralus"

# Apply
terraform apply \
  -var-file=environments/dev.tfvars \
  -var="portal_name=<client-portal-name>" \
  -var="location=centralus"

Module: terraform/modules/backstage/

Provisions:

• Helm release for backstage/backstage chart
• Custom image from ACR
• PostgreSQL Flexible Server integration
• GitHub App secret in Key Vault
• Ingress with TLS (cert-manager)

Region Validation

variable "location" {
  type    = string
  validation {
    condition     = contains(["centralus", "eastus"], var.location)
    error_message = "Only Central US and East US are supported."
  }
}

4. GitHub App Setup

For AUTH_PROVIDER=entra with GITHUB_IDENTITY_MODE=enterprise-managed-users, Entra ID handles user sign-in. GitHub App credentials are still required for technical GitHub integration: catalog sync, scaffolder writes, Actions, PRs, Codespaces, packages, and AI Impact metrics.

Create GitHub App

./scripts/setup-github-app.sh --target backstage --org <GITHUB_ORG>

Manual Creation

1. Go to https://github.com/organizations/<ORG>/settings/apps/new
2. Set:
   • Homepage URL: https://<portal-url>
   • Callback URL: https://<portal-url>/api/auth/github/handler/frame
   • Webhook: Disable (not needed for auth)
3. Permissions:
   • contents: read
   • metadata: read
   • pull_requests: write
   • members: read
4. Generate Private Key (.pem file)
5. Note: App ID, Client ID, Client Secret

Configure in Backstage

Environment variables:

GITHUB_APP_ID=<numeric-app-id>
GITHUB_APP_CLIENT_ID=<client-id>
GITHUB_APP_CLIENT_SECRET=<client-secret>
GITHUB_APP_PRIVATE_KEY=<contents-of-pem-file>

Microsoft Entra ID Sign-In

Environment variables:

AUTH_PROVIDER=entra
GITHUB_IDENTITY_MODE=enterprise-managed-users
ENTRA_TENANT_ID=<tenant-id>
ENTRA_CLIENT_ID=<app-registration-client-id>
ENTRA_CLIENT_SECRET=<client-secret>

Backstage callback URL:

https://<portal-url>/api/auth/microsoft/handler/frame

5. Golden Path Templates

Valid Templates (YAML-compatible with Backstage parser)

Registration

Templates are registered via catalog.locations in app-config.production.yaml:

catalog:
  locations:
    - type: url
      target: https://github.com/<org>/<repo>/blob/main/golden-paths/<horizon>/<template>/template.yaml
      rules:
        - allow: [Template]

6. Codespaces Integration

Each Golden Path template skeleton includes a .devcontainer/devcontainer.json that configures:

• Base image with required SDKs
• VS Code extensions for the template type
• Port forwarding for development servers
• Post-create setup scripts

Example: Python Microservice

{
  "name": "Python Microservice",
  "image": "mcr.microsoft.com/devcontainers/python:3.11",
  "features": {
    "ghcr.io/devcontainers/features/azure-cli:1": {},
    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python", "ms-python.pylint", "redhat.vscode-yaml"]
    }
  },
  "postCreateCommand": "pip install -r requirements.txt",
  "forwardPorts": [8000]
}

7. Troubleshooting

Backstage pod not starting

kubectl logs -n backstage -l app.kubernetes.io/name=backstage --tail=50
kubectl describe pod -n backstage -l app.kubernetes.io/name=backstage

Templates not loading

# Check for YAML parse errors
kubectl logs -n backstage -l app.kubernetes.io/name=backstage | grep 'YAML error'

# Verify catalog locations
kubectl exec -n backstage deploy/backstage -- cat /app/app-config.production.yaml | grep -A 2 'locations'

GitHub auth not working

# Test auth endpoint
kubectl exec -n backstage deploy/backstage -- \
  node -e "fetch('http://localhost:7007/api/auth/github/start?env=development',{redirect:'manual'}).then(r=>console.log(r.status))"
# Expected: 302

Database connection

kubectl exec -n backstage deploy/backstage -- \
  node -e "fetch('http://localhost:7007/.backstage/health/v1/readiness').then(r=>console.log(r.status))"
# Expected: 200