CostFormation Reference

This page is the complete YAML syntax reference for CostFormation, CloudZero's cost allocation language. Use it to look up conditions, source IDs, transforms, properties, and allocation syntax. For concepts, see How to Build a Dimension. For copy-paste templates, see CostFormation Templates.

Key terms:

• Dimension: A category that organizes cloud costs into groups (for example, Environment, Team, Product).
• Element: A value within a Dimension (for example, Production and Development are elements of an Environment Dimension).
• Source: The data attribute CloudZero checks when evaluating rules and conditions (for example, Account, Tag:Environment, K8s:Namespace). See Source IDs for all available sources.
• Rule: Logic that assigns costs to elements. Types: Group (explicit names), GroupBy (automatic from source values), Metadata (substring matching).
• Condition: A comparison applied to a source value to determine if a cost matches a rule (for example, Equals: production).

Definition file structure

All Dimension definitions live in a single YAML file per namespace. The file starts with the Dimensions root key:

Dimensions:
  Environment:
    Name: Environment
    Source: Account
    Rules:
      - Type: Group
        Name: Production
        Conditions:
          - Equals: 012345678901

  Team:
    Name: Team
    Source: Tag:Team
    Rules:
      - Type: GroupBy

Each Dimension has a unique ID (like Environment or Team) and a set of properties. You can define as many Dimensions as you need in a single file.

Dimension properties

Sources and inheritance

Sources can be specified at three levels: the Dimension root, a rule, or a condition. Each level inherits from its parent unless it specifies its own source.

Environment:
  Name: Environment
  Source: Account                   # Default source for all rules
  Rules:
    - Type: Group
      Name: Production
      Conditions:
        - Equals: 012345678901      # Inherits Source: Account
        - Source: Tag:Environment    # Overrides with its own source
          Equals: production
    - Type: Group
      Name: Cloud Management
      Source: CZ:Defined:Category    # Overrides at the rule level
      Conditions:
        - Equals: Cloud Management  # Inherits Source: CZ:Defined:Category

When a rule or condition specifies its own Source, all source properties are overridden as a set (including Transforms and CoalesceSources). Inherited transforms do not carry into the override.

Multiple sources and CoalesceSources

Specify multiple sources using the Sources property (plural). By default, conditions are applied as an OR across all sources. Set CoalesceSources: true to use the first source that has a value (checked in the order listed) instead.

Sources:
  - Tag:Env
  - Tag:Environment
  - Tag:environment
CoalesceSources: true

Rules

Group rules

Group rules create elements with explicit names. A cost is placed in the element if any condition evaluates to true.

Rules:
  - Type: Group
    Name: Production
    Conditions:
      - Equals:
          - 012345678901
          - 109876543210

Multiple rules can share the same element name; costs matching any of them are grouped together.

GroupBy rules and Format strings

GroupBy rules create elements automatically from source values. Format strings control element naming when using multiple sources.

Rules:
  - Type: GroupBy
    Sources:
      - Service
      - Region
    Format: '{0} -- {1}'

Format placeholders use zero-based indexes: {0} is the first source, {1} is the second. If Format is omitted, source values are concatenated with a space. When sources are coalesced, use a single placeholder ({0}).

Format indexes are zero-based ({0}, {1}). This is different from the Split transform, where Index is 1-based.

Metadata rules

Metadata rules match substrings within source values and create elements from the matched values.

Rules:
  - Type: Metadata
    Format: 'Service: {0}'
    Sources:
      - Tag:Name
      - CZ:Defined:ResourceSummaryDisplay
    Conditions:
      - Source: Account
        Equals: 012345678901
    Values:
      - -Web-:
          - -UI-
          - Frontend
      - Order-Processing
      - Order-Staging:
          - WebOrderStaging
      - Order-Fulfillment

Metadata value requirements:

• Values can only contain letters, numbers, and dashes (-). Other characters cause a validation failure.
• Metadata matching automatically normalizes source values by converting special characters to dashes and comparing case-insensitively. This is built into Metadata rule behavior and is separate from the Normalize transform (which you would use with Group or GroupBy rules).
• Element names preserve the case of the specified metadata value.
• Leading and trailing dashes are used for matching but removed from element names (-Web- matches the substring but creates an element named Web).

Alternatives: List alternatives after a metadata value to handle inconsistent naming. If any alternative matches, costs are grouped under the primary value. In the example above, costs containing -UI- or Frontend are grouped with -Web-.

Conditions

Conditions are listed under the Conditions: key within a rule. Each item in the list is evaluated independently, and the results are combined as an OR: if any single condition is true, the cost matches the rule. To require all conditions to be true, wrap them in an And block. Each condition can optionally specify its own source.

And

All conditions must be true.

- And:
    - <Condition 1>
    - <Condition 2>

Or

Any condition must be true.

- Or:
    - <Condition 1>
    - <Condition 2>

Not

Evaluates conditions as an OR, then negates the result. True only if all conditions are false.

- Not:
    - <Condition 1>
    - <Condition 2>

BeginsWith

Source value starts with any of the specified strings.

- BeginsWith: <Value>

- BeginsWith:
    - <Value 1>
    - <Value 2>

Contains

Source value includes any of the specified strings.

- Contains: <Value>

- Contains:
    - <Value 1>
    - <Value 2>

EndsWith

Source value ends with any of the specified strings.

- EndsWith: <Value>

- EndsWith:
    - <Value 1>
    - <Value 2>

Equals

Source value exactly matches any of the specified strings.

- Equals: <Value>

- Equals:
    - <Value 1>
    - <Value 2>

HasValue

Checks whether a source has any value or is null.

- HasValue: <True|False>

If True, the condition is true when the source has a value. If False, the condition is true when the source does not have a value.

Matches

Source value matches any of the specified regular expressions. Uses Snowflake's regex syntax (passthrough to REGEXP_LIKE). For details, see the Snowflake regex documentation.

- Matches: <RegEx>

- Matches:
    - <RegEx 1>
    - <RegEx 2>

Example: Matches: ".*(prod|production).*" evaluates to true for my-prod-server, production-db, and app-production-us but not for staging-server.

Before

Source value comes before the provided value alphabetically.

- Before: <value>

BeforeOrEquals

Source value comes before the provided value alphabetically or is the same.

- BeforeOrEquals: <value>

After

Source value comes after the provided value alphabetically.

- After: <value>

AfterOrEquals

Source value comes after the provided value alphabetically or is the same.

- AfterOrEquals: <value>

ForDateRange

Cost data with usage between the specified dates (inclusive). Recommended format: YYYY-MM-DD.

- ForDateRange:
    From: <Date>
    Until: <Date>

Example: From: 2025-01-01, Until: 2025-03-31 matches costs with usage in Q1 2025.

Transforms

Transforms normalize source values before rules are evaluated. They are applied in order: the output of the first becomes the input of the second.

Transforms can be set at three levels: the Dimension root (applies to all rules), a rule (applies to all conditions in that rule), or a condition (applies to that condition only). Each level inherits from its parent unless it specifies its own Source, which overrides all source properties including transforms. See Sources and inheritance.

Lower

Converts all letters to lowercase.

- Type: Lower

Example: ProductionResource 1 → productionresource 1

Upper

Converts all letters to uppercase.

- Type: Upper

Example: the cost types → THE COST TYPES

Title

Converts to title case (first letter of each word capitalized).

- Type: Title

Example: the cost types → The Cost Types

Trim

Removes leading and trailing whitespace.

- Type: Trim

Example: " the cost types " → "the cost types"

Clean

Removes leading and trailing whitespace. Converts .,/#!$%^&*;:=_~()\' and spaces to dashes.

- Type: Clean

Example: " The:Cost!Types " → "The-Cost-Types"

Normalize

Removes leading and trailing whitespace, converts to lowercase, converts .,/#!$%^&*;:=_~()\' and spaces to dashes.

- Type: Normalize

Example: Production/Resources#4561 → production-resources-4561

Split

Splits the source value by a delimiter and extracts the substring at the specified index. Index is 1-based.

- Type: Split
  Delimiter: <delimiter>
  Index: <1-based index>

Example: eu-west-1 with Delimiter: '-', Index: 1 → eu

Lookup

Parses the source value as JSON and extracts a field. Specify the field using either Key or Path (not both). Use Key for top-level fields and Path for nested objects or arrays. If the source value is not valid JSON, or the specified field does not exist, the result is null.

Key treats the value as a literal field name. Use Key for most cases, especially when field names contain special characters like colons (:) or dots (.).

- Type: Lookup
  Key: <field name>

Example: {"user:github_repo": "my-app", "region": "us-east-1"} with Key: user:github_repo → my-app

Example: {"owner": "platform-team", "env": "prod"} with Key: owner → platform-team

Path uses dot-notation to traverse nested JSON objects. Characters like . and : are interpreted as path separators. Supports nested paths (metadata.team) and array indexing (items[0].name).

- Type: Lookup
  Path: <dot-notation path>

Example: {"metadata": {"team": "billing", "region": "us-east-1"}} with Path: metadata.team → billing

Source IDs

The following tables list all available source IDs for use in CostFormation definitions.

Core Cloud Provider Dimensions

Additional Cloud Provider Dimensions

Tag Dimensions

Kubernetes Dimensions

K8s Label and annotation syntax:

Custom Dimensions

Allocation syntax

For allocation concepts (when to use each method, how proportional allocation works), see Splitting Shared Costs. To configure allocation visually, see Create an Allocation Dimension.

CloudZero enforces limits on the number of streams and combined allocation sources per dimension definition. If you hit a validation error related to these limits, contact your account manager to discuss adjustments.

AllocateByStreams

<DimensionId>:
  Type: Allocation
  AllocateByStreams:
    Streams:
      - <stream-name>

Rate-based allocation

Rate-based allocation gives consuming teams a stable, predictable cost per unit. Unlike proportional allocation, where the effective cost per unit changes whenever the total bill changes, rate-based allocation locks in a fixed price per unit of usage.

This is useful for internal chargeback when your organization has agreed on a fixed transfer price. For example, finance sets the rate for a CPU hour at $1.00. Consuming teams budget against that rate regardless of what the infrastructure actually costs. The platform team sees the surplus or deficit in the DefaultElement, which tells them whether their internal pricing is sustainable.

For example, a shared compute cluster costs $1,000. Two teams use it:

If total usage exceeds the actual spend, the default element receives a negative value to reconcile.

Your telemetry data only needs to contain raw usage, for example CPU hours, API calls, or gigabytes stored. You do not need to convert it to dollar amounts.

<DimensionId>:
  Type: Allocation
  AllocateByStreams:
    Rate:
      Type: Fixed
      Value: 1.00
      DefaultElement: 'Unallocated Cost'
    Streams:
      - cpu-hours-by-team

AllocateByRules

<DimensionId>:
  Type: Allocation
  AllocateByRules:
    AllocationMethod: <Even | Proportional>
    SpendToAllocate:
      Conditions:
        - <conditions>
    AcrossElements:
      Rules:
        - <rules>
    ForEachElementOf:          # Optional, proportional only
      Source: <Dimension>
      Values:
        - <value>

Even allocation example

Even allocation splits costs equally across all elements:

SharedInfra:
  Type: Allocation
  AllocateByRules:
    AllocationMethod: Even
    SpendToAllocate:
      Conditions:
        - Source: Account
          Equals: '123456789012'
    AcrossElements:
      Rules:
        - Type: GroupBy
          Source: User:Defined:Team

Proportional cost type and granularity

When you only need the default granularity and cost type, use the short form: AllocationMethod: Proportional. To customize granularity or cost type, use the expanded form below.

Default cost type: RealCost. Default granularity: UsageDaily.

AllocateByRules:
  AllocationMethod:
    Method: Proportional
    Granularity: <UsageDaily | UsageMonthly | BillingPeriod>
    CostType: <cost type>

Supported cost types: BilledCost, DiscountedCost, DiscountedAmortizedCost, AmortizedCost, InvoicedAmortizedCost, RealCost (default), OnDemandCost, UsageAmount.

ElementCutoff

Filters low-value elements from allocation Dimensions. For conceptual details, see Splitting Shared Costs.

ElementCutoff:
  ThresholdPercent: 5      # Required: 0-100 exclusive
  Name: 'Other'            # Optional: bucket name for grouped elements

Supported allocation types:

Combining dedicated and shared costs

Use a GroupBy rule referencing an Allocation Dimension to merge allocated costs into a parent Dimension alongside dedicated costs:

Product:
  Name: Product
  DefaultValue: Other
  Rules:
    - Type: Group
      Name: Mobile
      Conditions:
        - Source: Tag:Application
          Equals: mobile
    - Type: Group
      Name: Web
      Conditions:
        - Source: Tag:Application
          Equals: web
    - Type: GroupBy
      Source: User:Defined:SharedCostAllocation

Group rules match dedicated costs (tagged per application). The trailing GroupBy references an Allocation Dimension (User:Defined:SharedCostAllocation) to pull in shared costs. If the Allocation Dimension uses the same element names (Mobile, Web), costs are combined automatically. This works for both telemetry-based and proportional Allocation Dimensions.

Overriding default Dimensions

CloudZero provides built-in Dimensions like Elasticity and Payment Option. To replace a default with your own definition, use the Override property:

Elasticity:
  Name: Elasticity
  Override: CZ:Defined:Elasticity
  Rules:
    - Type: Group
      Name: Variable
      Conditions:
        - Source: CZ:Defined:Category
          Equals: Compute

The Override property references the ID of the default Dimension you are replacing. Without it, the definition fails validation because the name conflicts with the built-in Dimension.

Other Dimensions that reference the overridden default are automatically updated to use your custom definition.

Restrictions:

• Only default Dimensions can be overridden. You cannot override a Custom Dimension from the User:Defined namespace.
• A default Dimension can only be overridden by one Custom Dimension.
• All Dimension names must be unique, unless a Custom Dimension is overriding the default Dimension with the same name.
• The ID and name of the overriding Custom Dimension do not need to match the overridden default.