1. Kion Success Center
  2. Cloud Accounts
  3. Custom Accounts

Custom Accounts / Custom Billing Sources

Follow

Last updated

Bring Your Own Data into Kion. With Custom Accounts, you can ingest and normalize non‑CSP billing data, meaning you can bring in SaaS spend, on‑prem data center cost, or any internal data relevant to your organization alongside AWS, Azure, GCP, and OCI. Map external datasets to Kion’s financial model, attribute spend to projects and OUs, and roll it all up in reports, dashboards, budgets, and enforcements.

Getting Started

Below are the considerations and requirements for the file formatting and ingest behavior for custom billing sources. Please review these steps before uploading data and adding in a custom billing source.

Prerequisites

  • You must be using Kion v3.14.0 or newer in order to use this feature.
    • Support for Azure Storage Accounts is available in Kion 3.16.4 and later.
  • Custom Cloud Provider must be enabled in Kion settings. To enable this, navigate to Settings > System Settings > Cloud Provider Settings. On this page, enable Custom Cloud Provider and select Update Settings.
  • A compatible storage location:
    • AWS S3 bucket accessible by Kion through the Kion service role in AWS.
    • Azure Storage (Blob) Container accessible by Kion through an existing Azure Billing Source's App Registration or a newly created App Registration within a tenant.
  • Reports must be formatted to follow the FOCUS specification for proper ingest.
    • Kion requires the data entered into FOCUS columns to align with the spec. You can review the accepted values for each column in the FOCUS 1.2 Spec. You can also review all columns here - FOCUS column library.
    • Although the values in required columns must match the FOCUS spec (ex: you can’t have a blank in a required column), Kion will not require data in all columns in order to properly report financials.
      • For example, Region ID and Region Name are conditional columns in the FOCUS spec. However, if reporting by region for your data set is not applicable or relevant, you can mark those columns NULL or Blank because they aren’t required.
    • Below are required columns in the FOCUS spec:
      • BilledCost – charge basis for invoicing.
      • BillingAccountID – provider-assigned billing account identifier.
      • BillingCurrency – currency of the billed charge.
      • BillingPeriodEnd – exclusive end date/time of the billing period.
      • BillingPeriodStart – inclusive start date/time of the billing period.
      • ChargeCategory – type of charge (usage, adjustment, tax, etc.).
      • ChargePeriodEnd – exclusive end date/time of the charge period.
      • ChargePeriodStart – inclusive start date/time of the charge period.
      • ContractedCost – contracted cost (unit price × quantity).
      • EffectiveCost – effective cost after discounts/amortization.
      • InvoiceIssuer – name of the invoicing entity.
      • ListCost – list cost (list unit price × pricing quantity).
      • ProviderName – entity making the resource/service available.
      • PublisherName – entity producing the resource/service.
      • ServiceCategory – high-level service classification.
      • ServiceName – display name of the purchased service.
    • Although these columns are required according to the spec, Kion can be flexible with inputs into these columns. For example, if you only need to report on BilledCost and ListCost isn’t relevant for you, you can put ListCost as 0 for every row or make Billed and List match.
    • A sample file of FOCUS data is attached and available at the bottom of this article.

General Considerations

Data Storage Structure

S3 Bucket Storage Location

Data must be organized in a date-based folder structure within the S3 bucket:

  • <bucket-name>/<date-code>/
  • Date codes follow the format YYYYMM (e.g., 202501, 202502).
  • Each folder should contain the reports for that month only.

Azure Storage Container Storage Location

Data must be organized in a date-based folder structure within an Azure Storage Blob Container:

  • <container>[/<prefix>]/<date-code>/
    • The /<prefix> is an optional, but supported path element.
  • Date Codes follow the format YYYYMM (e.g., 202501, 202502).
  • Each folder should contain the reports for that month only.

File Naming and Formats

  • Files must be in CSV, GZIP, or ZIP format.
  • File prefix names are flexible, but we recommend using a consistent prefix to ensure the correct files are uploaded.
  • Large reports can be split into multiple files. The recommended naming convention is:
    • report-202501p1.csv
    • report-202501p2.csv

Best Practice Recommendations

  • Use consistent file prefixes.
  • Replace all files during updates to avoid duplication.
  • Delete old files before uploading new ones to minimize processing issues.

File Replacement and Updates

When updating or replacing data:

  • Always replace all files within the folder for that month.
    • Kion processes all files in the folder, so leaving old files in place may result in duplicate spend data.
    • As an example, for customers who are looking to build a scheduled job that ingests new daily costs every evening, you may create a report-202508.csv on 8/1/2025. On 8/2/2025, the recommendation would be to replace the existing file and include BOTH 8/1 and 8/2 cost data in the file
  • If you mix current and historical data in the same folder, it will lead to duplicate spend for that month.
    • Deleted spend is not deleted from Kion without reprocessing or replacing data, as noted in "Other Considerations".
  • To avoid this, we recommend:
    • Deleting all files in the folder before uploading new ones (not required, but safer).
    • Ensuring only the latest intended data is present in the storage location.

Kion ingests and processes all files based on the new timestamp each time files are replaced.

File Splitting Options

You can choose how to split your files depending on your needs:

  • Single file per month – simplest option, one file per folder.
    • As an example, report-202508.csv would contain all August spend. If updates need to be made, you would delete and replace the previous file.
  • Multiple files per month – if files are too large, or if you prefer to split by day.
    • Each part must follow the naming convention (ex: report-202501p1.csv, report-202501p2.csv).
    • Users can use this method to upload large files, or files segmented by day/week. However, we do recommend a single file per month if possible for ease of file management.

Other Considerations

  • Once a file is ingested, deleting that file will not remove it from Kion. To remove incorrect data, one of the following actions can be taken depending on the use case:
    • If a single month needs to be updated, upload new data to the folder to kick off a new ingest
    • If you want to no longer report on historical months, change the account (or billing source) start date to ignore historical months with stale/incorrect data
    • If the data for all months needs to be deleted, please delete the billing source entirely
  • Account numbers from the FOCUS data, or account numbers manually inputted, can not be duplicated. This means you can not have a Kion account numbered 123xxxx and a new custom account with 123xxxx.

Deployment

Preparing an Azure Storage Container Storage Location

If choosing Azure Storage Account Storage Location for your custom account data, you must ensure that Kion can access this data. You have options for this access:

  • Access via Existing Azure Billing Source Service Principal (Recommended)
    • This method allows you to use the Service Principal of an existing Kion Billing Source to access your Azure Storage Container. This means fewer credentials to maintain and faster configuration.
    • Your existing Service Principal must be granted at least Storage Blob Data Reader access on your Azure Storage Account. Owner is not a sufficient permission to read stored data.
  • Access via New Service Principal (Tenant Credentials)
    • This method allows you to create a new Service Principal primarily when the data you need to read does not exist within a tenant already managed as a Kion Billing Source today.
    • Follow the steps below to deploy a new Service Principal.

Deploying a New Azure Storage Principal and Assigning Access

If you've elected the Access via New Service Principal path above, follow these steps within the Azure tenant where you need to establish access:

  1. Log in to the Azure Portal.
  2. Search for and select the service: Microsoft Entra ID.
  3. Navigate to Manage > App Registrations.
  4. Select new registration.
  5. Enter a name for your new registration: Kion Storage Account and select Register.
  6. Back on the list of App registrations, choose All applications and locate the entry you just created. Click on the name of the entry to bring up the app registration.
  7. Record the Application (client) ID from the overview somewhere you will be able to reference it later.
  8. Select Manage > Certificates & secrets.
  9. In the Client secrets section, click New client secret.
  10. Select an expiration period for the client secret and choose Add.
  11. Copy the Value next to your client secret from the client secrets table and store it securely.
  12. Navigate to Storage accounts > [Data storage account].
  13. In the left menu, select Access Control (IAM).
  14. On the IAM screen, select Add > Add role assignment
  15. Search for and select Storage Blob Data Reader and choose Next.
  16. For Assign access to, select User, group, or service principal.
  17. Click Select members.
  18. Search for and select the app registration you created in the previous steps. It will be listed as an Application rather than a regular user.
  19. Click Review and Assign.
  20. Click Review and Assign again.

Your Service Principal is now ready for use in the next set of steps.

Preparing an S3 Bucket Storage Location

If choosing an AWS S3 Bucket Storage Location for your custom account data, you must ensure that Kion can access this data.

Download and apply billing-role-one-bucket-read-only.json to provide read-only access to the S3 bucket in the AWS account where the S3 bucket lives. With that role in place, you should be able to access your data.

NOTE: If Kion is installed in AWS Commercial and you must access a bucket in AWS GovCloud, you must configure partition access first using only the steps in Section 4 found here. In this case, you will trust your Kion GovCloud partition account number, not your installation account number for your CloudFormation template.

Creating a Custom Billing Source using AWS S3 Bucket

This feature is available in Kion v3.14.0 and newer only.

  1. Within Kion, Navigate to Accounts > Billing Sources > “Add New +” in the top right of the page
  2. Select Custom as your account type in the drop-down
    1. NOTE: If you do not see Custom as an account type, this means that Custom Cloud Provider has not been enabled in Kion. Please see the instructions in the prerequisites section of this document to enable this setting before continuing.
  3. (For 3.16.4 and newer) Select your Data Source as AWS S3 Bucket.
  4. Enter the AWS Account where the data will be stored
    1. To create a custom Billing Source, you must first have an accessible AWS account.
  5. Provide a name for this Custom Billing Source (ex: MongoDB Atlas Billing)
  6. Provide the region where the data will be stored
  7. Prefix for the report name Kion should look for is optional. If no prefix is provided, Kion will default to look for “bucket-name/YYYYMM”.
  8. Provide an IAM role with a trust policy for Billing Bucket Access Role. This is optional and only necessary if the role is different than “cloudtamer-service-role”
  9. Select a Billing Start Date - this indicates how far back you want Kion to historically ingest files.
  10. Click Test Billing Connection - This will confirm if Kion can access the expected files.
    1. If 0 files are found and data has been uploaded to the storage location, please verify the details on the billing source and ensure the storage location folder and file names are also correct.
    2. If no files have been uploaded yet, you can Skip Billing Source Validation, but we recommend confirming the connection once data is available.
  11. Create Billing Source to finish your configuration. Once complete, you can proceed to the Creating a Custom Account section to begin adding new accounts. It may take some time to load your new data.

Creating a Custom Billing Source Using Azure Storage Container

This feature is available in Kion v3.16.4 and newer only.

  1. Within Kion, Navigate to Accounts > Billing Sources > “Add New +” in the top right of the page
  2. Select Custom as your account type in the drop-down
    1. NOTE: If you do not see Custom as an account type, this means that Custom Cloud Provider has not been enabled in Kion. Please see the instructions in the prerequisites section of this document to enable this setting before continuing.
  3. Select your Data Source as Azure Storage Container.
  4. Select how you will access the storage account based on the method you chose above.
    1. For an Existing Billing Source, select the Azure Billing Source that you will use to access the Azure Storage Account.
    2. For Tenant Credentials:
      1. Select your Azure environment as your Tenant Type.
      2. Enter the domain for your Tenant. This field is case sensitive so ensure that this matches your environment exactly.
      3. Enter the Application ID and Client Secret that you created in the previous steps.
  5. Regardless of the method you chose above, ensure that you choose Test Tenant Credentials at this step to make sure that we can access your Azure Tenant. A failure here means:
    1. For an Existing Billing Source, your Billing Source is likely experiencing a failure and you must validate the credentials.
    2. For Tenant Credentials:
      1. Double-check that you've not included any unwanted characters in either the Application ID or the Client Secret.
      2. If these credentials are new, wait about 5 minutes and try again. Azure may be experiencing a delay in propagating the access you've defined.
      3. If these still do not work, try issuing the Client Secret again.
      4. If you continue to experience issues, please reach out to support@kion.io.
  6. Provide a name for this Custom Billing Source (ex: MongoDB Atlas Billing)
  7. Enter the endpoint address for your Azure Storage Account in the Storage Primary Endpoint field.
  8. Enter the name of your Storage Container.
  9. Enter a Storage Prefix (the path to your dated folders) if required.
  10. Select a Billing Start Date - this indicates how far back you want Kion to historically ingest files.
  11. Choose Test Billing Connection at this step to make sure that we can access your billing data. A failure here may mean:
    1. The Service Principal does not have access to your Azure Storage Account.
    2. The data in your Azure Storage Account is in the wrong location against the settings you provided.
  12. Create Billing Source to finish your configuration. Once complete, you can proceed to the Creating a Custom Account section to begin adding new accounts. It may take some time to load your new data.

Creating a Custom Account

  1. Navigate to Accounts > “Add +” > Connect existing Accounts
    • Because a custom billing source should already be created, the account numbers found in the FOCUS formatted file will be detected by Kion and ready to be added as a Kion account
  2. Select Custom Provider
  3. Select the Billing Source of the account you want to add
  4. Select the account you want to add to Kion
  5. Provide a name for the account in Kion - this is a Kion-only name and it’s recommended to name custom accounts in a way that’s easy to understand the account’s purpose (ex: App Team MongoDB)
    • You can provide an optional Kion alias for easier identification below this input
  6. Assign Account - either add this account to Kion’s cache for future management or add to an existing project to get started managing the account right away.
    • If adding to a project, you will select the project and give the account a start date. The start date for custom accounts should likely align to when you start providing custom data for Kion to ingest.
  7. Connect the account
    • To edit any details on the account, navigate to the account, click the 3-dot menu in the top right, and then edit.

FAQ:

  • If a row in my dataset has a ChargePeriod that spans across a day boundary, which day will the charge be attributed to? 

    a. The charge will be attributed to the ChargePeriodStart value. 

  • Does Kion currently support converting any tools to FOCUS for use as a custom account?

    a. Yes, Kion currently supports a number of tools with customized converters developed internally. Below is list of some that are available but new ones are added frequently as customer demand arises:

    • MongoDB Atlas
    • Databricks
    • Anthropic (Claude)
    • OpenAI
    • VMware On-prem
    • OpenCost
    • Azure CSP
  • I don't see "Custom" available as an option when adding a new Billing Source. Is a configuration change required?
    • You must be using Kion v3.14.0 or newer and you must enable Custom Cloud Provider in Kion. Please see the Prerequisites section of this document for instructions on enabling this.
  • I don't see "Azure Storage Container" available as an option when adding a new Billing Source.
    • You must be using Kion v3.16.4 or newer.