Author CostFormation in Python

CloudZero organizes your cloud and AI costs into categories called Dimensions, using CostFormation, CloudZero's YAML-based cost allocation language. This page covers defining Dimensions as Python classes instead of hand-writing YAML, then generating that YAML and publishing it to CloudZero. Authoring in Python is a good fit when you want type checking, tests, code review, or the ability to generate many Dimensions programmatically. The output is the same CostFormation YAML you would write by hand. For syntax details, see the CostFormation Reference.

The library is open source: cloudzero-costformation on PyPI and source on GitHub.

Install

pip install cloudzero-costformation

Requires Python 3.10+.

Step 1: Author your Dimensions in Python

Define each Dimension as a class. Core cloud-provider, Kubernetes, and CloudZero-managed Dimensions are importable and used as sources or references:

from costformation import CostFormation, Service, GroupDimension, GroupRule, Equals

class MyServices(GroupDimension):
    name = 'My Services'
    source = Service()
    default_value = 'Other'
    rules = [
        GroupRule(name='Compute', condition=Equals(['AmazonEC2', 'AWSLambda', 'AmazonECS'])),
        GroupRule(name='Storage', condition=Equals(['AmazonS3'])),
    ]

Match values against the service codes CloudZero uses, such as AmazonEC2, AWSLambda, and AmazonS3. To group by friendly service names instead, use CZ:Defined:ServiceDisplay as the source. For every operator, transform, rule type, and allocation option, see the CostFormation Reference. For ready-made patterns, see CostFormation Templates.

Step 2: Generate the YAML

Add a print(...) to the bottom of the file with your class (my_costformation.py) to serialize your Dimensions to CostFormation YAML:

print(CostFormation([MyServices()]).to_yaml())

Output:

Dimensions:
  MyServices:
    Name: My Services
    Source: Service
    Rules:
    - Type: Group
      Name: Compute
      Conditions:
      - Equals:
        - AmazonEC2
        - AWSLambda
        - AmazonECS
    - Type: Group
      Name: Storage
      Conditions:
      - Equals:
        - AmazonS3
    DefaultValue: Other

Save it to a file so you can publish it:

python my_costformation.py > my-costformation.yaml

Step 3: Publish it to CloudZero

The generated YAML is ordinary CostFormation, so you publish it exactly as you would any hand-written definition. Publishing requires an API key or user with the Modify Dimension Definitions permission (see API authorization scopes); a scoped API key without it fails at publish time. Use any of the three self-serve options below, which are the same publish paths described in Allocate through YAML with CostFormation.

Option A: CloudZero API (best for automation and CI/CD)

POST the YAML to the CostFormation definitions endpoint, authenticated with your CloudZero API key in the Authorization header:

curl -X POST "https://api.cloudzero.com/v2/costformation/definition/versions" \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: text/plain" \
  --data-binary @my-costformation.yaml

• Add ?validate_only=true to check the definition without saving or publishing it.
• Add ?namespace=<name> to publish to a specific namespace when you split your CostFormation across multiple files.

See createCostFormationDefinitionVersion in the API reference.

In CI/CD, keep your definition in version control and let a pipeline validate it, then publish on merge, using an API key from an environment variable:

python my_costformation.py > my-costformation.yaml
# Validate first so the pipeline fails on an invalid definition
curl -fsS -X POST "https://api.cloudzero.com/v2/costformation/definition/versions?validate_only=true" \
  -H "Authorization: $CLOUDZERO_API_KEY" -H "Content-Type: text/plain" --data-binary @my-costformation.yaml
# Publish
curl -fsS -X POST "https://api.cloudzero.com/v2/costformation/definition/versions" \
  -H "Authorization: $CLOUDZERO_API_KEY" -H "Content-Type: text/plain" --data-binary @my-costformation.yaml

Option B: CloudZero app

Paste the generated YAML into the CostFormation editor in the CloudZero app and publish it there. See How to Build a Dimension.

Option C: VS Code extension

If you use the CloudZero CostFormation Toolkit, run CloudZero: Download CostFormation for the target namespace, which links the local file to CloudZero. Replace the file's contents with your generated YAML, then run CloudZero: Publish CostFormation.

What to expect

After you publish, the new version becomes your active CostFormation and CloudZero begins allocating costs with it. CloudZero reprocesses your costs, and your updated allocations appear across the platform. Reprocessing time varies with the size of your cost history. If you published with ?validate_only=true, nothing changes until you publish without it.

Why author in Python?

• Type checking and IDE autocomplete on every Dimension, operator, and transform.
• Tests. Assert that your Dimensions produce the YAML you expect.
• Reuse. Generate families of similar Dimensions in a loop instead of copy-pasting YAML.
• Code review and version control for your cost-allocation model.

See also

• CostFormation Reference
• CostFormation Templates
• How to Build a Dimension
• VS Code Extension