Skip to content
CostReveal
Menu

Connecting Oracle Cloud to CostReveal, setup guide

The CostReveal team, , 6 minute read

Oracle Cloud Infrastructure keeps a cost report for every metered tenancy, but a tenancy total does not say which team, product or customer the spend was for. This guide covers how CostReveal reads Oracle's FOCUS cost reports with an API key it makes for you, what you need first, each setup step in the order you take it, how defined and free form tags explain spend, and how every month can be checked against Oracle's own Usage API.

What the Oracle Cloud connection reads

CostReveal reads the FOCUS cost reports Oracle keeps for every metered tenancy. FOCUS is the FinOps Foundation's open cost format, so each line carries its billed cost, service, region, resource and tags in the same shape as other clouds.

Oracle keeps those reports in its own tenancy, not yours, and lets a policy grant a group read access to them. CostReveal reads the reports and nothing else: nothing is installed in your workloads, and no secret of yours is exchanged. CostReveal signs in as a user you create, with an API key CostReveal makes for that user.

What you need

  • A metered tenancy. Oracle makes no cost reports for tenancies that are not metered.
  • An administrator who can create users, groups and policies in the root compartment. CostReveal never needs that access itself; setting it up does.
  • An owner or admin role in CostReveal.

Step by step setup

1. Start the connection to get CostReveal's key

In CostReveal, go to Connections and choose Connect Oracle Cloud. CostReveal makes an API key for this connection and shows its public half and its fingerprint. The private half never leaves CostReveal, so there is nothing to copy or store on your side.

2. Create a group and a user

In Oracle's Identity, create a group named costreveal-readers, and a user for CostReveal in that group. The user needs no password and no console access: it only ever signs in with the API key.

3. Paste CostReveal's public key on the user

Under the user's API keys, paste CostReveal's public key. Oracle then shows a fingerprint, which matches the one CostReveal displayed, so you can see it is the same key.

4. Add the policy statements

Add the policy statements CostReveal shows to a policy in the root compartment:

  • The first two let the costreveal-readers group read the cost reports, which Oracle keeps in its own tenancy.
  • The third is optional. It lets CostReveal read the Usage API, so every month can be checked against Oracle's own total.

5. Verify and connect

Enter the tenancy OCID, the user OCID and the home region, and choose Verify and connect. Only the format is checked as you type. When you verify, CostReveal signs in with its key and lists the cost reports before saving anything, and points at the field to fix if it cannot.

How often it reads, and how much history

Oracle adds cost reports every six hours, and some usage arrives up to a day late. CostReveal reads them every six hours. The first read brings in the current month and the twelve before it, as far as Oracle still holds reports for them. Where Oracle holds no older months, Connections says how far back it reached, and each read asks again. After that, each read covers the current and previous month.

Each report object is read once, and a month is read again only when Oracle has added or changed an object in it, so repeated reads stay cheap.

Connection states

Under Connections, the connection is always in one of four states:

  • Setup not finished: the details have not been verified yet.
  • Waiting for first data: the key and policy were verified, and no report has been read yet.
  • Connected: the reports were read and the latest read succeeded.
  • Needs attention: the latest read failed, for example because the key was deleted from the user. Everything already read is kept.

How Oracle Cloud spend is explained

  • Direct: the service, which Oracle reports itself.
  • Inferred: the team, feature and customer, when a tag names them. Tags are read with the project's tag keys.
  • Allocated: a share of a cost an allocation rule divides, by fixed percentages, evenly, or in proportion to what each owner's tags already explain.
  • Unknown: spend no tag or rule explains. It is shown as unknown, never spread across teams.

Defined tags and free form tags

Oracle has two kinds of tags. Free form tags are a simple key and value, and are read like tags on any other cloud. Defined tags belong to a namespace, and are keyed by it, such as Operations.CostCenter. To read a defined tag, name it that way, namespace included, in the project's tag keys.

Many Oracle tenancies already use a defined tag namespace for cost tracking. Adding its keys to the project's tag keys is usually the single biggest step toward explained spend.

Compartments and rules

Oracle organizes resources into compartments, but a compartment is not an owner on its own. Where a part of the bill belongs to one team, write an allocation rule on what the line states, such as its service, region or resource, or on a tag. A rule's result is inferred and shows the rule, so anyone can see why.

Generative AI

Oracle's Generative AI spend is shown by service. Oracle's reports name models only in text, so Oracle spend has no model in CostReveal.

How figures are checked

The ledger against attribution. Every line is recorded exactly as the report states its billed cost. A change Oracle makes to a month already read is recorded as a correction that keeps what was said before, and attribution runs again. Attribution on every dimension must add up exactly to the ledger.

The ledger against the Usage API, with the third policy statement. Each month is compared with the Usage API's own total for the same usage. While the month is open, a difference is pending, because late usage is still arriving. Once it closes, a difference is flagged as a variance, never adjusted away. Without that statement, CostReveal says only that every amount is attributed.

Getting more of Oracle spend explained

  1. Add your defined tag keys, namespace included, to the project's tag keys.
  2. Use a free form tag key you already have, such as team, owner or cost-center, which are among the defaults.
  3. Write rules for shared spend, so shared networking or platform services are allocated in the open rather than left unknown.
  4. Grant the optional Usage API statement, so every month is also checked against Oracle's own total.

Troubleshooting

  • Verify cannot sign in. Check the tenancy OCID, the user OCID and the home region, and that the fingerprint Oracle shows for the user's key matches the one CostReveal showed.
  • Verify cannot list the cost reports. Check that the first two policy statements are in a policy in the root compartment, and that the user is in the costreveal-readers group.
  • Waiting for first data on a new tenancy. Oracle makes cost reports only for metered tenancies, and adds them every six hours.
  • Defined tags are not read. Name them with their namespace, such as Operations.CostCenter, in the project's tag keys.

Removing the connection

Removing the connection under Connections deletes every figure it brought in from the project, its archived reports within a day, and CostReveal's key. Delete the key from the user in Oracle too. To stop reading without removing anything, delete CostReveal's key from the user, or delete the user: CostReveal keeps every figure already read and tells you new data has stopped.

Frequently asked questions

Does CostReveal need administrator access to my tenancy? No. It signs in as a user in the costreveal-readers group, which can read the cost reports and, if you grant it, the Usage API. Setting it up does need an administrator, to create the user, group and policy.

Who holds the private key? CostReveal. It makes the key for this connection and shows you only the public half to paste on the user, so no private key is ever copied or stored on your side.

Why does my tenancy have no cost reports? Oracle makes cost reports only for metered tenancies.

How much history is brought in? The first read brings in the current month and the twelve before it, as far as Oracle still holds reports for them. Where Oracle holds no older months, Connections says how far back it reached, and each read asks again. After that, each read covers the current and previous month.

How do I read a defined tag? Name it with its namespace, such as Operations.CostCenter, in the project's tag keys.

Is the monthly check against Oracle required? No. It needs the optional third policy statement. Without it, the connection still works, and CostReveal still checks that attribution adds up exactly to the ledger.

Keep reading

More setup guides