From 7617d711318e3dbc1a85308d2afd5ac990765225 Mon Sep 17 00:00:00 2001 From: kavith Date: Wed, 12 Aug 2026 12:34:22 +0200 Subject: [PATCH 1/2] docs(backstage-plugins): fix install guide inaccuracies found in end-to-end test --- .../compatibility-matrix.mdx | 19 ++-- .../installing-into-existing-backstage.mdx | 107 +++++++++++++++--- .../backstage-plugins/troubleshooting.mdx | 53 +++++++-- .../compatibility-matrix.mdx | 19 ++-- .../installing-into-existing-backstage.mdx | 107 +++++++++++++++--- .../backstage-plugins/troubleshooting.mdx | 53 +++++++-- 6 files changed, 292 insertions(+), 66 deletions(-) diff --git a/docs/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx b/docs/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx index dc908ad9..356d7c50 100644 --- a/docs/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx +++ b/docs/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx @@ -10,13 +10,18 @@ The OpenChoreo plugin set is tested against a specific Backstage release line. I ## Tested combination -| Component | Version | -| ---------------------- | ------------ | -| Backstage release line | **1.51.0** | -| Node.js | 20.x or 22.x | -| Yarn | 4.13.x | -| `@backstage/cli` | 0.36.x | -| OpenChoreo plugin set | `1.2.x` | +| Component | Version | +| ----------------------- | ------------ | +| Backstage release line | **1.51.0** | +| `@backstage/create-app` | 0.8.3 | +| Node.js | 22.x or 24.x | +| Yarn | 4.4.1 | +| `@backstage/cli` | 0.36.x | +| OpenChoreo plugin set | `1.2.x` | + +`@backstage/create-app@0.8.3` is the scaffolder release that produces Backstage `1.51.0`, and the Yarn version listed is the one that scaffold ships in `.yarn/releases/`. Node 20 is **not** supported — the scaffold declares `"engines": { "node": "22 || 24" }`. + +If you scaffold at a newer Backstage release and use `versions:bump --release 1.51.0` to come down, your Yarn version will be whatever that newer scaffold shipped (4.13.x at time of writing) rather than 4.4.1. Both work. ## Required `resolutions` diff --git a/docs/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx b/docs/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx index 138ab5fe..be3742b4 100644 --- a/docs/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx +++ b/docs/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx @@ -21,29 +21,49 @@ OpenChoreo plugins are published to **GitHub Packages** under the [`@openchoreo` ::: -:::tip Tracking the upcoming 1.2.0 release +:::tip Tracking prereleases -The install commands on this page reference `@openchoreo/@^1.2.0`, which will be the GA dist-tag of the next plugin release. While `1.2.0` is still under active development, install via the `next` dist-tag to get the latest prerelease today: +The install commands on this page reference `@openchoreo/@^1.2.0`, which resolves to the newest stable `1.2.x` release. Stable releases are published under the `latest` dist-tag; prereleases go to `next`. To track the cutting edge instead: ```bash yarn workspace app add @openchoreo/backstage-plugin@next ``` -Once `1.2.0` GA is announced, swap `@next` for `@^1.2.0` to pin to the stable release. - ::: ## 1. Prerequisites - A Backstage workspace on the [supported Backstage version](./compatibility-matrix.mdx). This guide pins to **Backstage `1.51.0`**. -- The workspace must be scaffolded with the **default NFS scaffold**: `npx @backstage/create-app@latest`. (Do NOT pass `--legacy`. If you must stay on legacy, see [Section 9](#9-legacy-frontend-system-fallback).) -- Node.js **20 or 22**, Yarn **4.13.x** (the current `create-app` scaffold ships Yarn 4.13.0 in `.yarn/releases/`). +- The workspace must be scaffolded with the **default NFS scaffold** (do NOT pass `--legacy`; if you must stay on legacy, see [Section 9](#9-legacy-frontend-system-fallback)). +- Node.js **22 or 24** — the scaffold declares `"engines": { "node": "22 || 24" }`, so Node 20 will not work. +- Yarn **4.4.1** if you scaffold at `1.51.0` as described below. (`create-app@latest` ships a newer Yarn — see [Section 3](#authenticate-to-github-packages).) - Access to a running OpenChoreo control plane (local `k3d` or a deployed cluster). - OAuth client credentials for the OpenChoreo Identity Provider (used by the catalog sync and user sign-in). On `k3d` the helm chart pre-seeds these; for a deployed cluster see [Identity configuration](../identity-configuration.mdx). -:::tip Backstage version +:::tip Getting Backstage 1.51.0 without a downgrade + +`create-app@latest` gives you whatever Backstage release is current, which is newer than the tested `1.51.0`. Pin the scaffolder to the matching release instead, and there is nothing to undo afterwards: + +```bash +npx @backstage/create-app@0.8.3 +cat backstage.json # -> { "version": "1.51.0" } +``` + +`@backstage/create-app@0.8.3` is the release that ships Backstage `1.51.0`. If you already have an app on a different release line, use `versions:bump` instead — see [Section 2](#2-pin-backstage-versions). + +`create-app` has no `--name` flag, so the command prompts for one. To script it: `printf 'my-app\n' | npx @backstage/create-app@0.8.3 --path ./my-app`. + +::: + +:::info Optional tab packs need cluster-side planes + +If you plan to install the Observability (Section 5) or CI/Build and Workflows (Sections 6–7) packs, the corresponding OpenChoreo planes must exist in the cluster. On the `k3d` quick start they are opt-in: + +```bash +./install.sh --with-observability --with-build +``` -`create-app@latest` will likely give you Backstage `1.52.x` or newer at the time you read this. After scaffolding, run `yarn backstage-cli versions:bump --release 1.51.0` (covered in [Section 2](#2-pin-backstage-versions)) to align with the tested combination. +Without them the tabs install and render, but have no data behind them. ::: @@ -70,32 +90,60 @@ yarn backstage-cli versions:bump --release 1.51.0 yarn install ``` -…to align before adding the OpenChoreo packages. +…to align before adding the OpenChoreo packages. `versions:bump` handles downgrades as well as upgrades, so this works from a newer release line too. + +:::note + +If you are creating a brand-new app, prefer `create-app@0.8.3` ([Section 1](#1-prerequisites)) over scaffolding at the latest release and bumping down. Scaffolding at the right version keeps the `@backstage/*` version churn out of your first commit, so the diff that adds OpenChoreo contains only OpenChoreo changes. + +::: ## 3. Authenticate to GitHub Packages {#authenticate-to-github-packages} GitHub Packages requires authentication even for `read:packages`-only operations. Create a [classic Personal Access Token](https://github.com/settings/tokens/new) with the `read:packages` scope, then wire it into your package manager. -**Yarn 4 (Berry)** — the current `create-app` scaffold's `.yarnrc.yml` enables a 3-day [npm minimum-age gate](https://yarnpkg.com/configuration/yarnrc#npmMinimalAgeGate) that blocks newly published packages. Update `.yarnrc.yml` to both add the `@openchoreo` scope auth **and** pre-approve the scope so fresh OpenChoreo releases install immediately: +**Yarn 4 (Berry)** — add the `@openchoreo` scope to `.yarnrc.yml`. Keep the `nodeLinker` and `yarnPath` lines your scaffold already generated and append the `npmScopes` block: ```yaml title=".yarnrc.yml" nodeLinker: node-modules -npmMinimalAgeGate: 3d -npmPreapprovedPackages: - - "@backstage/*" - - "@openchoreo/*" -yarnPath: .yarn/releases/yarn-4.13.0.cjs +# Leave this at whatever your scaffold generated. The Backstage 1.51.0 scaffold +# ships Yarn 4.4.1; newer scaffolds ship a newer release. +yarnPath: .yarn/releases/yarn-4.4.1.cjs npmScopes: openchoreo: npmRegistryServer: "https://npm.pkg.github.com" npmAlwaysAuth: true - npmAuthToken: "${GITHUB_PACKAGES_TOKEN}" + npmAuthToken: "${GITHUB_PACKAGES_TOKEN:-}" ``` …then `export GITHUB_PACKAGES_TOKEN=` before running `yarn install`. Berry expands the `${...}` placeholder from the environment so the token never lands in the repo. +:::warning Keep the `:-` in `${GITHUB_PACKAGES_TOKEN:-}` + +Yarn expands `.yarnrc.yml` variables on **every** invocation, not just `yarn install`. With a bare `"${GITHUB_PACKAGES_TOKEN}"`, any yarn command run without the variable exported — `yarn tsc`, `yarn start`, `yarn lint` — aborts before doing anything: + +```text +Usage Error: Environment variable not found (GITHUB_PACKAGES_TOKEN) in /path/to/.yarnrc.yml +``` + +The `:-` suffix supplies an empty default, so day-to-day commands work unauthenticated and only install/fetch needs the real token. + +::: + +:::note Newly published releases and the minimum-age gate + +Scaffolds newer than Backstage 1.51.0 set a 3-day [npm minimum-age gate](https://yarnpkg.com/configuration/yarnrc#npmMinimalAgeGate) in `.yarnrc.yml`. It only blocks packages published within the last three days, so it rarely affects a normal install. If you are installing an OpenChoreo release that fresh and Yarn refuses it, pre-approve the scope: + +```yaml title=".yarnrc.yml" +npmPreapprovedPackages: + - "@backstage/*" + - "@openchoreo/*" +``` + +::: + In **CI**, GitHub Actions can use the auto-issued `GITHUB_TOKEN` instead of a PAT, provided the workflow has `permissions: { packages: read }` and the running repo is in (or a fork of) an org the package is published from. --- @@ -586,7 +634,9 @@ openchoreo: permission: enabled: true # required for the OpenChoreo permission policy to run -# The catalog must accept Domain entities from the OpenChoreo provider. +# Only needed for static `catalog.locations` you add yourself. Entities emitted by +# an EntityProvider — which is how the OpenChoreo sync works — bypass catalog.rules +# entirely, so this block does not gate the OpenChoreo entities. catalog: rules: - allow: [Component, System, Domain, API, Resource, Location, Group, User] @@ -633,6 +683,16 @@ Expected: 5. Click into any project (`kind=system`) → **CELL DIAGRAM** and **DEFINITION** tabs are present and render real data. 6. Click into any component → **DEPLOY** and **DEFINITION** tabs are present and render real data. +:::warning Complete step 3 before judging steps 4–6 + +With `permission.enabled: true`, the catalog looks **empty** until OpenChoreo sign-in has completed. This is expected: the OpenChoreo permission policy authorizes catalog reads against the signed-in user's IDP token, and a guest session (or any service credential) has no OpenChoreo identity to evaluate, so the OpenChoreo entities are filtered out of every read. + +What makes this easy to misread is that nothing reports it. There is no error and no warning, the provider still logs `Successfully processed N entities`, and the provider's `Template` entities are **not** filtered — so the Scaffolder fills with OpenChoreo templates while the catalog looks empty. + +To confirm the sync itself is healthy, set `permission.enabled: false`, restart, and the full entity set appears. Set it back to `true` afterwards. + +::: + If you get a 401 on tab data fetches, your `customAppModule`'s `ApiBlueprint` for `fetchApiRef` isn't being registered — check that `customAppModule` is in the `features: [...]` array in `App.tsx`. If you get "No permissions" on Deploy, same check for the `permissionApiRef` `ApiBlueprint`. See [Troubleshooting](./troubleshooting.mdx) for the full failure-mode index. --- @@ -798,7 +858,18 @@ The plugin contributes the standalone `/workflows` page as a `PageBlueprint` — Optionally add a sidebar entry in `packages/app/src/modules/nav/Sidebar.tsx` so users can navigate to it. -### 7.4 Verify +### 7.4 Configure + +This pack shares the same feature flag as the CI/Build tab in [Section 6](#6-add-cibuild-tab-optional). If you installed Section 6 it is already set; if you are installing Section 7 on its own, add it: + +```yaml +openchoreo: + features: + workflows: + enabled: true +``` + +### 7.5 Verify Restart `yarn start`. Navigate to `http://localhost:3000/workflows` → see the org-level workflow list. diff --git a/docs/platform-engineer-guide/backstage-plugins/troubleshooting.mdx b/docs/platform-engineer-guide/backstage-plugins/troubleshooting.mdx index dd60ce64..c85a8b23 100644 --- a/docs/platform-engineer-guide/backstage-plugins/troubleshooting.mdx +++ b/docs/platform-engineer-guide/backstage-plugins/troubleshooting.mdx @@ -71,7 +71,7 @@ YN0090: @openchoreo/backstage-plugin@npm:1.2.0 is younger than the configured minimum age (3d) ``` -**Cause:** the NFS `create-app` scaffold's `.yarnrc.yml` sets `npmMinimalAgeGate: 3d` to protect against supply-chain attacks. Fresh `@openchoreo/*` prereleases sometimes land within that window. +**Cause:** `create-app` scaffolds newer than Backstage 1.51.0 set `npmMinimalAgeGate: 3d` in `.yarnrc.yml` to protect against supply-chain attacks. Fresh `@openchoreo/*` prereleases sometimes land within that window. (The Backstage 1.51.0 scaffold does not set this key at all, so you will not see this there.) **Fix:** add `@openchoreo/*` to the pre-approved list in `.yarnrc.yml`: @@ -81,6 +81,32 @@ npmPreapprovedPackages: - "@openchoreo/*" ``` +## Every yarn command fails: `Environment variable not found (GITHUB_PACKAGES_TOKEN)` + +``` +Usage Error: Environment variable not found (GITHUB_PACKAGES_TOKEN) in /path/to/.yarnrc.yml +``` + +**Cause:** `.yarnrc.yml` references the token as a bare `"${GITHUB_PACKAGES_TOKEN}"`. Yarn expands `.yarnrc.yml` variables on **every** invocation, not just `yarn install` — so `yarn tsc`, `yarn start` and `yarn lint` all abort whenever the variable is not exported. + +**Fix:** add the `:-` empty-default suffix: + +```yaml title=".yarnrc.yml" +npmScopes: + openchoreo: + npmRegistryServer: "https://npm.pkg.github.com" + npmAlwaysAuth: true + npmAuthToken: "${GITHUB_PACKAGES_TOKEN:-}" +``` + +Day-to-day commands then run unauthenticated, and only install/fetch needs the real token exported. + +## `403 does not match expected scopes` from `npm.pkg.github.com` + +**Cause:** using a `gh` CLI token. GitHub Packages rejects it regardless of the CLI's own scopes. + +**Fix:** create a [classic Personal Access Token](https://github.com/settings/tokens/new) with the `read:packages` scope and export that as `GITHUB_PACKAGES_TOKEN`. + ## Missing `alpha.core.metrics` service ref ``` @@ -235,15 +261,26 @@ lsof -i :7007 -i :3000 kill ``` -## Catalog provider runs but no entities show up +## Catalog provider logs `Successfully processed N entities` but the catalog is empty -Check `catalog.rules.allow` includes `Domain` and any other custom kinds the OpenChoreo provider produces. The catalog silently drops disallowed kinds. +Almost always: **you are not signed in to OpenChoreo yet.** -```yaml -catalog: - rules: - - allow: [Component, System, Domain, API, Resource, Location, Group, User] -``` +With `permission.enabled: true`, the OpenChoreo permission policy authorizes catalog reads against the signed-in user's IDP token. A guest session — or any service credential — has no OpenChoreo identity for the authorization service to evaluate, so every OpenChoreo entity is filtered out of the response. Sign in via **Sign in using OpenChoreo** and they appear. + +Nothing reports this. There is no error, no warning, the provider still logs a successful run, and debug logging shows the entities being stitched. Two details make it more confusing: + +- The provider's `Template` entities are **not** filtered, so the Scaffolder fills with OpenChoreo templates while the catalog looks empty. The integration looks healthy. +- The frontend shows the scaffold's own example entities (`example-website`, `examples`), because those come from static `catalog.locations` rather than from OpenChoreo. + +To confirm the sync itself is fine, temporarily set `permission.enabled: false` and restart. The full entity set — components, systems, domains, environments and the `Cluster*` kinds — appears immediately. Set it back to `true` afterwards. + +If you are signed in and entities are still missing, check that `openchoreo.features.authz.enabled` matches how the cluster was deployed; see [the cluster-mirroring warning](./installing-into-existing-backstage.mdx#configure-app-config). + +:::note `catalog.rules` is not the cause + +An earlier version of this page suggested adding kinds to `catalog.rules.allow`. That does not affect the OpenChoreo sync: entities emitted by an **EntityProvider bypass `catalog.rules` entirely**, which only governs static `catalog.locations`. You can verify this — the provider's `Template` entities are admitted even when `Template` is absent from the allow-list. + +::: ## `NotificationsSidebarItem` crashes the app at boot diff --git a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx index dc908ad9..356d7c50 100644 --- a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx +++ b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/compatibility-matrix.mdx @@ -10,13 +10,18 @@ The OpenChoreo plugin set is tested against a specific Backstage release line. I ## Tested combination -| Component | Version | -| ---------------------- | ------------ | -| Backstage release line | **1.51.0** | -| Node.js | 20.x or 22.x | -| Yarn | 4.13.x | -| `@backstage/cli` | 0.36.x | -| OpenChoreo plugin set | `1.2.x` | +| Component | Version | +| ----------------------- | ------------ | +| Backstage release line | **1.51.0** | +| `@backstage/create-app` | 0.8.3 | +| Node.js | 22.x or 24.x | +| Yarn | 4.4.1 | +| `@backstage/cli` | 0.36.x | +| OpenChoreo plugin set | `1.2.x` | + +`@backstage/create-app@0.8.3` is the scaffolder release that produces Backstage `1.51.0`, and the Yarn version listed is the one that scaffold ships in `.yarn/releases/`. Node 20 is **not** supported — the scaffold declares `"engines": { "node": "22 || 24" }`. + +If you scaffold at a newer Backstage release and use `versions:bump --release 1.51.0` to come down, your Yarn version will be whatever that newer scaffold shipped (4.13.x at time of writing) rather than 4.4.1. Both work. ## Required `resolutions` diff --git a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx index 138ab5fe..be3742b4 100644 --- a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx +++ b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/installing-into-existing-backstage.mdx @@ -21,29 +21,49 @@ OpenChoreo plugins are published to **GitHub Packages** under the [`@openchoreo` ::: -:::tip Tracking the upcoming 1.2.0 release +:::tip Tracking prereleases -The install commands on this page reference `@openchoreo/@^1.2.0`, which will be the GA dist-tag of the next plugin release. While `1.2.0` is still under active development, install via the `next` dist-tag to get the latest prerelease today: +The install commands on this page reference `@openchoreo/@^1.2.0`, which resolves to the newest stable `1.2.x` release. Stable releases are published under the `latest` dist-tag; prereleases go to `next`. To track the cutting edge instead: ```bash yarn workspace app add @openchoreo/backstage-plugin@next ``` -Once `1.2.0` GA is announced, swap `@next` for `@^1.2.0` to pin to the stable release. - ::: ## 1. Prerequisites - A Backstage workspace on the [supported Backstage version](./compatibility-matrix.mdx). This guide pins to **Backstage `1.51.0`**. -- The workspace must be scaffolded with the **default NFS scaffold**: `npx @backstage/create-app@latest`. (Do NOT pass `--legacy`. If you must stay on legacy, see [Section 9](#9-legacy-frontend-system-fallback).) -- Node.js **20 or 22**, Yarn **4.13.x** (the current `create-app` scaffold ships Yarn 4.13.0 in `.yarn/releases/`). +- The workspace must be scaffolded with the **default NFS scaffold** (do NOT pass `--legacy`; if you must stay on legacy, see [Section 9](#9-legacy-frontend-system-fallback)). +- Node.js **22 or 24** — the scaffold declares `"engines": { "node": "22 || 24" }`, so Node 20 will not work. +- Yarn **4.4.1** if you scaffold at `1.51.0` as described below. (`create-app@latest` ships a newer Yarn — see [Section 3](#authenticate-to-github-packages).) - Access to a running OpenChoreo control plane (local `k3d` or a deployed cluster). - OAuth client credentials for the OpenChoreo Identity Provider (used by the catalog sync and user sign-in). On `k3d` the helm chart pre-seeds these; for a deployed cluster see [Identity configuration](../identity-configuration.mdx). -:::tip Backstage version +:::tip Getting Backstage 1.51.0 without a downgrade + +`create-app@latest` gives you whatever Backstage release is current, which is newer than the tested `1.51.0`. Pin the scaffolder to the matching release instead, and there is nothing to undo afterwards: + +```bash +npx @backstage/create-app@0.8.3 +cat backstage.json # -> { "version": "1.51.0" } +``` + +`@backstage/create-app@0.8.3` is the release that ships Backstage `1.51.0`. If you already have an app on a different release line, use `versions:bump` instead — see [Section 2](#2-pin-backstage-versions). + +`create-app` has no `--name` flag, so the command prompts for one. To script it: `printf 'my-app\n' | npx @backstage/create-app@0.8.3 --path ./my-app`. + +::: + +:::info Optional tab packs need cluster-side planes + +If you plan to install the Observability (Section 5) or CI/Build and Workflows (Sections 6–7) packs, the corresponding OpenChoreo planes must exist in the cluster. On the `k3d` quick start they are opt-in: + +```bash +./install.sh --with-observability --with-build +``` -`create-app@latest` will likely give you Backstage `1.52.x` or newer at the time you read this. After scaffolding, run `yarn backstage-cli versions:bump --release 1.51.0` (covered in [Section 2](#2-pin-backstage-versions)) to align with the tested combination. +Without them the tabs install and render, but have no data behind them. ::: @@ -70,32 +90,60 @@ yarn backstage-cli versions:bump --release 1.51.0 yarn install ``` -…to align before adding the OpenChoreo packages. +…to align before adding the OpenChoreo packages. `versions:bump` handles downgrades as well as upgrades, so this works from a newer release line too. + +:::note + +If you are creating a brand-new app, prefer `create-app@0.8.3` ([Section 1](#1-prerequisites)) over scaffolding at the latest release and bumping down. Scaffolding at the right version keeps the `@backstage/*` version churn out of your first commit, so the diff that adds OpenChoreo contains only OpenChoreo changes. + +::: ## 3. Authenticate to GitHub Packages {#authenticate-to-github-packages} GitHub Packages requires authentication even for `read:packages`-only operations. Create a [classic Personal Access Token](https://github.com/settings/tokens/new) with the `read:packages` scope, then wire it into your package manager. -**Yarn 4 (Berry)** — the current `create-app` scaffold's `.yarnrc.yml` enables a 3-day [npm minimum-age gate](https://yarnpkg.com/configuration/yarnrc#npmMinimalAgeGate) that blocks newly published packages. Update `.yarnrc.yml` to both add the `@openchoreo` scope auth **and** pre-approve the scope so fresh OpenChoreo releases install immediately: +**Yarn 4 (Berry)** — add the `@openchoreo` scope to `.yarnrc.yml`. Keep the `nodeLinker` and `yarnPath` lines your scaffold already generated and append the `npmScopes` block: ```yaml title=".yarnrc.yml" nodeLinker: node-modules -npmMinimalAgeGate: 3d -npmPreapprovedPackages: - - "@backstage/*" - - "@openchoreo/*" -yarnPath: .yarn/releases/yarn-4.13.0.cjs +# Leave this at whatever your scaffold generated. The Backstage 1.51.0 scaffold +# ships Yarn 4.4.1; newer scaffolds ship a newer release. +yarnPath: .yarn/releases/yarn-4.4.1.cjs npmScopes: openchoreo: npmRegistryServer: "https://npm.pkg.github.com" npmAlwaysAuth: true - npmAuthToken: "${GITHUB_PACKAGES_TOKEN}" + npmAuthToken: "${GITHUB_PACKAGES_TOKEN:-}" ``` …then `export GITHUB_PACKAGES_TOKEN=` before running `yarn install`. Berry expands the `${...}` placeholder from the environment so the token never lands in the repo. +:::warning Keep the `:-` in `${GITHUB_PACKAGES_TOKEN:-}` + +Yarn expands `.yarnrc.yml` variables on **every** invocation, not just `yarn install`. With a bare `"${GITHUB_PACKAGES_TOKEN}"`, any yarn command run without the variable exported — `yarn tsc`, `yarn start`, `yarn lint` — aborts before doing anything: + +```text +Usage Error: Environment variable not found (GITHUB_PACKAGES_TOKEN) in /path/to/.yarnrc.yml +``` + +The `:-` suffix supplies an empty default, so day-to-day commands work unauthenticated and only install/fetch needs the real token. + +::: + +:::note Newly published releases and the minimum-age gate + +Scaffolds newer than Backstage 1.51.0 set a 3-day [npm minimum-age gate](https://yarnpkg.com/configuration/yarnrc#npmMinimalAgeGate) in `.yarnrc.yml`. It only blocks packages published within the last three days, so it rarely affects a normal install. If you are installing an OpenChoreo release that fresh and Yarn refuses it, pre-approve the scope: + +```yaml title=".yarnrc.yml" +npmPreapprovedPackages: + - "@backstage/*" + - "@openchoreo/*" +``` + +::: + In **CI**, GitHub Actions can use the auto-issued `GITHUB_TOKEN` instead of a PAT, provided the workflow has `permissions: { packages: read }` and the running repo is in (or a fork of) an org the package is published from. --- @@ -586,7 +634,9 @@ openchoreo: permission: enabled: true # required for the OpenChoreo permission policy to run -# The catalog must accept Domain entities from the OpenChoreo provider. +# Only needed for static `catalog.locations` you add yourself. Entities emitted by +# an EntityProvider — which is how the OpenChoreo sync works — bypass catalog.rules +# entirely, so this block does not gate the OpenChoreo entities. catalog: rules: - allow: [Component, System, Domain, API, Resource, Location, Group, User] @@ -633,6 +683,16 @@ Expected: 5. Click into any project (`kind=system`) → **CELL DIAGRAM** and **DEFINITION** tabs are present and render real data. 6. Click into any component → **DEPLOY** and **DEFINITION** tabs are present and render real data. +:::warning Complete step 3 before judging steps 4–6 + +With `permission.enabled: true`, the catalog looks **empty** until OpenChoreo sign-in has completed. This is expected: the OpenChoreo permission policy authorizes catalog reads against the signed-in user's IDP token, and a guest session (or any service credential) has no OpenChoreo identity to evaluate, so the OpenChoreo entities are filtered out of every read. + +What makes this easy to misread is that nothing reports it. There is no error and no warning, the provider still logs `Successfully processed N entities`, and the provider's `Template` entities are **not** filtered — so the Scaffolder fills with OpenChoreo templates while the catalog looks empty. + +To confirm the sync itself is healthy, set `permission.enabled: false`, restart, and the full entity set appears. Set it back to `true` afterwards. + +::: + If you get a 401 on tab data fetches, your `customAppModule`'s `ApiBlueprint` for `fetchApiRef` isn't being registered — check that `customAppModule` is in the `features: [...]` array in `App.tsx`. If you get "No permissions" on Deploy, same check for the `permissionApiRef` `ApiBlueprint`. See [Troubleshooting](./troubleshooting.mdx) for the full failure-mode index. --- @@ -798,7 +858,18 @@ The plugin contributes the standalone `/workflows` page as a `PageBlueprint` — Optionally add a sidebar entry in `packages/app/src/modules/nav/Sidebar.tsx` so users can navigate to it. -### 7.4 Verify +### 7.4 Configure + +This pack shares the same feature flag as the CI/Build tab in [Section 6](#6-add-cibuild-tab-optional). If you installed Section 6 it is already set; if you are installing Section 7 on its own, add it: + +```yaml +openchoreo: + features: + workflows: + enabled: true +``` + +### 7.5 Verify Restart `yarn start`. Navigate to `http://localhost:3000/workflows` → see the org-level workflow list. diff --git a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/troubleshooting.mdx b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/troubleshooting.mdx index dd60ce64..c85a8b23 100644 --- a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/troubleshooting.mdx +++ b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/troubleshooting.mdx @@ -71,7 +71,7 @@ YN0090: @openchoreo/backstage-plugin@npm:1.2.0 is younger than the configured minimum age (3d) ``` -**Cause:** the NFS `create-app` scaffold's `.yarnrc.yml` sets `npmMinimalAgeGate: 3d` to protect against supply-chain attacks. Fresh `@openchoreo/*` prereleases sometimes land within that window. +**Cause:** `create-app` scaffolds newer than Backstage 1.51.0 set `npmMinimalAgeGate: 3d` in `.yarnrc.yml` to protect against supply-chain attacks. Fresh `@openchoreo/*` prereleases sometimes land within that window. (The Backstage 1.51.0 scaffold does not set this key at all, so you will not see this there.) **Fix:** add `@openchoreo/*` to the pre-approved list in `.yarnrc.yml`: @@ -81,6 +81,32 @@ npmPreapprovedPackages: - "@openchoreo/*" ``` +## Every yarn command fails: `Environment variable not found (GITHUB_PACKAGES_TOKEN)` + +``` +Usage Error: Environment variable not found (GITHUB_PACKAGES_TOKEN) in /path/to/.yarnrc.yml +``` + +**Cause:** `.yarnrc.yml` references the token as a bare `"${GITHUB_PACKAGES_TOKEN}"`. Yarn expands `.yarnrc.yml` variables on **every** invocation, not just `yarn install` — so `yarn tsc`, `yarn start` and `yarn lint` all abort whenever the variable is not exported. + +**Fix:** add the `:-` empty-default suffix: + +```yaml title=".yarnrc.yml" +npmScopes: + openchoreo: + npmRegistryServer: "https://npm.pkg.github.com" + npmAlwaysAuth: true + npmAuthToken: "${GITHUB_PACKAGES_TOKEN:-}" +``` + +Day-to-day commands then run unauthenticated, and only install/fetch needs the real token exported. + +## `403 does not match expected scopes` from `npm.pkg.github.com` + +**Cause:** using a `gh` CLI token. GitHub Packages rejects it regardless of the CLI's own scopes. + +**Fix:** create a [classic Personal Access Token](https://github.com/settings/tokens/new) with the `read:packages` scope and export that as `GITHUB_PACKAGES_TOKEN`. + ## Missing `alpha.core.metrics` service ref ``` @@ -235,15 +261,26 @@ lsof -i :7007 -i :3000 kill ``` -## Catalog provider runs but no entities show up +## Catalog provider logs `Successfully processed N entities` but the catalog is empty -Check `catalog.rules.allow` includes `Domain` and any other custom kinds the OpenChoreo provider produces. The catalog silently drops disallowed kinds. +Almost always: **you are not signed in to OpenChoreo yet.** -```yaml -catalog: - rules: - - allow: [Component, System, Domain, API, Resource, Location, Group, User] -``` +With `permission.enabled: true`, the OpenChoreo permission policy authorizes catalog reads against the signed-in user's IDP token. A guest session — or any service credential — has no OpenChoreo identity for the authorization service to evaluate, so every OpenChoreo entity is filtered out of the response. Sign in via **Sign in using OpenChoreo** and they appear. + +Nothing reports this. There is no error, no warning, the provider still logs a successful run, and debug logging shows the entities being stitched. Two details make it more confusing: + +- The provider's `Template` entities are **not** filtered, so the Scaffolder fills with OpenChoreo templates while the catalog looks empty. The integration looks healthy. +- The frontend shows the scaffold's own example entities (`example-website`, `examples`), because those come from static `catalog.locations` rather than from OpenChoreo. + +To confirm the sync itself is fine, temporarily set `permission.enabled: false` and restart. The full entity set — components, systems, domains, environments and the `Cluster*` kinds — appears immediately. Set it back to `true` afterwards. + +If you are signed in and entities are still missing, check that `openchoreo.features.authz.enabled` matches how the cluster was deployed; see [the cluster-mirroring warning](./installing-into-existing-backstage.mdx#configure-app-config). + +:::note `catalog.rules` is not the cause + +An earlier version of this page suggested adding kinds to `catalog.rules.allow`. That does not affect the OpenChoreo sync: entities emitted by an **EntityProvider bypass `catalog.rules` entirely**, which only governs static `catalog.locations`. You can verify this — the provider's `Template` entities are admitted even when `Template` is absent from the allow-list. + +::: ## `NotificationsSidebarItem` crashes the app at boot From a1b9c0785fe346482c1c90ff0d3c1deac0b9fc79 Mon Sep 17 00:00:00 2001 From: kavith Date: Wed, 12 Aug 2026 13:01:41 +0200 Subject: [PATCH 2/2] docs(backstage-plugins): document Resource entity tabs and Definition kind coverage --- .../backstage-plugins/entity-views.mdx | 61 ++++++++++++------- .../backstage-plugins/entity-views.mdx | 61 ++++++++++++------- 2 files changed, 76 insertions(+), 46 deletions(-) diff --git a/docs/platform-engineer-guide/backstage-plugins/entity-views.mdx b/docs/platform-engineer-guide/backstage-plugins/entity-views.mdx index d7806974..6e9de6cf 100644 --- a/docs/platform-engineer-guide/backstage-plugins/entity-views.mdx +++ b/docs/platform-engineer-guide/backstage-plugins/entity-views.mdx @@ -6,7 +6,7 @@ sidebar_position: 5 # 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. +OpenChoreo ships entity-page tabs for **Domain**, **System**, and **Component** entities, plus **Resource** (managed resources only) and **Workflow** / **ClusterWorkflow**. 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. :::tip Under NFS, tabs auto-mount @@ -18,28 +18,43 @@ If you followed the [install guide Section 4 — Core](./installing-into-existin 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'`. | +| 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. | +| Resource | Overview | (built-in) | `@openchoreo/backstage-plugin` | Cards: resource parameters, resource deployments. Managed resources only. | +| Resource | Deploy | `Environments` (`/environments`) | `@openchoreo/backstage-plugin` | Managed resources only — see note below. | +| Resource | Definition | `ResourceDefinitionTab` (`/definition`) | `@openchoreo/backstage-plugin` | | +| Workflow / ClusterWorkflow | Runs | `WorkflowRuns` (`/runs`) | `@openchoreo/backstage-plugin-openchoreo-workflows` | Only for `spec.type === 'Generic'`. | + +:::note Resource tabs are label-gated + +The `Resource` rows above only apply to **OpenChoreo-managed** resources — those carrying the label `openchoreo.io/managed: 'true'`. A plain Backstage `Resource` entity from your own catalog files gets none of them. This is how a managed dependency such as a Postgres, Redis or Valkey instance ends up with its own per-environment Deploy view, alongside the services that consume it. + +::: + +:::note `Definition` is not limited to the kinds listed above + +`ResourceDefinitionTab` mounts on any kind that maps to an OpenChoreo resource — currently `component`, `system`, `domain`, `resource`, `environment`, `dataplane`, `clusterdataplane`, `workflowplane`, `clusterworkflowplane`, `observabilityplane`, `clusterobservabilityplane`, `deploymentpipeline`, `componenttype`, `resourcetype`, `clustercomponenttype`, `clusterresourcetype`, `traittype`, `clustertraittype`, `workflow`, `clusterworkflow` and `componentworkflow`. The table lists it only against the kinds most users browse. + +::: 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. diff --git a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/entity-views.mdx b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/entity-views.mdx index d7806974..6e9de6cf 100644 --- a/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/entity-views.mdx +++ b/versioned_docs/version-v1.2.x/platform-engineer-guide/backstage-plugins/entity-views.mdx @@ -6,7 +6,7 @@ sidebar_position: 5 # 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. +OpenChoreo ships entity-page tabs for **Domain**, **System**, and **Component** entities, plus **Resource** (managed resources only) and **Workflow** / **ClusterWorkflow**. 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. :::tip Under NFS, tabs auto-mount @@ -18,28 +18,43 @@ If you followed the [install guide Section 4 — Core](./installing-into-existin 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'`. | +| 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. | +| Resource | Overview | (built-in) | `@openchoreo/backstage-plugin` | Cards: resource parameters, resource deployments. Managed resources only. | +| Resource | Deploy | `Environments` (`/environments`) | `@openchoreo/backstage-plugin` | Managed resources only — see note below. | +| Resource | Definition | `ResourceDefinitionTab` (`/definition`) | `@openchoreo/backstage-plugin` | | +| Workflow / ClusterWorkflow | Runs | `WorkflowRuns` (`/runs`) | `@openchoreo/backstage-plugin-openchoreo-workflows` | Only for `spec.type === 'Generic'`. | + +:::note Resource tabs are label-gated + +The `Resource` rows above only apply to **OpenChoreo-managed** resources — those carrying the label `openchoreo.io/managed: 'true'`. A plain Backstage `Resource` entity from your own catalog files gets none of them. This is how a managed dependency such as a Postgres, Redis or Valkey instance ends up with its own per-environment Deploy view, alongside the services that consume it. + +::: + +:::note `Definition` is not limited to the kinds listed above + +`ResourceDefinitionTab` mounts on any kind that maps to an OpenChoreo resource — currently `component`, `system`, `domain`, `resource`, `environment`, `dataplane`, `clusterdataplane`, `workflowplane`, `clusterworkflowplane`, `observabilityplane`, `clusterobservabilityplane`, `deploymentpipeline`, `componenttype`, `resourcetype`, `clustercomponenttype`, `clusterresourcetype`, `traittype`, `clustertraittype`, `workflow`, `clusterworkflow` and `componentworkflow`. The table lists it only against the kinds most users browse. + +::: 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.