Compose Configuration

The compose configuration file defines the desired state of an Arctic cluster in YAML format. This page documents the complete schema, field definitions, and validation rules.

File Format

Configuration files use YAML format with schema version v1. The file can be named anything, but cluster.yaml is the convention.

Configuration Schema

Root Structure

Field	Type	Required	Description
`version`	string	Yes	Schema version (must be `v1`)
`license`	string	No	Relative path to license file from config location
`peers`	array	Yes	List of peer configurations
`services`	array	No	List of service configurations

Peer Configuration

Field	Type	Required	Description
`name`	string	Yes	Unique human-readable identifier for this peer
`address`	string	Yes	Network address in `host:port` format

Notes:

Peers cannot be deleted via compose. Removing a peer from the configuration file will not remove it from the cluster. Use arctic peers delete to remove peers.
Peer names are used as references in service configurations.

Service Configuration

Field	Type	Required	Description
`name`	string	Yes	Unique human-readable identifier for this service
`source_peer`	string	Yes	Name of the source peer (must exist in peers list)
`target_peer`	string	Yes	Name of the target peer (must exist in peers list)
`transport_type`	string	Yes	Transport protocol: `tcp` or `kcp`
`fully_transparent`	bool	No	Enable fully transparent proxying mode (default: `false`)
`interface`	object	No	MACVLAN interface configuration
`qos`	object	No	Quality of service settings
`routes`	array	No	Routing rules for this service

Notes:

A service must have either interface (with enabled: true) or routes defined.
source_peer and target_peer must be different peers.

Interface Configuration

Field	Type	Required	Description
`enabled`	bool	Yes	Enable MACVLAN interface creation for this service
`ipv4`	string	No	Desired IPv4 address in CIDR notation (e.g., `10.0.0.1/24`)
`ipv6`	string	No	Desired IPv6 address in CIDR notation (e.g., `fd00::1/64`)

Notes:

If ipv4 and ipv6 are omitted, addresses are assigned via DHCP.
IPv4 cannot be 0.0.0.0/0 (broadcast address).
IPv4 addresses must be unique per source peer across services.

QoS Configuration

Field	Type	Required	Description
`bandwidth_limit_mbps`	uint64	No	Maximum bandwidth in Mbps (0 = unlimited)

Notes:

QoS is recommended for KCP transport to prevent bandwidth saturation.

Route Configuration

Field	Type	Required	Description
`source_cidr`	string	Conditional	Source network in CIDR notation
`dest_cidr`	string	Conditional	Destination network in CIDR notation
`priority`	uint64	Yes	Route evaluation order (lower value = higher priority)

Notes:

At least one of source_cidr or dest_cidr must be specified.
Cannot have both source_cidr and dest_cidr set to 0.0.0.0/0.
Priorities must be unique within a service.
Routes cannot conflict with another service on the same source peer (same source and dest CIDRs).

Validation Rules

Errors

Errors must be fixed before the configuration can be applied.

Field	Rule	Description
`version`	required	Version field is required
`version`	supported	Must be `v1`
`peers`	required	At least one peer is required
`peers[N].name`	required	Peer name is required
`peers[N].name`	unique	Peer names must be unique
`peers[N].address`	required	Peer address is required
`peers[N].address`	unique	Peer addresses must be unique
`services[N].name`	required	Service name is required
`services[N].name`	unique	Service names must be unique
`services[N].source_peer`	required	Source peer is required
`services[N].source_peer`	reference	Must exist in peers list
`services[N].target_peer`	required	Target peer is required
`services[N].target_peer`	reference	Must exist in peers list
`services[N]`	different-peers	Source and target peers must be different
`services[N]`	has-routing	Must have interface (enabled) or routes defined
`services[N].transport_type`	required	Transport type is required
`services[N].transport_type`	valid	Must be `tcp` or `kcp`
`services[N].interface.ipv4`	valid-cidr	Must be valid CIDR notation
`services[N].interface.ipv4`	not-broadcast	Cannot be `0.0.0.0/0`
`services[N].interface.ipv6`	valid-cidr	Must be valid CIDR notation
`services[N].interface.ipv4`	unique-per-peer	No duplicate IPv4 for same source peer
`services[N].routes[M]`	has-cidr	At least `source_cidr` or `dest_cidr` required
`services[N].routes[M].source_cidr`	valid-cidr	Must be valid CIDR notation
`services[N].routes[M].dest_cidr`	valid-cidr	Must be valid CIDR notation
`services[N].routes[M]`	not-full-broadcast	Cannot have both CIDRs as `0.0.0.0/0`
`services[N].routes[M].priority`	unique	Priorities must be unique within service
`services[N].routes[M]`	no-conflicts	Route cannot conflict with another service on same source peer

Warnings

Warnings are advisory and do not prevent configuration from being applied. Use --strict to treat warnings as errors.

Rule	Field	Description
`missing-port`	`peers[N].address`	Peer address missing port (typically `:8080`)
`interface-and-routes`	`services[N]`	Service has both interface and routes (typically use one or the other)

Canonical Key Ordering

The arctic compose fmt command reorders keys to a canonical order for consistency:

Root level: version, license, peers, services

Peer: name, address

Service: name, source_peer, target_peer, transport_type, fully_transparent, interface, qos, routes

Interface: enabled, ipv4, ipv6

QoS: bandwidth_limit_mbps

Route: source_cidr, dest_cidr, priority

Examples

Minimal Configuration

version: v1

peers:
  - name: peer-1
    address: 192.168.1.10:8080
  - name: peer-2
    address: 192.168.1.20:8080

services:
  - name: tunnel-1-to-2
    source_peer: peer-1
    target_peer: peer-2
    transport_type: tcp
    routes:
      - dest_cidr: 10.0.0.0/8
        priority: 100

Full Configuration

version: v1
license: ./license.jwt

peers:
  - name: datacenter-west
    address: 10.0.1.10:8080
  - name: datacenter-east
    address: 10.0.2.10:8080

services:
  # West to East tunnel
  - name: west-to-east
    source_peer: datacenter-west
    target_peer: datacenter-east
    transport_type: tcp
    fully_transparent: true
    interface:
      enabled: true
      ipv4: 10.100.0.1/24
    qos:
      bandwidth_limit_mbps: 100
    routes:
      - source_cidr: 0.0.0.0/0
        dest_cidr: 10.0.2.0/24
        priority: 100
      - source_cidr: 192.168.0.0/16
        dest_cidr: 172.16.0.0/12
        priority: 200

  # East to West tunnel (bidirectional)
  - name: east-to-west
    source_peer: datacenter-east
    target_peer: datacenter-west
    transport_type: tcp
    fully_transparent: true
    interface:
      enabled: true
      ipv4: 10.100.0.2/24
    qos:
      bandwidth_limit_mbps: 100
    routes:
      - source_cidr: 0.0.0.0/0
        dest_cidr: 10.0.1.0/24
        priority: 100

KCP Transport with QoS

version: v1

peers:
  - name: site-a
    address: 192.168.1.10:8080
  - name: site-b
    address: 192.168.2.10:8080

services:
  - name: kcp-tunnel
    source_peer: site-a
    target_peer: site-b
    transport_type: kcp
    qos:
      bandwidth_limit_mbps: 50  # Recommended for KCP
    routes:
      - dest_cidr: 10.20.0.0/16
        priority: 100

Compose Configuration

Compose Configuration

File Format

Configuration Schema

Root Structure

Peer Configuration

Service Configuration

Interface Configuration

QoS Configuration

Route Configuration

Validation Rules

Errors

Warnings

Canonical Key Ordering

Examples

Minimal Configuration

Full Configuration

KCP Transport with QoS

See Also

On this page