Pool Schema

Complete field reference for pool configuration files. For conceptual overview, see pool concepts.

IDE Integration

Add this directive to the top of your YAML file for autocomplete and validation:

# yaml-language-server: $schema=https://tracemill.dev/schemas/pool.schema.json

Properties

Field	Type	Required	Description
`type`	`"pool"`	Yes	Discriminator. Optional when inline in a job's `pools` array, but required in standalone pool files.
`id`	string	Yes	Pool identifier. Dots are not allowed because `pool.<id>.<field>` splits on dots. Pattern: `^[a-zA-Z][a-zA-Z0-9_-]*$`
`description`	string	No	Free-text description.
`sampling`	object	No	Sampling strategy. See sampling.

Exactly one of ip_range, string_list, or csv must be specified.

Sampling

Field	Type	Required	Description
`mode`	`"random"` \| `"round_robin"`	No	Default: `random`.
`seed`	integer	No	Seed for deterministic draws. When set, results are reproducible across runs.

random draws a uniformly random entry on each Get(). round_robin cycles through entries sequentially.

Pool Kinds

`ip_range`

Generates a pool of IP addresses from CIDR ranges.

Field	Type	Required	Description
`cidrs`	string[]	Yes	CIDR strings to include. Min 1.
`exclude`	string[]	No	CIDR strings to exclude from the pool.
`count`	integer	No	Max IPs to store. Min: 1.

Without count, all IPs from the CIDRs are enumerated. If the total exceeds 100,000, a 100K default is used with a warning. Max 1,048,576 IPs (2^20) when fully enumerated.

With count, rejection sampling draws that many unique IPs — no full enumeration occurs, so CIDRs of any size (up to 64 host bits) are supported.

ip_range:
  cidrs:
    - 198.51.100.0/24
    - 203.0.113.0/25
  exclude:
    - 198.51.100.1/32
  count: 1000

`string_list`

A pool of literal string values.

Field	Type	Required	Description
`values`	string[]	Yes	List of strings. Min 1.

string_list:
  values:
    - admin
    - root
    - deployer

`csv`

Loads rows from a CSV file. Each Get() returns a map[string]any, so individual columns are accessible via dot-path expressions like pool.users.email.

Field	Type	Required	Description
`path`	string	Yes	Path to the CSV file. Relative paths are resolved from the pool YAML file's directory.
`columns`	string[]	No	Columns to include. If omitted, all columns are loaded.

csv:
  path: ./data/users.csv
  columns:
    - email
    - username

Accessing fields in job bindings:

bindings:
  user_email: pool.users.email     # extract one column
  user: pool.users                 # full row as a map