Backstage setup

The Anyshift Backstage integration adds live infrastructure context to the software catalog you already use. It connects one Anyshift project to:

A global Anyshift dashboard at /anyshift, with estate-wide evidence coverage and Ask Anyshift
An Anyshift tab on matching catalog entities, with runtime context, impact, and recent evidence
A cloud inventory at /cloud and cloud-aware pages for synchronized Resources
Optional infrastructure Resources and evidence-backed relations in the catalog and architecture diagram

Your Anyshift project ID and API token stay in the Backstage backend. The browser sends authenticated requests only to Backstage and never receives the Anyshift token.

The integration is currently in beta. Use the coordinated package versions below. It supports Backstage’s new frontend and backend systems. There is no legacy frontend entry point.

Before You Start

You need:

A Backstage application using the new frontend system
Backstage 1.52 or 1.53
One Anyshift project with graph data
An API token that can read that project
A Backstage permission policy

Install the Core Integration

Add these resolutions to your root package.json, preserving any existing resolutions. They pin a coordinated beta release to its public npm tarballs and avoid inconsistent registry tag metadata. Keep all four pins together when upgrading.

{
  "resolutions": {
    "@anyshift/backstage-plugin-anyshift": "https://registry.npmjs.org/@anyshift/backstage-plugin-anyshift/-/backstage-plugin-anyshift-0.1.0-beta.26.tgz",
    "@anyshift/backstage-plugin-anyshift-backend": "https://registry.npmjs.org/@anyshift/backstage-plugin-anyshift-backend/-/backstage-plugin-anyshift-backend-0.1.0-beta.24.tgz",
    "@anyshift/backstage-plugin-anyshift-common": "https://registry.npmjs.org/@anyshift/backstage-plugin-anyshift-common/-/backstage-plugin-anyshift-common-0.1.0-beta.20.tgz",
    "@anyshift/backstage-plugin-catalog-backend-module-anyshift": "https://registry.npmjs.org/@anyshift/backstage-plugin-catalog-backend-module-anyshift/-/backstage-plugin-catalog-backend-module-anyshift-0.1.0-beta.20.tgz"
  }
}

Install the frontend plugin in your app workspace and the backend plugin in your backend workspace:

yarn workspace app add @anyshift/backstage-plugin-anyshift@0.1.0-beta.26
yarn workspace backend add @anyshift/backstage-plugin-anyshift-backend@0.1.0-beta.24

backend.add(import("@anyshift/backstage-plugin-anyshift-backend"));

The frontend package is discoverable. Enable package discovery in your Backstage configuration:

app:
  packages: all

You do not need to edit App.tsx or EntityPage.tsx. Backstage discovers the global page, navigation item, API factory, and entity content from the installed package.

Configure Anyshift

Add one Anyshift project to your Backstage configuration:

anyshift:
  baseUrl: https://graph.anyshift.io
  projectId: ${ANYSHIFT_PROJECT_ID}
  token: ${ANYSHIFT_TOKEN}
  timeout: 60s
  cache:
    ttl: 60s
  ask:
    enabled: false
  query:
    enabled: false
  catalog:
    mode: disabled
    topologyMode: disabled

Set ANYSHIFT_PROJECT_ID and ANYSHIFT_TOKEN in the environment used by your Backstage backend. Do not put the token in frontend configuration or commit it to your repository. Ask Anyshift and the query console are disabled by default. Enable Ask for viewers who need guided, evidence-backed answers. Leave the query console disabled unless operators need to run deterministic, read-only Graph queries from Backstage.

Configure Permissions

The backend enforces three permissions:

Permission	Grants
`anyshift.view`	Read dashboards, entity context, cloud evidence, and use Ask Anyshift
`anyshift.query`	Run deterministic, read-only Graph queries when the query console is enabled
`anyshift.catalog.sync`	Start an immediate catalog reconciliation

Install the common package directly in the backend workspace if your permission policy imports these constants:

yarn workspace backend add @anyshift/backstage-plugin-anyshift-common@0.1.0-beta.20

Import the permissions into your existing Backstage policy:

import { AuthorizeResult } from "@backstage/plugin-permission-common";
import {
  anyshiftCatalogSyncPermission,
  anyshiftQueryPermission,
  anyshiftViewPermission,
} from "@anyshift/backstage-plugin-anyshift-common";

For a read-only rollout, grant anyshift.view to the intended users and deny anyshift.query and anyshift.catalog.sync. A typical policy decision inside handle() looks like this:

if (request.permission.name === anyshiftViewPermission.name) {
  return {
    result: user ? AuthorizeResult.ALLOW : AuthorizeResult.DENY,
  };
}

if (request.permission.name === anyshiftQueryPermission.name) {
  return { result: AuthorizeResult.DENY };
}

if (request.permission.name === anyshiftCatalogSyncPermission.name) {
  const isOperator = user?.info.ownershipEntityRefs.includes(
    "group:default/platform-operators",
  );
  return {
    result: isOperator ? AuthorizeResult.ALLOW : AuthorizeResult.DENY,
  };
}

Replace group:default/platform-operators with the group that operates your catalog. The frontend hides actions a user cannot perform, but the backend permission checks remain authoritative.

An allow-all Backstage policy grants all three permissions to every signed-in user. Replace it with an explicit production policy before enabling the query console or manual reconciliation.

Match Catalog Entities

The Anyshift tab appears on entities with either of these annotations:

anyshift.io/target
github.com/project-slug

When anyshift.io/target is absent, the plugin uses the repository name from github.com/project-slug as the runtime target. Add an explicit target when the repository and deployed workload use different names:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout
  annotations:
    github.com/project-slug: example-org/checkout
    anyshift.io/target: checkout-api
spec:
  type: service
  lifecycle: production
  owner: group:default/checkout-team

After the entity is ingested, open it in the catalog and select the Anyshift tab.

Ask About Your Estate

Ask Anyshift provides a single-question, read-only experience on the global dashboard and supported entity pages. Use it to investigate dependencies, changes, impact, inventory, and evidence coverage without writing a Graph query. Enable it in the backend configuration:

anyshift:
  ask:
    enabled: true

Users with anyshift.view can then enter a question such as:

What depends on checkout-api?

On an entity page, the scope chip makes the current Component or Resource explicit. Keep the chip to ask about that entity, or remove it before submitting to ask across the configured project. When a configured runtime ID is available, Ask uses that exact identity while the chip retains the readable service name. This avoids choosing between a Service, Deployment, and observability service that share a name. The answer shows how the question was interpreted and presents supported evidence as typed dependency, timeline, impact, inventory, resource, coverage, ranking, or ambiguity details. Resource answers show identity and incoming/outgoing relationships, with a notice when the evidence is partial or the displayed relationship list is truncated. Ask displays one current answer and does not provide conversation history. Questions and answers are not persisted by the plugin or written to its default logs. The Anyshift token remains in the Backstage backend.

Ask uses anyshift.view; it does not require anyshift.query. The entity scope helps compose the question but does not create a separate authorization boundary outside the configured Anyshift project.

Understand Entity Evidence

The Anyshift tab brings current graph evidence into the service page:

Why now? summarizes active alerts, suspected runtime conditions, and available deployment correlation. A nearby deployment is not presented as the cause unless the evidence supports that conclusion.
Affected footprint groups potentially affected workloads, downstream services, datastores, external dependencies, monitors, and SLOs. Related catalog entities are linked when a match exists.
Architecture shows observed and configured service dependencies. Select a service-to-service edge marked HTTP · N to inspect its HTTP operation evidence.

Recent deployment activity can come from specialized rollout evidence or normalized producer deployment events. The integration uses the available source automatically and keeps its evidence limitations visible. The HTTP operation inspector can show multiple observations on one edge. Each entry includes the available HTTP method, templated path, APM source, and observation time. Method-only and path-only observations remain useful and are displayed without inventing the missing value. Operation metadata is optional. An edge without HTTP · N remains a valid dependency and renders as before; missing operation evidence does not mean there was no traffic. The inspector uses the topology response already loaded for the diagram and does not make a request for each edge.

HTTP operation details require Graph API v0.2.42 or later and an APM source that supplies operation evidence. Datadog, Tempo, and Dynatrace source names use the same Backstage presentation.

The global Anyshift dashboard also includes Evidence coverage. It compares connected and expected sources, reports graph size and event coverage, and identifies observability blind spots. Use it before drawing conclusions from an empty result.

Synchronize Infrastructure Resources

Catalog synchronization is optional. Use it when you want infrastructure Resources and runtime relations next to the Components already owned by GitHub. Install the catalog module:

yarn workspace backend add @anyshift/backstage-plugin-catalog-backend-module-anyshift@0.1.0-beta.20

backend.add(
  import("@anyshift/backstage-plugin-catalog-backend-module-anyshift"),
);

Start in Shadow Mode

Shadow mode reads the graph and reports proposed matches, collisions, and Resources without writing them to the catalog:

anyshift:
  baseUrl: https://graph.anyshift.io
  projectId: ${ANYSHIFT_PROJECT_ID}
  token: ${ANYSHIFT_TOKEN}
  catalog:
    mode: shadow
    topologyMode: shadow
    fallbackOwner: group:default/anyshift-unowned
    relationshipConcurrency: 25
    inventoryTypes: [deployment, statefulset, configmap]
    workloadTypes: [deployment]
    resourceNamePatterns: []
    schedule:
      frequency: 30m
      timeout: 5m

Review the Anyshift catalog sync report entries in your Backstage logs. Confirm that component targets, owners, proposed Resources, and collisions are correct before enabling writes. Set fallbackOwner to a Group that exists in your catalog. The example uses a dedicated holding group for infrastructure that does not yet have an evidence-backed owner. catalog.mode controls infrastructure Resource publication. catalog.topologyMode independently controls Component relationship enrichment. Set both explicitly so you can review cloud inventory and service relations separately.

Enable Active Mode Gradually

Switch to active mode with a reviewed target allowlist:

anyshift:
  baseUrl: https://graph.anyshift.io
  projectId: ${ANYSHIFT_PROJECT_ID}
  token: ${ANYSHIFT_TOKEN}
  catalog:
    mode: active
    topologyMode: active
    fallbackOwner: group:default/anyshift-unowned
    inventoryTypes: [deployment, statefulset, configmap]
    workloadTypes: [deployment]
    activeTargets: [checkout-api, payments-api]
    schedule:
      frequency: 30m
      timeout: 5m

activeTargets limits Component enrichment to the listed runtime targets. Omit it only when every matched Component should be eligible. If you configure it, the list must contain at least one target. Mark an individual Component as intentionally unmanaged when it should never be synchronized:

metadata:
  annotations:
    anyshift.io/catalog-sync: excluded

Add Configured Runtime Dependencies

Observed APM topology is not the only useful source of a dependency. For ECS services, you can declare reviewed endpoint aliases so Anyshift can confirm dependencies found in task-definition configuration without returning environment values.

metadata:
  annotations:
    anyshift.io/target: checkout-api
    anyshift.io/runtime-resource-id: <stable ECS service ID>
    anyshift.io/configuration-dependencies: payments-api=payments.internal

On the dependency Component, use anyshift.io/configuration-endpoints to list the endpoint aliases that identify it:

metadata:
  annotations:
    anyshift.io/target: payments-api
    anyshift.io/configuration-endpoints: payments.internal

The catalog module creates a relation only when the configured alias is supported by graph evidence. anyshift.io/runtime-resource-id lets configuration evidence resolve a stable cloud identity while anyshift.io/target continues to identify the APM service. Use catalog.runtimeMappings to centrally configure reviewed identities for Components and provider-generated Resources. A mapping’s runtimeResourceId takes precedence over the Component annotation. Provider-generated Resources do not inherit annotations from a separate Component:

anyshift:
  catalog:
    runtimeMappings:
      - target: checkout-api
        runtimeResourceId: <stable ECS service ID>
        configurationDependencies:
          - service: payments-api
            endpoint: payments.internal
      - target: payments-api
        configurationEndpoints:
          - payments.internal

Runtime Identity and Partial Failures

Component enrichment uses separate selectors: anyshift.io/target identifies the APM service, while runtimeResourceId identifies the infrastructure runtime for connections and workload evidence. Resolve the runtime in the connected Anyshift project and select its exact graph ID. Verify the resource type, cluster, and namespace: an ECS service, its Terraform record, and an APM service may share a name; Kubernetes deployments may share names across namespaces. Without a runtime ID, the processor logs a missing-mapping warning and continues APM topology enrichment without querying connections by name. A failure in either source does not discard successful evidence from the other. Cached evidence is scoped to its selector; fallback is logged as stale, and changing a runtime ID cannot reuse connections from the previous runtime. Inspect backend warnings for the failed operation, selector, and Component when diagnosing partial enrichment. Active Component enrichment also writes the selected runtime ID to anyshift.io/runtime-resource-id, so the entity tab uses the same workload for safeguards and alert impact. This identity is retained when APM evidence is unavailable. Alert-cause queries use that workload and an explicit 24-hour window; APM topology continues to use the service selector.

Cloud Resource Types

The default inventory types are Kubernetes-oriented. For an AWS-backed project, select the resource labels you want to publish:

anyshift:
  catalog:
    mode: shadow
    inventoryTypes:
      - ECS_SERVICE
      - ECS_CLUSTER
      - LAMBDA_FUNCTION
      - RDS_DB
      - DYNAMODB_TABLE
      - S3_BUCKET
      - SQS_QUEUE
      - SNS_TOPIC
      - ECR_REPOSITORY
      - ELASTICLOADBALANCING_LOADBALANCER
    workloadTypes: [ECS_SERVICE, LAMBDA_FUNCTION]

Use resourceNamePatterns to limit the imported inventory further with case-insensitive regular expressions.

Explore Cloud Resources

When cloud Resources are synchronized, the discoverable frontend adds a Cloud navigation item at /cloud. Open a Resource to review:

Provider, account, region, ARN, and a cloud-console link when available
Direct catalog dependencies and dependents
Typed potential impact through supported graph relationships
Normalized cloud changes and their evidence limitations
Terraform code-to-state-to-cloud provenance and supported drift comparisons
Ask Anyshift scoped to the visible Resource

The Cloud and Anyshift tabs use the same cloud-aware view. Cloud Resources do not show Kubernetes safeguards that do not apply to them. Potential impact describes graph reachability, not a confirmed outage or cause. Empty cloud-change, infrastructure-as-code, drift, or impact sections mean that evidence is unavailable for the selected Resource or window. They do not prove that the Resource is healthy, unmanaged, or disconnected.

Ownership and Failure Behavior

GitHub remains authoritative for Components, Users, Groups, owners, lifecycle, and repository metadata. The Anyshift module:

Creates infrastructure Resources
Adds service-to-service, Component-to-Resource, and Resource-to-Resource relations supported by graph evidence
Enriches matched Components without recreating them
Preserves the previous complete Resource set when a synchronization attempt fails

Generated Resources carry the anyshift.io/managed-by: catalog-provider annotation. In active mode, the module also maintains resource:default/anyshift-catalog-sync, which records the result, trigger, completion time, and a bounded failure reason for the latest attempt. Users with anyshift.catalog.sync can select Reconcile now on the global Anyshift page. Scheduled and manual requests that overlap are combined into one provider run.

Verify the Installation

Start the Backstage backend with the Anyshift environment variables set.
Sign in as a user with anyshift.view.
Open /anyshift and confirm the global dashboard and Evidence coverage card load.
Open a Component with anyshift.io/target or github.com/project-slug.
Select the Anyshift tab and confirm the runtime target, Why now?, affected footprint, and architecture evidence resolve independently.
If Ask is enabled, submit one estate-wide question and one entity-scoped question. Confirm the visible scope matches the intended entity.
If an architecture edge is marked HTTP · N, select it and confirm its method or path, APM source, and observation time appear.
If catalog synchronization is enabled, review the sync report and the anyshift-catalog-sync Resource before moving either catalog mode from shadow to active.
Open /cloud, select a synchronized Resource, and confirm its identity, relations, evidence sections, and scoped Ask use the intended resource.

Troubleshooting

The Anyshift page does not appear

Confirm that the frontend package is installed in the app workspace, the app uses Backstage’s new frontend system, and app.packages is set to all. Restart the frontend after changing dependencies or configuration.

The entity does not have an Anyshift tab

Add anyshift.io/target or github.com/project-slug to the entity annotations. Use anyshift.io/target when the repository name does not match the runtime workload.

Ask Anyshift does not appear

Set anyshift.ask.enabled to true, restart the backend and frontend, and confirm the signed-in user has anyshift.view. Ask is independent of the Advanced Query setting and does not require anyshift.query.

A request returns 403 Forbidden

Check your Backstage permission policy. Dashboard, entity data, cloud evidence, and Ask require anyshift.view; queries require anyshift.query; manual reconciliation requires anyshift.catalog.sync.

A service edge has no HTTP details

Operation evidence is optional. Confirm that the Graph API is v0.2.42 or later and that the APM source supplies operation metadata for this edge. An unmarked edge still represents a dependency; missing operation details do not prove that no traffic exists.

The catalog contains no Anyshift Resources

Confirm that the catalog module is installed and registered. disabled creates nothing, while shadow reports proposed changes without applying them. In active, verify that inventoryTypes, activeTargets, and resourceNamePatterns include the intended resources.

Cloud or entity sections are empty

Check Evidence coverage and the freshness shown beside each capability. Empty changes, impact, infrastructure-as-code, deployment, or operation evidence means unknown for that entity and time window. It does not mean healthy, disconnected, or unmanaged. Retry only the failed capability when the page offers a section-level retry.

Cloud event evidence shows a limitation

A quiet source or status caveat means the event evidence is derived or incomplete. It provides context rather than a health alert. Identity warnings remain actionable when the Resource itself cannot be resolved.

A synchronization attempt fails

Find the latest Anyshift catalog sync report in the backend logs and inspect resource:default/anyshift-catalog-sync. A failed attempt leaves the last complete infrastructure Resource set in place.

Packages

The beta packages are available from npm:

For direct TypeScript access to the same infrastructure graph, see the Graph SDK guide.

Get Started

Product

Manage

Before You Start

Install the Core Integration

Configure Anyshift

Configure Permissions

Match Catalog Entities

Ask About Your Estate

Understand Entity Evidence

Synchronize Infrastructure Resources

Start in Shadow Mode

Enable Active Mode Gradually

Add Configured Runtime Dependencies

Runtime Identity and Partial Failures

Cloud Resource Types

Explore Cloud Resources

Ownership and Failure Behavior

Verify the Installation

Troubleshooting

Packages

​Before You Start

​Install the Core Integration

​Configure Anyshift

​Configure Permissions

​Match Catalog Entities

​Ask About Your Estate

​Understand Entity Evidence

​Synchronize Infrastructure Resources

​Start in Shadow Mode

​Enable Active Mode Gradually

​Add Configured Runtime Dependencies

​Runtime Identity and Partial Failures

​Cloud Resource Types

​Explore Cloud Resources

​Ownership and Failure Behavior

​Verify the Installation

​Troubleshooting

​Packages

Before You Start

Install the Core Integration

Configure Anyshift

Configure Permissions

Match Catalog Entities

Ask About Your Estate

Understand Entity Evidence

Synchronize Infrastructure Resources

Start in Shadow Mode

Enable Active Mode Gradually

Add Configured Runtime Dependencies

Runtime Identity and Partial Failures

Cloud Resource Types

Explore Cloud Resources

Ownership and Failure Behavior

Verify the Installation

Troubleshooting

Packages