How the Backstage Cost Insights plugin shows cloud cost by team
If a platform or FinOps lead wants engineering teams to see what their services cost inside Backstage, the Spotify Cost Insights plugin renders the cost views, but Backstage does not ship a cost data source. Your team must build or supply a cost data client that pulls spend from your cloud billing exports or cost APIs and returns it to the plugin in the shape it expects. That client is the real work. Confirm the plugin's current API, configuration keys and setup steps against its own repository before you scope the build, because plugin interfaces change and a page written today may not match the code you install.
Cost only becomes useful when each figure maps to an owner. The client has to attribute spend to catalog entities, usually through tags, labels or account boundaries that your cloud provider exposes, and those attributes must match the owner and system values in your catalog descriptors. Untagged or shared spend, such as data transfer, shared clusters or support fees, needs an explicit rule: allocate it, show it as unallocated, or assign it to a platform owner. Decide that rule before the first dashboard goes live, because teams will question any total they cannot trace to a service they recognize.
This is an integration on infrastructure you control. The cost client needs read-only billing credentials, a place to run on a schedule, and a store for daily aggregates, and each of these needs an owner, a rotation process and access review. Ask any partner to show how the client authenticates to your billing source, where its credentials live, and how it handles a failed sync, since stale numbers displayed as current are worse than no numbers. Plan for a recurring cost as well: the client and the mapping rules must be maintained as your tagging conventions and catalog evolve.
What you need before cost figures appear on entity pages
Cost data on an entity page is only as useful as the link between a cloud account and a catalog owner. The cards below cover the prerequisites that have to be in place before any plugin configuration starts, and they are ordered so that the tagging scheme is settled before anyone writes mapping code.
A working catalog with owners set
Cost Insights attaches spend to components, systems and teams, so the Software Catalog must already contain those entities with an owner on each one. Check that every system that carries cloud spend has a spec.owner value that resolves to a real group or user, and that orphaned components are either assigned or deliberately excluded. A cost report that lands on an unowned entity gives finance a number with no one to answer for it.
A defined tagging and account scheme
Before any mapping work starts, agree which cloud tags, labels or account boundaries identify a team, product or environment. Write the key names down, decide which one is authoritative when two disagree, and state what happens to untagged spend. Illustrative example: a team that tags resources with owner in one account and team in another will produce two partial totals that never reconcile in the portal.
Billing exports and cost API access
Confirm which billing exports or cost APIs your organization can read, such as a cloud provider's cost and usage export or a reporting API, and who grants access to them. The service identity that reads them needs read-only permissions scoped to billing data, not administrator rights on the accounts. Ask the cloud or finance team to confirm the export frequency and the data retention period, since both affect how far back a chart can go.
A host for the cost data client
The cost data client is the component you build and run, so it needs a runtime, a schedule and outbound network access to each billing source. Decide whether it runs in the same cluster as Backstage or in a separate network zone that already reaches the billing endpoints. Keep its credentials in your secrets store, and make sure the client writes only the data shape the plugin reads, so a failed run does not blank the entity pages.
Supported Backstage and Node.js versions
Check the Cost Insights plugin release notes for the Backstage version range it targets, then match your instance to that range before installing. The Backstage versioning policy supports two adjacent even-numbered Node.js releases, and the plugin must work on the line your instance runs. Confirm this in the release notes rather than assuming that the latest Backstage release is supported.
How the Cost Insights frontend and your cost data client fit together
The Cost Insights frontend plugin only displays cost views and charts. It does not reach into your cloud billing accounts itself. Your team implements a cost data client, a piece of code that fetches billing data from each source, such as the cloud provider's cost and usage exports or billing APIs, normalizes it, and returns it in the shape the frontend expects. The frontend asks for cost entries grouped by team or product, the client answers, and the chart renders what came back. Because the client owns the translation from raw billing records to the plugin's data model, most of the implementation effort sits there, not in the React components. Before you scope that work, confirm the exact client interface, the entity and group fields the plugin requests, and the date range and aggregation parameters in the plugin's current documentation. Older blog posts and example repositories often show interfaces that have since changed, and building against them is a common reason integrations break after an upgrade.
The client should run as a backend component, typically a backend module or a service alongside the Backstage backend, inside the network where your billing and cost data already lives. It authenticates to billing APIs with a read-only identity scoped to cost and usage data, such as a dedicated service principal or workload identity, and it keeps those credentials in your secret store and injects them at runtime. Billing credentials should never reach the browser. Anything the frontend sends is visible to every signed-in user and can be copied from developer tools, so the browser should only call the Backstage backend, which applies the same authentication and access rules you use elsewhere in the portal. Decide early who may see which cost figures, since per-team spend can be sensitive, and enforce that in the backend rather than in the chart configuration. Ask your cloud provider and security team to confirm which billing permissions and export mechanisms they will approve before the design is fixed.
Configuring the Cost Insights plugin and your cost data client
This sequence takes a Backstage instance from no cost data to a working Cost Insights view on team and product pages. Each step ends with a check you can run before moving on, so billing access, grouping and ownership are proven before anyone relies on the numbers.
Confirm the plugin version and its client interface
Before installing anything, open the Cost Insights plugin's own repository and find the release that matches your Backstage version. Note the cost data client interface documented for that release, including the method signatures and the shape of the returned cost objects. Your team, or the partner doing the build, records the chosen version in the project's dependency file. Done when you can name the package versions and point to the interface definition they implement.
Install the frontend and backend packages
Add the Cost Insights frontend package to the Backstage app and the backend package to the backend, both taken from the plugin's own repository and pinned to the version confirmed in the previous step. Keep the versions aligned with the other @backstage packages so that later version bumps move them together. Done when the app builds and starts, and the backend log shows the Cost Insights plugin loading without errors.
Implement the cost data client
Write the cost data client against the interface from the first step. It should call your billing source, such as a cloud provider's cost export or billing API, and return costs for a time window grouped by the keys you plan to use. Keep the client in a dedicated module so it can be tested separately from the plugin. Done when unit tests pass against recorded billing responses and the client returns a total that matches the billing console for one known account and month.
Register the client in the backend
Wire the client into the Cost Insights backend plugin so the backend uses it as the source of cost data. The registration happens in the backend entry point, where the plugin is added with your implementation. Keep the billing client on the server side only, so no billing credential or raw response reaches the browser. Done when a direct request to the Cost Insights backend endpoint returns a JSON payload containing the account total you checked in the previous step.
Store billing credentials through the secrets mechanism
Provide the billing source credentials through Backstage's configuration and secrets handling, referenced by environment variable or your secret manager, never written into the repository. Scope the credential to read-only cost data. Confirm which identity provider and sign-in setup the environment uses, since production should not rely on guest access. Done when the backend starts with the credential supplied from the secret store and a configuration review finds no billing key in source control or the frontend bundle.
Set the cost grouping keys
Decide which keys costs are grouped by, such as a team tag, a product tag, or a cloud account mapped to an owner. Use the same keys your catalog entities carry, so each cost group can be matched to a catalog owner. Check with your cloud team that these tags are enforced at resource creation, because untagged spend will fall into an unowned group. Done when a test query grouped by team returns named groups and an explicit bucket for untagged spend, with the total matching the unfiltered query.
Wire the views into entity and team pages
Add the Cost Insights entity content to the component and system pages in the frontend, and add the team or group view where your organization tracks spend. Map each view to the catalog owner and system relationships so a page shows only the costs for its own entities. Confirm the catalog data for these entities is complete before relying on the view. Done when a service page with a known tagged cost renders a non-empty dataset that matches the backend response for that entity.
Mapping cloud accounts and tags to catalog owners
This table maps each cost attribute to the catalog field that ties it to an owner, with the rule for untagged spend and the owner of shared costs. Read it as the contract between your cloud billing data and your Backstage catalog: if a row has no owner in the catalog, the cost it carries will show up as unassigned.
| Cost attribute | Where it comes from | Catalog link or rule | Who maintains it |
|---|---|---|---|
| Cloud account or project ID | Billing export account, subscription or project that owns the spend | Map each account to one owning System or Group in a reviewed mapping file, not to individual services | Cloud platform team, with the owning group named in the mapping file |
| Billing tag or label | Resource tags or labels applied at creation, such as a team or service key | Tag value must match a catalog entity name exactly; enforce required tags with policy in your cloud accounts | Platform engineering sets the tag policy, service owners apply it |
| Kubernetes namespace | Cost allocation tooling that reports spend per namespace in shared clusters | Namespace is linked to a Component or System through an annotation or mapping entry; confirm the cost tool supports this key | Cluster administrators, with service owners requesting namespace changes |
| Catalog entity annotation or owner field | The entity's spec.owner value and any annotation the cost data client reads | spec.owner names the Group or User accountable for the spend; the annotation key must match what your cost client expects | Owning team for each entity, checked during catalog reviews |
| Untagged or unmapped spend | Resources with no tag, no matching account or no namespace mapping | Assign to a defined holding owner, such as the platform team, and report it as unallocated so it stays visible | Finance or FinOps lead sets the rule, platform team clears the queue |
| Shared platform spend | Costs for clusters, networking, logging or shared databases used by several teams | Split by an agreed allocation key (for example, usage or headcount) or keep it under the platform owner; record the choice in the mapping file | Platform owner proposes the key, finance approves it |
| Services moving between teams | Ownership changes after reorganizations or handovers | Update spec.owner and the tag or account mapping in the same change, so historical and current costs follow the new owner | Outgoing and incoming team leads, with catalog reviewers confirming the change |
Choosing an ownership model for shared cloud costs
When each team owns its own cloud account or subscription, most cost attribution is done by the provider's billing structure rather than by tags. Every line item already belongs to one account, and the account is mapped to a catalog owner. The data client's main job is to read spend per account on a regular schedule and associate each account with the Backstage entity or group that owns it. The harder questions are about what sits outside the accounts.
- Account mapping: Keep a written record of which account or subscription belongs to which group, and make the catalog the source of that record.
- Shared services: Networking, DNS, identity and logging often live in a central account. Decide whether that spend stays with the platform team or is charged back by a fixed share or by usage.
- Account sprawl: Accounts created outside the process are invisible to the mapping. Check for untracked accounts before publishing totals.
- Credential scope: The client needs read-only billing access in each account or a consolidated billing view. Confirm what your provider allows for that role.
- Ownership changes: When a team is renamed or split, moving an account must update the catalog mapping in the same change.
Confirm with your finance and cloud teams whether account-level billing is complete for every account in scope.
When several teams deploy into the same account, cost attribution depends on resource tags or labels applied consistently at creation. The data client can only assign spend it can see with a team or product key, so untagged resources land in an unallocated bucket. Attribution quality is therefore a governance question as much as a reporting one. The provider's tag support and activation rules differ, so confirm how your provider applies tags to billing data before designing the model.
- Mandatory keys: Choose a small set of tag keys, such as owning team and product, and require them through policy at creation time.
- Untagged spend: Decide whether unallocated cost is reported as its own line, split by a rule, or assigned to the platform team. Publish that rule.
- Tag drift: Resources copied from templates or created by scripts often carry wrong or missing tags. Schedule a report of untagged resources.
- Data lag: Tag changes usually affect billing data only from the point they take effect, so historical views can disagree with current ones.
- Shared resources: Databases, load balancers and data transfer serving several products need an allocation key, such as proportional usage or a fixed split.
Confirm which tag keys your provider exposes in billing exports and whether they can be enforced by policy in your environment.
When many teams run workloads on the same Kubernetes clusters, the cloud bill shows nodes, not applications. Attribution has to come from inside the cluster, using namespaces, labels and resource requests, and then be matched to the cloud cost of the nodes. Requests and actual usage often differ, so the model must state which one it charges. Cost data clients for clusters usually depend on an allocation tool in the cluster, and the platform team must confirm what that tool measures before the numbers are published.
- Allocation basis: Decide whether teams are charged for requested resources, measured usage or a blend. Requests are easier to explain; usage is fairer to teams that over-request.
- Namespace ownership: Map each namespace to a catalog entity. Namespaces without an owner need a rule, and a namespace owned by two teams needs a split.
- Idle capacity: Unused node capacity is a platform decision. Charge it to the platform, spread it across tenants, or report it separately.
- Shared platform components: Ingress controllers, monitoring stacks and cluster add-ons consume capacity for every tenant. Agree how they are allocated.
- Node pool and tenant labels: Dedicated node pools make attribution clearer but can raise cost. Record that trade-off in the design.
Confirm what your allocation tooling reports for requests, usage and idle capacity before agreeing the allocation rule with teams.
Securing billing data and cloud credentials in Cost Insights
Cost data reveals spend by team, product and cloud account, and it is usually more sensitive than the portal pages that display it. The controls below work together: the credentials limit what the data client can read, the backend keeps those credentials away from browsers, and Backstage's sign-in and catalog permissions decide who sees which numbers.
Scope billing credentials to read-only cost data
Create a dedicated billing identity for the cost data client that can read cost and usage reports and nothing else. Avoid reusing an administrator key, a broad cloud role or a personal token. Confirm with your cloud provider exactly which billing actions the identity needs, and check that it cannot change budgets, accounts or resources. Review the granted permissions after each provider or plugin change.
Keep secrets in the backend
The cost data client runs in the Backstage backend, so cloud credentials should be read there from your secret store or environment, never placed in a frontend configuration value. Anything prefixed for frontend use ends up in the browser bundle, where any signed-in user can extract it. Search the built frontend output for key formats after each build to confirm nothing leaked.
Match spend visibility to identity and ownership
Team and account spend should only appear for users entitled to see it. Make sure each sign-in provider resolves to the same catalog identity, as the Backstage authentication guidance advises, so a user cannot gain wider cost access by signing in through a different provider. Do not offer guest access in production. Map cost views to the owning group in the catalog and restrict them with your permission policy.
Limit the data client's network egress
Allow the backend to reach only the billing API endpoints it needs, through a fixed egress path if your network supports one. Block general internet access from the Backstage pod or host. Confirm the exact endpoints with your cloud provider and record them in your network policy, so a compromised plugin or dependency cannot send cost data to an unexpected destination.
Log access to cost views
Record who opened cost pages and which teams or accounts they viewed, and send those events to the same audit store as other portal activity. Check that the logs capture the user identity from the resolved sign-in, not a shared service account. Confirm retention with your security team, since access logs for financial data are often requested during reviews.
Rotate billing credentials on a schedule
Set a rotation interval for the billing identity and its keys, and test the rotation in a non-production instance first. Plan for a short overlap period so the backend can switch to the new credential without losing cost data. Document who owns rotation, where the new secret is stored, and how a revoked key is detected in the backend logs.
Fixing missing, stale or misattributed cost figures
This table lists the failures teams most often hit when Cost Insights shows empty, late or wrong numbers, with the likely cause and a check you can run to confirm it. Work down the rows in order, since a missing backend registration hides every other symptom. Most fixes sit in the backend wiring, the billing export and the catalog ownership data, not in the frontend.
| Symptom | Likely cause | Check and fix |
|---|---|---|
| Cost views are empty for every entity | The cost data backend module is not registered in the Backstage backend, or the frontend plugin cannot reach its API | Confirm the backend package is added in packages/backend/src/index.ts and that the backend starts without errors. Call the cost API route directly from the backend and check that it returns JSON rather than a 404 |
| Figures stop updating or lag several days behind | The billing export your cost client reads has not refreshed, or the export delivery is delayed upstream | Check the timestamp of the newest record in your billing export or cost store. Compare it with the cloud provider's billing console. Set the client to report the data date so readers can see the age of the numbers |
| Spend appears under the wrong team or product | Tag or label drift: resources were renamed, tags were missing or applied inconsistently, so the cost client maps them to the wrong owner | Run a query on untagged and multi-tagged spend for the period. Compare tag keys against the owner annotation or spec.owner value in catalog-info.yaml. Fix the source tags first, then rerun the affected period |
| Some entities show no cost and no owner | The catalog entity has no spec.owner, or the owner refers to a group or user that is not in the catalog | Filter the catalog for components without an owner and for owner references that do not resolve. Assign owners in the descriptor or through the ownership source your catalog uses before judging cost coverage |
| Cost requests fail with permission or access errors | The service credential lacks read access to billing or cost APIs, or the account scope in the config excludes the accounts that hold the spend | Read the backend log for authorization responses from the cloud provider. Verify the role or service account has the billing read permissions your cost client documents, and that the configured accounts or projects match where the resources run |
| Figures break or go blank after a Backstage upgrade | Cost plugin packages were not bumped together with the rest of the @backstage packages, so frontend and backend versions differ | Run yarn backstage-cli versions:bump, then check that all plugin packages share the same Backstage release line. Review template changes in the Backstage Upgrade Helper and rebuild both frontend and backend before testing |
| Totals differ from finance reports | Currency, amortized versus on-demand pricing, credits or refunds handled differently between the export and the finance view | Agree the cost basis with finance in writing. Confirm which currency, discount and credit treatment the cost client uses, and label the figures in Backstage so readers know what they represent |
What a Backstage cost visibility build involves and what it costs
How much effort does a Backstage cost visibility build take?
Effort depends mainly on how many cloud accounts and billing sources feed the portal, how consistently teams tag their resources, and how much custom client work the data requires. The Cost Insights plugin renders costs, but it needs a cost data client behind it that you or the partner must implement against your billing exports. Each additional account, currency, or cost source adds mapping, testing, and access setup. Ask for the effort split between discovery, client implementation, catalog linkage, and handover, so you can see where the time goes. No effort figure should be accepted until the written scope lists the accounts and sources in use.
How long does a cost visibility build take?
Duration follows the same drivers as effort: the number of billing sources, the state of tagging and ownership data, and whether the cost data client needs custom logic. A build with one account and clean tags moves faster than one that must reconcile several clouds and shared-cost allocations. Timelines are set in the written scope, which should name the milestones, the environments used for testing, and the dependencies on your teams. Confirm the duration with the partner in writing before work starts, and confirm which dependencies could move it, such as billing access approvals.
What does the internal team need to provide for cost visibility?
Most delays come from access and ownership data, not from the plugin itself. You will typically need to provide:
- Read access to billing exports or cost APIs for each cloud account, scoped to cost data only
- Confirmation of which cost tags or labels map resources to teams and products
- Catalog entities with named owners, since costs are shown against those entities
- A test environment or sample data for validating the client before production
- A named person who approves credentials and reviews the figures
Ask the partner to list these items in the scope so each one has an owner and a date.
Can a platform engineer build Backstage cost visibility alone?
A capable platform engineer who already runs Backstage can build a single-account proof of concept alone, provided they have billing read access and an established catalog. The work becomes harder when it involves several cloud accounts, allocation rules for shared resources, finance review of the numbers, and production credential handling. It also needs ongoing attention because the cost data client must be maintained as billing formats and tags change. Decide based on your team's time, familiarity with the Backstage plugin system, and how much of the catalog is already reliable. A partner can cover the parts your team does not have capacity for, under a written scope.
What are the cost components of a cost visibility build?
The engagement cost is usually made of discovery and design, client implementation, catalog and tagging work, testing, documentation, and handover. The Cost Insights plugin itself is open source and carries no license fee, but the labor to connect it to your billing data is not free. Recurring costs include your cloud billing usage, the hosting of Backstage, and the time needed to maintain the cost client when providers change their export formats. Ask each quote to separate one-time build work from any retainer for upgrades and maintenance, and to state who pays for test accounts or sandbox usage.
How do Backstage and Cost Insights upgrades affect the build?
Backstage moves every @backstage package together, so upgrades are applied through the project's version bump command and reviewed with the Backstage Upgrade Helper, which shows template changes between versions. Your custom cost data client and any plugin code must then be checked against the new APIs, which is the part that takes engineering time. Ask the partner how they test the cost pages after each bump, who owns the upgrade calendar, and whether upgrades are covered by a retainer or billed separately. Confirm the supported Backstage release line you plan to run before the build starts, since the release policy sets which lines receive fixes.
What should a quote for cost visibility include?
A useful quote lists the cloud accounts and billing sources in scope, the catalog entities that will receive cost data, and the cost data client to be built, with its tests. It should state the deliverables, the milestones, the acceptance criteria, and the internal dependencies. It should also say which items are one-time and which recur, what support is included after handover, and how changes to scope are priced. Request the assumptions in writing, especially about tagging quality and access approvals, because most cost overruns start from assumptions that were never recorded.
How DeployOpen scopes and delivers Backstage cost visibility
DeployOpen plans and builds Backstage Cost Insights for cloud cost visibility inside your own infrastructure, starting from a written scope. We pair the plugin with a cost data client you control and with catalog ownership, so spend shows up against the teams and products that run it. Engagements are fixed-scope, and ongoing support is available as a retainer.
How we scope
- We confirm which cloud accounts, billing exports and tags will feed cost data into Backstage.
- We agree which catalog entities, teams or products each cost figure should map to, in writing.
- We record which cost data client you will implement, who owns it, and where it runs.
How we build
- We install and configure the Cost Insights plugin and connect it to a cost data client we build for your environment.
- We test that costs roll up correctly by entity and that missing ownership is flagged rather than hidden.
- We document each credential the client uses, its read-only scope, and where it is stored.
How we hand over
- We deliver runbooks covering data refresh, failed cost imports, and how to add a new team or account.
- We walk your platform and finance contacts through the dashboards and the ownership gaps they reveal.
- We provide the configuration, code and test evidence in your own repositories for your team to keep.
How we support
- Ongoing support covers Backstage version bumps, plugin compatibility checks and cost client maintenance.
- Retainers can include periodic review of catalog ownership gaps so cost reports stay attributable.
- Ask any provider to confirm how cloud billing data access is granted and audited in your environment.
