OpenChoreo Backstage Plugins

This repository contains Backstage plugins for integrating with OpenChoreo, providing a developer portal for cloud-native application management, deployment visualization, and observability.

Features

• Environment Management: View and manage application environments and workloads
• Cell Diagrams: Visualize system architecture and component relationships
• Runtime Logs: Real-time log viewing and filtering capabilities
• Build Integration: Track builds and deployment pipelines
• Scaffolding: Templates for creating OpenChoreo projects and components
• Catalog Integration: Automatic discovery and management of OpenChoreo entities

Prerequisites

OpenChoreo Setup

Follow the setup guide

Local Domain Configuration

To access the OpenChoreo services locally, you need to configure DNS resolution for .localhost domains.

Setup (Required)

Add the following entries to your /etc/hosts file:

sudo nano /etc/hosts

Add these lines:

127.0.0.1       openchoreo.localhost
127.0.0.1       api.openchoreo.localhost
127.0.0.1       thunder.openchoreo.localhost

Save and exit. The changes take effect immediately.

Why is this needed?

While browsers automatically resolve .localhost domains to 127.0.0.1, Node.js and other tools use system DNS which doesn't have this built-in behavior for subdomains. The /etc/hosts entries ensure consistent resolution across all tools.

Alternative Approaches

If you cannot modify /etc/hosts, you can:

• Use IP directly: Connect to http://127.0.0.1 instead and set the Host header manually in your requests
• DNS lookup override: Implement custom DNS resolution in your Node.js code to intercept .localhost domains
• Local DNS server: Run dnsmasq or similar to handle .localhost wildcard resolution

However, the /etc/hosts approach is recommended for its simplicity and reliability.

Development Setup

Required Tools

• Node.js 22
• Yarn 4.4.1
• Docker

1. Install Dependencies

yarn install

2. Local Development Setup

If you're running OpenChoreo locally and want to connect Backstage (running at localhost:3000/7007) to it:

Note: The following steps are for the single cluster setup.

helm upgrade 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-json 'backstage.auth.redirectUrls=["http://localhost:3000/api/auth/openchoreo-auth/handler/frame","http://localhost:7007/api/auth/openchoreo-auth/handler/frame","http://openchoreo.localhost:8080/api/auth/openchoreo-auth/handler/frame"]'

To develop observability plane features, port-forward the observer API:

kubectl patch clusterobservabilityplane default --type='merge' -p '{"spec":{"observerURL":"http://localhost:9097"}}'

kubectl port-forward -n openchoreo-observability-plane svc/observer 9097:8080

Receiving live catalog-sync events locally

When running Backstage locally with yarn start, the OpenChoreo event-forwarder still posts webhooks to the in-cluster Backstage Service by default. Your local backend on localhost:7007 will not receive them, and the catalog falls back to the periodic full sync only.

To point the event-forwarder at your local Backstage:

helm upgrade 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-json 'eventForwarder.config.webhooks.endpoints=[{"url":"http://host.docker.internal:7007/api/events/http/openchoreo"}]'

kubectl rollout restart deploy/event-forwarder -n openchoreo-control-plane

host.docker.internal resolves from inside the k3d node back to the host's loopback. To switch back to the in-cluster Backstage Service, repeat the command with http://backstage:7007/api/events/http/openchoreo as the URL.

# Copy the pre-configured local development template
cp app-config.local.yaml.example app-config.local.yaml

# Start Backstage
yarn start

# Access at http://localhost:3000

This is the easiest way to get started - all values are pre-configured to connect your local Backstage instance to the OpenChoreo services (*.openchoreo.localhost).

What's in app-config.local.yaml?

The app-config.local.yaml.example file contains hardcoded values for:

• Frontend URL: http://localhost:3000
• Backend URL: http://localhost:7007
• OpenChoreo API: http://api.openchoreo.localhost:8080/api/v1
• Thunder IDP: http://thunder.openchoreo.localhost:8080
• OAuth Credentials: Pre-configured from helm values
  • Client ID: openchoreo-backstage-client
  • Client Secret: backstage-portal-secret

Note: app-config.local.yaml is gitignored and won't affect Docker builds or production deployments. The Docker build only uses app-config.production.yaml.

Optional: GitHub Integration

If you need GitHub integration for catalog/templates, add your personal access token to app-config.local.yaml:

integrations:
  github:
    - host: github.com
      token: YOUR_GITHUB_TOKEN_HERE

3. Configuration Files

The application uses three configuration files:

File	Purpose	Used When
app-config.yaml	Base configuration with environment variable placeholders	Referenced by both local and Docker builds
app-config.local.yaml	Local development overrides (gitignored)	Local development with yarn start
app-config.production.yaml	Production configuration	Docker builds, k3d cluster, production Kubernetes

Configuration Loading Order:

Backstage CLI automatically loads configs in this order (later files override earlier ones):

1. app-config.yaml
2. app-config.local.yaml (if it exists)

Advanced: Using Environment Variables

If you prefer to use environment variables instead of app-config.local.yaml, you can set these in your shell:

export BACKSTAGE_BASE_URL=http://localhost:3000
export BACKEND_SECRET=your-secret-key-here
export OPENCHOREO_API_URL=http://api.openchoreo.localhost:8080/api/v1
export THUNDER_BASE_URL=http://thunder.openchoreo.localhost:8080
# User sign-in client (OIDC — used by auth.providers.openchoreo-auth)
export OPENCHOREO_AUTH_CLIENT_ID=openchoreo-backstage-client
export OPENCHOREO_AUTH_CLIENT_SECRET=backstage-portal-secret
export OPENCHOREO_AUTH_AUTHORIZATION_URL=http://thunder.openchoreo.localhost:8080/oauth2/authorize
export OPENCHOREO_AUTH_TOKEN_URL=http://thunder.openchoreo.localhost:8080/oauth2/token
# Service client (client credentials — used by background tasks such as the Catalog Provider)
# Can be the same client as above in development, but should be a separate client in production
export OPENCHOREO_SERVICE_CLIENT_ID=openchoreo-backstage-client
export OPENCHOREO_SERVICE_CLIENT_SECRET=backstage-portal-secret
export GITHUB_TOKEN=your-github-token  # Optional

Then run: yarn start

Note: In production deployments (Kubernetes/Helm), environment variables are automatically injected by the Helm chart. See the openchoreo/openchoreo repository at install/helm/openchoreo/templates/backstage/deployment.yaml for details.

4. Start the Application

# Start both frontend and backend
yarn start

# Or start individual services
yarn build:backend  # Build backend first
yarn start          # Start full application

Development Mode: When using yarn start, two separate processes will start:

• Frontend: http://localhost:3000 (webpack dev server) - Access the application here
• Backend API: http://localhost:7007 (API endpoints only)

Production Mode: After building with yarn build:all, the backend will serve both the static frontend assets and API endpoints from http://localhost:7007 (or your configured BACKSTAGE_BASE_URL).

Note: If you access http://localhost:7007 directly in development mode (without building first), you'll see a 403 error because the @backstage/plugin-app-backend has no built frontend assets to serve. Always access http://localhost:3000 during development.

For day-to-day development commands (test, lint, build, plugin development workflows) and the contribution workflow (changesets, releases), see CONTRIBUTING.md.

Available Plugins

• @openchoreo/backstage-plugin - Frontend UI components
• @openchoreo/backstage-plugin-backend - Backend API services
• @openchoreo/backstage-plugin-api - Shared API client library
• @openchoreo/backstage-plugin-catalog-backend-module - Catalog entity provider
• @openchoreo/backstage-plugin-scaffolder-backend-module - Scaffolder actions

Installation

The plugins are published to GitHub Packages. To install them in your Backstage application:

# Configure npm to use GitHub Packages for @openchoreo scope
echo "@openchoreo:registry=https://npm.pkg.github.com" >> .npmrc

# Install the plugins you need
yarn add @openchoreo/backstage-plugin
yarn add @openchoreo/backstage-plugin-backend
yarn add @openchoreo/backstage-plugin-api

Note: You'll need a GitHub personal access token with packages:read permission to install from GitHub Packages.

Feature Flags

OpenChoreo includes configurable feature flags that allow you to enable or disable major functionality without code changes.

Available Feature Flags

Feature	Environment Variable	Description
Workflows	OPENCHOREO_FEATURES_WORKFLOWS_ENABLED	Workflow plane / CI pipeline features. When disabled, hides Workflows tab and WorkflowsOverviewCard from component pages.
Observability	OPENCHOREO_FEATURES_OBSERVABILITY_ENABLED	Metrics, Traces, and Runtime Logs. When disabled, hides these tabs and RuntimeHealthCard from component pages.
Auth	OPENCHOREO_FEATURES_AUTH_ENABLED	OAuth authentication. When disabled, users are automatically logged in as guests (demo/development mode).
Authz	OPENCHOREO_FEATURES_AUTHZ_ENABLED	Authorization / Access Control. When disabled, hides Access Control sidebar and pages.

Configuration

Local Development (app-config.local.yaml):

openchoreo:
  features:
    workflows:
      enabled: true
    observability:
      enabled: true
    auth:
      enabled: false # Use guest mode for local development
    authz:
      enabled: true

Production (Environment Variables):

The Helm chart automatically injects these environment variables. You can configure them via Helm values:

backstage:
  features:
    workflowsEnabled: true
    observabilityEnabled: true
    authEnabled: true
    authzEnabled: true

Behavior When Features Are Disabled

When a feature is disabled:

• Tabs remain visible but show an informative empty state explaining that the feature is disabled
• Overview cards for the feature are hidden from the Overview tab
• This approach ensures consistent navigation while clearly communicating feature availability

Catalog Sync

OpenChoreo entities are synced to the Backstage catalog through two mechanisms:

• Event-driven sync: The OpenChoreo event-forwarder watches Kubernetes resources in the control plane and posts change notifications to Backstage's events HTTP topic (/api/events/http/openchoreo). Backstage applies a delta update to the catalog within seconds.
• Periodic full sync: A scheduled task re-fetches all OpenChoreo state and applies a full update. This catches anything missed by the event path.

Both are enabled by default. If the event-driven sync is disabled, the periodic full sync becomes the only sync mechanism.

Configuration

Setting	Environment Variable	Default	Description
openchoreo.events.enabled	OPENCHOREO_EVENTS_ENABLED	true	Enables event-driven catalog sync. When false, the entity provider runs in poll-only mode. Should match eventForwarder.enabled.
openchoreo.schedule.frequency	OPENCHOREO_CATALOG_SYNC_FREQUENCY	300	Seconds between periodic full syncs. Lower the value when eventForwarder.enabled is false.

The events HTTP topic is registered in app-config.yaml (events.http.topics: [openchoreo]). When running Backstage locally, see Receiving live catalog-sync events locally for pointing the event-forwarder at your local backend.

Production (Helm):

The Helm chart automatically injects these environment variables. You can configure them via Helm values:

backstage:
  catalogSync:
    frequency: 300
  events:
    enabled: true
eventForwarder:
  enabled: true

External CI Platform Integration

OpenChoreo includes built-in support for viewing CI build status from external platforms directly in Backstage.

Supported Platforms

Platform	Required Annotation	Environment Variables
Jenkins	jenkins.io/job-full-name	JENKINS_BASE_URL, JENKINS_USERNAME, JENKINS_API_KEY
GitHub Actions	github.com/project-slug	GITHUB_TOKEN
GitLab CI	gitlab.com/project-slug or gitlab.com/project-id	GITLAB_HOST, GITLAB_TOKEN

How It Works

External CI plugins work differently based on the platform:

• Jenkins: Backend plugin is always enabled and handles missing config gracefully (API calls fail, not startup)
• GitHub Actions: Uses the GitHub integration token from integrations.github - no separate backend plugin needed
• GitLab: Backend plugin requires integrations.gitlab config at startup. The plugin is commented out by default - you must uncomment it in packages/backend/src/index.ts after adding GitLab config.

The UI components (tabs and status cards) appear when the entity has the required CI annotation.

Configuration

Local Development (app-config.local.yaml)

# Jenkins Configuration
jenkins:
  baseUrl: http://jenkins.example.com
  username: admin
  apiKey: YOUR_JENKINS_API_KEY

# GitHub Integration (used by GitHub Actions and scaffolder)
integrations:
  github:
    - host: github.com
      token: YOUR_GITHUB_TOKEN

  # GitLab Integration (required for GitLab CI)
  gitlab:
    - host: gitlab.com
      token: YOUR_GITLAB_TOKEN

Note for GitLab: Unlike Jenkins, the GitLab backend plugin requires configuration at startup. After adding GitLab config to app-config.local.yaml, you must also uncomment the GitLab backend plugin in packages/backend/src/index.ts:

backend.add(import('@immobiliarelabs/backstage-plugin-gitlab-backend'));

Production (Helm Chart)

For Kubernetes deployments, configure CI integrations via Helm values:

backstage:
  externalCI:
    jenkins:
      enabled: true
      baseUrl: 'https://jenkins.example.com'
      username: 'admin'
      apiKey: 'your-jenkins-api-key'
    github:
      enabled: true
      token: 'ghp_xxxxxxxxxxxx'
    gitlab:
      enabled: true
      host: 'gitlab.com'
      token: 'glpat-xxxxxxxxxxxx'

The Helm chart will:

• Inject environment variables when enabled: true
• Store sensitive values (apiKey, token) in Kubernetes secrets
• Skip injection when enabled: false (default)

Adding CI Annotations

Once configured, add annotations to your components:

1. Navigate to the component in Backstage
2. Click the context menu (...) and select Edit Annotations
3. Add the appropriate CI annotation for your platform
4. Click Save

When annotations are present, you'll see:

• Status cards on the component Overview page (replaces the Workflows card when external CI is configured)
• Dedicated tabs (Jenkins, GitHub Actions, or GitLab) with full build history

For detailed setup instructions, see the External CI Integration Guide.

Contributing

Development workflow, changeset conventions, and the release process are documented in CONTRIBUTING.md.

Documentation

• Check individual plugin README files in plugins/ directory
• Visit Backstage documentation for general Backstage guidance