Entity views

OpenChoreo ships entity-page tabs for Domain, System, and Component entities. They mirror what the in-tree OpenChoreo portal shows, so a user navigating from the OpenChoreo UI into your Backstage instance sees the same tabs they're used to.

Under NFS, tabs auto-mount

If you followed the install guide Section 4 — Core on the default NFS scaffold, every tab in the table below is contributed by the plugin's /alpha export as an EntityContentBlueprint extension and mounts automatically on the correct entity kind. You do not need to edit EntityPage.tsx (the NFS scaffold does not even create one). The wiring example further down applies only to legacy hosts.

Tab catalog

Every tab below ships in one of three "tab packs". Install only the packs whose tabs you want; tabs whose pack is not installed simply won't appear in the layout.

Kind	Tab	Component / Path	Package	Notes
Domain	Overview	(built-in)	@openchoreo/backstage-plugin	Cards: NamespaceProjectsCard, NamespaceResourcesCard.
Domain	Definition	ResourceDefinitionTab (/definition)	@openchoreo/backstage-plugin	Raw OpenChoreo resource manifest.
System	Overview	(built-in)	@openchoreo/backstage-plugin	Cards: ProjectComponentsCard, DeploymentPipelineCard.
System	Definition	ResourceDefinitionTab (/definition)	@openchoreo/backstage-plugin
System	Cell Diagram	CellDiagram (/cell-diagram)	@openchoreo/backstage-plugin	Project-level architecture view.
System	Logs	ObservabilityProjectRuntimeLogs (/logs)	@openchoreo/backstage-plugin-openchoreo-observability	Project-scoped runtime logs.
System	Traces	ObservabilityTraces (/traces)	@openchoreo/backstage-plugin-openchoreo-observability
System	Incidents	ObservabilityProjectIncidents (/incidents)	@openchoreo/backstage-plugin-openchoreo-observability
System	RCA Reports	ObservabilityRCA (/rca-reports)	@openchoreo/backstage-plugin-openchoreo-observability	Root-cause analysis agent reports.
System	Cost Analysis	ObservabilityCostAnalysis (/cost-analysis)	@openchoreo/backstage-plugin-openchoreo-observability	FinOps agent reports.
Component	Overview	(built-in)	@openchoreo/backstage-plugin	Cards: DeploymentStatusCard, RuntimeHealthCard, Deployments widget.
Component	Definition	ResourceDefinitionTab (/definition)	@openchoreo/backstage-plugin
Component	Build	Workflows (/workflows)	@openchoreo/backstage-plugin-openchoreo-ci	Workflow runs / triggers.
Component	Deploy	Environments (/environments)	@openchoreo/backstage-plugin	Per-environment runtime status.
Component	Logs	ObservabilityRuntimeLogs (/runtime-logs)	@openchoreo/backstage-plugin-openchoreo-observability	Component-scoped runtime logs.
Component	Events	ObservabilityRuntimeEvents (/runtime-events)	@openchoreo/backstage-plugin-openchoreo-observability	Component-scoped runtime events.
Component	Metrics	ObservabilityMetrics (/metrics)	@openchoreo/backstage-plugin-openchoreo-observability
Component	Alerts	ObservabilityAlerts (/alerts)	@openchoreo/backstage-plugin-openchoreo-observability
Component	Wirelogs	ObservabilityWirelogs (/wirelogs)	@openchoreo/backstage-plugin-openchoreo-observability	Service-mesh wire-level logs.
Workflow / ClusterWorkflow	Runs	WorkflowRuns (/runs)	@openchoreo/backstage-plugin-openchoreo-workflows	Only for spec.type === 'Generic'.

Each openchoreo-observability / openchoreo-ci / openchoreo-workflows frontend package has a matching backend package (-backend suffix) — install both. The frontend talks to the backend at a Backstage discovery endpoint; the backend talks to OpenChoreo at ${openchoreo.baseUrl} and /resolve-urls for observability.

Cards on the Overview tab

@openchoreo/backstage-plugin's /alpha export contributes a wide set of EntityCardBlueprint extensions:

• Domain Overview: NamespaceProjectsCard, NamespaceResourcesCard.
• System Overview: ProjectComponentsCard, DeploymentPipelineCard, CellTopologyCard.
• Component Overview: DeploymentStatusCard, RuntimeHealthCard, Deployments widget linking to the Deploy tab.
• Environment / DataPlane / WorkflowPlane / ObservabilityPlane / DeploymentPipeline Overview: kind-specific status and configuration cards (30+ in total covering every OpenChoreo platform kind).

Under NFS the cards auto-mount into the default Overview Grid alongside the upstream About / Links / Labels cards. Under the legacy install you compose them by hand in your EntityPage.tsx.

Settings tabs

Beyond entity pages, the plugin contributes two tabs to Backstage's own user settings page. They auto-mount — there is nothing to wire.

Tab	Path	Extension id
Access Control	/settings/access-control	sub-page:openchoreo/access-control
Secrets	/settings/secrets	sub-page:openchoreo/secrets

Access Control is only useful with authz enabled, and Secrets only with secret management enabled. Settings tabs rather than standalone pages, because that is where the OpenChoreo portal already puts them — so a host and the portal end up with the same layout instead of diverging. To place them yourself instead, switch the sub-pages off through app.extensions and mount AccessControlContent / SecretsContent where you want them; see Feature discovery.

The plugin exposes accessControl and secrets on its routes map if you need to bind external route refs to them.

Available from 1.4.0

On 1.3.x these components exist but nothing mounts them and they have no route — you must place them yourself.

What the views actually render

<Environments /> issues authenticated calls to ${openchoreo.baseUrl} via the Backstage backend proxy at /api/openchoreo/*. It reads the entity's annotations to determine which OpenChoreo project and component to query. Components synced by the catalog provider already have these annotations — for components imported from your own catalog-info.yaml, the tab renders an "OpenChoreo metadata not found" empty state.

<CellDiagram /> does the same against ${openchoreo.baseUrl}/projects/{name}/cell-diagram for the project the system corresponds to.

Observability tabs first call the observability backend's /resolve-urls endpoint to discover the per-environment Observer/RCA/FinOps URLs, then call those services directly with the IDP token attached (header x-openchoreo-direct: true to bypass any intermediate proxies).

The Build tab (Workflows) calls the CI backend, which proxies to OpenChoreo's workflow API.

Hiding or moving tabs under NFS

If you want to suppress a tab on a specific kind, or move it to a different path, override the contributed EntityContentBlueprint extension. Each tab is registered with a stable extension ID — find the ID in the plugin's alpha.tsx (e.g. componentDeployEntityContent) and override its attachTo or disabled in your customAppModule:

import { openchoreoPluginAlphaBase } from "@openchoreo/backstage-plugin/alpha";

const customised = openchoreoPluginAlphaBase.withOverrides({
  extensions: [
    openchoreoPluginAlphaBase
      .getExtension("entity-content:openchoreo/component-deploy")
      .override({
        // hide on a specific kind, or change the route, etc.
        disabled: true,
      }),
  ],
});

Then add customised to createApp({ features: [...] }) instead of openchoreoPluginAlpha.

Legacy wiring example

For hosts on the legacy frontend system (see install guide Section 9), tabs must be mounted by hand in packages/app/src/components/catalog/EntityPage.tsx:

packages/app/src/components/catalog/EntityPage.tsx (legacy)

import {
  Environments,
  CellDiagram,
  ResourceDefinitionTab,
} from '@openchoreo/backstage-plugin';
import { Workflows } from '@openchoreo/backstage-plugin-openchoreo-ci';
import {
  ObservabilityMetrics,
  ObservabilityAlerts,
  ObservabilityRuntimeLogs,
  ObservabilityRuntimeEvents,
  ObservabilityWirelogs,
  ObservabilityProjectRuntimeLogs,
  ObservabilityTraces,
  ObservabilityProjectIncidents,
  ObservabilityRCA,
  ObservabilityCostAnalysis,
} from '@openchoreo/backstage-plugin-openchoreo-observability';

// componentEntityPage / defaultEntityPage:
<EntityLayout.Route path="/environments" title="Deploy">
  <Environments />
</EntityLayout.Route>
<EntityLayout.Route path="/definition" title="Definition">
  <ResourceDefinitionTab />
</EntityLayout.Route>
<EntityLayout.Route path="/workflows" title="Build">
  <Workflows />
</EntityLayout.Route>
<EntityLayout.Route path="/runtime-logs" title="Logs">
  <ObservabilityRuntimeLogs />
</EntityLayout.Route>
<EntityLayout.Route path="/runtime-events" title="Events">
  <ObservabilityRuntimeEvents />
</EntityLayout.Route>
<EntityLayout.Route path="/metrics" title="Metrics">
  <ObservabilityMetrics />
</EntityLayout.Route>
<EntityLayout.Route path="/alerts" title="Alerts">
  <ObservabilityAlerts />
</EntityLayout.Route>
<EntityLayout.Route path="/wirelogs" title="Wirelogs">
  <ObservabilityWirelogs />
</EntityLayout.Route>

// systemPage:
<EntityLayout.Route path="/definition" title="Definition">
  <ResourceDefinitionTab />
</EntityLayout.Route>
<EntityLayout.Route path="/cell-diagram" title="Cell">
  <CellDiagram />
</EntityLayout.Route>
<EntityLayout.Route path="/logs" title="Logs">
  <ObservabilityProjectRuntimeLogs />
</EntityLayout.Route>
<EntityLayout.Route path="/traces" title="Traces">
  <ObservabilityTraces />
</EntityLayout.Route>
<EntityLayout.Route path="/incidents" title="Incidents">
  <ObservabilityProjectIncidents />
</EntityLayout.Route>
<EntityLayout.Route path="/rca-reports" title="RCA Reports">
  <ObservabilityRCA />
</EntityLayout.Route>
<EntityLayout.Route path="/cost-analysis" title="Cost Analysis">
  <ObservabilityCostAnalysis />
</EntityLayout.Route>

// domainPage:
<EntityLayout.Route path="/definition" title="Definition">
  <ResourceDefinitionTab />
</EntityLayout.Route>

OpenChoreo synced components have type strings like deployment/web-application and deployment/service. The default componentPage EntitySwitch only routes service/website to the page that includes Environments — add the Environments route to defaultEntityPage too if you want it on every component kind.

Other extensions you can opt into

The @openchoreo/backstage-plugin package re-exports more components than the install guide wires. These are not part of the canonical install but are available for hosts that want richer overview cards or standalone pages:

Export	Use
RuntimeHealthCard	Smaller component-level health card for the Overview tab.
DeploymentStatusCard	Per-environment deployment status, for the Overview tab.
DeploymentPipelineCard	Deployment pipeline summary on a Component overview.
EnvironmentStatusSummaryCard	Aggregated environment status on an Environment entity page.
AccessControlContent	Access Control body, also mounted as a settings tab.
SecretsContent	Secret management body, also mounted as a settings tab.

These ship in the same @openchoreo/backstage-plugin package — no extra installation step.

Hiding tabs when annotations are missing (legacy)

For legacy hosts that want a tab to only appear on entities the OpenChoreo provider synced, gate it on the openchoreo.io/component-name annotation:

import { isOpenChoreoComponent } from "@openchoreo/backstage-plugin-common";

<EntityLayout.Route
  path="/environments"
  title="Deploy"
  if={isOpenChoreoComponent}
>
  <Environments />
</EntityLayout.Route>;

(isOpenChoreoComponent checks for the standard OpenChoreo annotations; see @openchoreo/backstage-plugin-common for the full list.)

Frontend dependencies

The plugin uses MUI v4 (@material-ui/core@4.12.x), matching Backstage's current default. If your host app has migrated to MUI v5, you must keep both: do not remove @material-ui/core@4.x from your dependencies. Note that the install guide pins @mui/material (v5) via resolutions to fix a material-ui-popup-state transitive resolution issue — see Section 2 of the install guide.

@material-ui/lab@4.0.0-alpha.61 is required for some sub-components — add it to your app workspace if you do not already depend on it.

The observability pack pulls recharts, @material-ui/pickers, and @date-io/date-fns transitively; the CI pack pulls @rjsf/* for dynamic workflow-parameter forms. Both are pinned by the packages themselves.