Allocate through YAML with CostFormation

CostFormation is CloudZero's YAML-based language for defining Dimensions. You write rules that tell CloudZero how to categorize and allocate your costs, then publish them to see the results across the platform. CostFormation supports the same rule types as Dimension Studio, with the added flexibility of managing Dimensions as code and automating changes through the API.

💡
Prefer a visual editor? Most users build Dimensions in Dimension Studio with no code required. Dimension Studio also includes a built-in Code Editor for YAML when you need it.

ℹ️
Permissions: To create or edit Dimensions, you must have a role with the Modify Dimension Definitions permission.

Your first Dimension in YAML

This example creates an Environment Dimension that automatically creates elements from your environment tags. You can follow these steps in the Dimension Studio Code Editor, or use the VS Code Extension if you prefer to work in your own editor.

In CloudZero, select Dimension Studio from the left navigation.
Click the Code Editor tab.
Add the following YAML to your definitions file, inside the Dimensions: block:

Dimensions:
  Environment:
    Name: Environment
    Rules:
      - Type: GroupBy
        Source: Tag:Environment
        Transforms:
          - Type: Normalize

Select Publish.

Replace Tag:Environment with whatever tag key your organization uses for environments (for example, Tag:Env, Tag:env, or Tag:environment). CloudZero creates an element for every unique value in that tag. The Normalize transform converts values to lowercase and replaces special characters with dashes, so PRODUCTION, Production, and production all become a single production element instead of three separate ones. Changes are retroactive, applied across your full cost history, and begin processing within a few minutes.

From here, you can add Group rules above the GroupBy to normalize messy values (for example, flattening prd, PROD, and production into a single Production element). See How to Build a Dimension for the iterative workflow.

How to publish CostFormation definitions

CostFormation definitions are stored in a single YAML file per namespace. You can edit and publish this file in three ways:

Method	How it works
Dimension Studio Code Editor	Select a Dimension in Dimension Studio, click the Code Editor tab, edit the YAML, and select Publish.
VS Code Extension	Open your definitions file in VS Code with the CloudZero extension installed. The extension provides autocompletion, inline validation, and one-click publishing.
REST API	Download, modify, and upload your definitions file programmatically. Useful for CI/CD pipelines and automated workflows.

All three methods produce the same result. Choose whichever fits your workflow.

Going further

CostFormation Reference: Every condition, source ID, and transform available in CostFormation.
CostFormation Templates: Copy-and-adapt YAML patterns for common use cases.
Default Dimension Definitions: The built-in Dimensions CloudZero provides by default.
Splitting Shared Costs: How to split shared infrastructure costs across teams or products.

ℹ️
Have questions or feedback? Reach out to your account manager.