Backstage Configuration

OpenChoreo uses Backstage as its developer portal, providing a unified interface for managing organizations, projects, components, and deployments. This guide covers configuration options for customizing Backstage in your OpenChoreo deployment.

Backstage configuration is done via Helm values in the Control Plane chart.

Core Configuration

Console/UI URL:

backstage:
  appConfig:
    app:
      baseUrl: "https://console.example.com"
    backend:
      baseUrl: "https://console.example.com"

OpenChoreo API URL:

openchoreoApi:
  ingress:
    enabled: true
    hosts:
      - host: api.example.com
        paths:
          - path: /

Authentication

By default, OpenChoreo configures Thunder as the identity provider for Backstage with a pre-configured OAuth client for testing purposes. If you want to integrate an external identity provider instead, create an OAuth 2.0 client with the following requirements:

OAuth Client Requirements:

1. Grant Types: The OAuth client must support both:

   • authorization_code - For user authentication and login flows
   • client_credentials - For service-to-service authentication

2. Token Format: Configure the client to issue JWT tokens (not opaque tokens)

3. Redirect URLs: Add the Backstage callback URL:

   • <protocol>://<backstage-domain>/api/auth/openchoreo-auth/handler/frame
   • Replace <protocol> with http or https and <backstage-domain> with your actual Backstage domain

Helm Configuration:

Once you have created the OAuth client, configure Backstage with the client credentials:

helm upgrade --install openchoreo-control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \
--version 0.0.0-latest-dev \
--namespace openchoreo-control-plane \
--reuse-values \
--set backstage.auth.clientId="your-client-id" \
--set backstage.auth.clientSecret="your-client-secret" \
--set backstage.auth.redirectUrls\[0\]="<protocol>://<backstage-domain>/api/auth/openchoreo-auth/handler/frame"

See Identity Provider Configuration for detailed setup instructions.

Feature Flags

backstage:
  features:
    workflows:
      enabled: true       # Requires Build Plane
    observability:
      enabled: true       # Requires Observability Plane

Resource Configuration

backstage:
  replicas: 1
  resources:
    limits:
      cpu: 2000m
      memory: 2Gi
    requests:
      cpu: 200m
      memory: 256Mi

  autoscaling:
    enabled: false
    minReplicas: 1
    maxReplicas: 5

Environment Variables

Add custom environment variables to the Backstage deployment:

backstage:
  env:
    - name: NODE_ENV
      value: production
    - name: LOG_LEVEL
      value: info
    - name: PORT
      value: "7007"

Commonly Used Variables

Variable	Description	Default
NODE_ENV	Node.js environment	production
LOG_LEVEL	Logging verbosity	info
PORT	HTTP server port	7007
OPENCHOREO_API_URL	OpenChoreo API endpoint	Auto-configured
THUNDER_BASE_URL	Thunder IdP URL	Auto-configured

Ingress Configuration

backstage:
  ingress:
    enabled: true
    className: "your-ingress-class"
    hosts:
      - host: console.example.com
        paths:
          - path: /
    tls:
      - secretName: console-tls
        hosts:
          - console.example.com

Service Configuration

backstage:
  service:
    type: ClusterIP
    port: 7007

OpenChoreo API Integration

Backstage communicates with the OpenChoreo API for backend operations:

backstage:
  openchoreoApi:
    url: ""  # Auto-configured to internal service URL

The API URL defaults to http://{release-name}-api.{namespace}.svc.cluster.local:8080/api/v1.

Backend Secret

For session encryption (should be stable across restarts):

backstage:
  backendSecret: "your-32-character-secret-here"

Health Checks

Backstage health checks are pre-configured:

Check	Endpoint	Default
Liveness	/healthcheck	Enabled
Readiness	/healthcheck	Enabled

Example Configurations

Development

backstage:
  enabled: true
  replicas: 1
  baseUrl: "http://localhost:7007"
  ingress:
    enabled: true
    hosts:
      - host: localhost
        paths:
          - path: /
  resources:
    limits:
      cpu: 1000m
      memory: 1Gi
    requests:
      cpu: 100m
      memory: 256Mi
  features:
    workflows:
      enabled: true
    observability:
      enabled: true

Production

backstage:
  enabled: true
  replicas: 2
  baseUrl: "https://console.example.com"
  backendSecret: "your-production-secret-32chars!"

  ingress:
    enabled: true
    hosts:
      - host: console.example.com
        paths:
          - path: /
    tls:
      - secretName: console-tls
        hosts:
          - console.example.com

  resources:
    limits:
      cpu: 2000m
      memory: 2Gi
    requests:
      cpu: 500m
      memory: 512Mi

  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    targetCPUUtilizationPercentage: 70

  features:
    workflows:
      enabled: true
    observability:
      enabled: true

API-only Mode

For headless deployments where only the API is needed:

backstage:
  enabled: false

# Security can also be disabled for development
security:
  enabled: false

Troubleshooting

Backstage Not Loading

Check pod status and logs:

kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/name=backstage
kubectl logs -n openchoreo-control-plane deployment/backstage

Authentication Issues

Verify OAuth configuration:

# Check Backstage environment variables
kubectl exec -n openchoreo-control-plane deployment/backstage -- env | grep -E "(AUTH|THUNDER)"

# Check Thunder is running
kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/name=thunder

API Connection Errors

Verify OpenChoreo API is accessible:

# Check API pod
kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/name=openchoreo-api

# Test API from Backstage pod
kubectl exec -n openchoreo-control-plane deployment/backstage -- \
  curl -s http://openchoreo-control-plane-api:8080/api/v1/health

Next Steps

• Identity Provider Configuration: Configure an external IdP
• Deployment Topology: Set up organizations and environments
• Helm Charts Reference: Complete Backstage configuration options