compose

Manage Arctic clusters using declarative YAML configuration files.

Synopsis

arctic compose <subcommand> <config-file> [flags]

The compose command is the recommended way to deploy and manage Arctic clusters. It provides Infrastructure as Code (IaC) capabilities, allowing you to define your cluster state in a YAML file and apply it declaratively.

Subcommands

Subcommand	Description
apply	Apply cluster configuration from YAML
diff	Show differences between config and cluster state
export	Export cluster configuration to YAML
fmt	Format configuration files
init	Generate starter configuration template
validate	Validate YAML syntax and schema

apply

Apply cluster configuration from a YAML file.

Usage

arctic compose apply <config-file> [flags]

Arguments

Argument	Description
`config-file`	Path to cluster configuration YAML file

Flags

Flag	Description	Default
`--dry-run`	Show changes without applying	`false`
`--prune`	Delete resources not in config	`false`
`--ignore-unreachable`	Skip unreachable peers	`false`
`--license-file`	License file for bootstrap
`--credentials-file`	Write credentials to JSON file on bootstrap
`--env-file`	Write credentials to .env file on bootstrap
`--save-config`	Save cluster to CLI config and set as current	`true`
`--skip-validate`	Skip pre-validation checks (not recommended)	`false`
`--strict`	Treat validation warnings as errors	`false`

Required Scope

urn:tillered:arctic:admin

Examples

# Validate and apply configuration
arctic compose apply cluster.yaml

# Preview changes without applying
arctic compose apply cluster.yaml --dry-run

# Apply and prune resources not in config
arctic compose apply cluster.yaml --prune

# Apply with new license and save credentials
arctic compose apply cluster.yaml \
  --license-file license.json \
  --credentials-file creds.json

# Apply without saving to CLI config
arctic compose apply cluster.yaml --save-config=false

Output

Validating cluster.yaml...
OK - Configuration valid

Checking cluster state...
  peer-a: bootstrapped
  peer-b: bootstrapped

Planning changes...
  + Create service: web-tunnel (peer-a -> peer-b)
  + Create route: 0.0.0.0/0 -> 10.0.0.0/8

Applying changes...
  [OK] Created service web-tunnel
  [OK] Created route 10.0.0.0/8

Apply complete: 1 service created, 1 route created

diff

Show differences between configuration file and current cluster state.

Usage

arctic compose diff <config-file>

Arguments

Argument	Description
`config-file`	Path to cluster configuration YAML file

Required Scope

urn:tillered:arctic:peers.read, urn:tillered:arctic:services.read, urn:tillered:arctic:routes.read

Example

arctic compose diff cluster.yaml

Output

Comparing cluster.yaml with cluster state...

Services:
  ~ web-tunnel: bandwidth_limit_mbps changed (0 -> 100)
  + new-tunnel: will be created
  - old-tunnel: will be deleted (with --prune)

Routes:
  + 10.0.0.0/8: will be added to web-tunnel

export

Export current cluster configuration to YAML format.

Usage

arctic compose export [flags]

Flags

Flag	Description
`--file`	Output file path (defaults to stdout)

Required Scope

urn:tillered:arctic:peers.read, urn:tillered:arctic:services.read, urn:tillered:arctic:routes.read

Examples

# Export to stdout
arctic compose export

# Export to file
arctic compose export --file cluster.yaml

Output

version: v1
peers:
  - name: peer-a
    address: 192.168.1.10:8080
  - name: peer-b
    address: 192.168.1.20:8080
services:
  - name: web-tunnel
    source_peer: peer-a
    target_peer: peer-b
    transport_type: tcp
    routes:
      - source_cidr: 0.0.0.0/0
        dest_cidr: 10.0.0.0/8
        priority: 100

fmt

Format a cluster configuration file with consistent formatting.

Usage

arctic compose fmt <config-file> [flags]

Arguments

Argument	Description
`config-file`	Path to cluster configuration YAML file

Flags

Flag	Description	Default
`--write`	Write formatted output back to file	`false`
`--check`	Check if file is formatted (exit 1 if not)	`false`

Description

The fmt command normalizes YAML configuration files to a canonical format:

Reorders keys to canonical order (see Compose Configuration)
Uses 2-space indentation
Preserves comments

Examples

# Output formatted config to stdout
arctic compose fmt cluster.yaml

# Format file in place
arctic compose fmt cluster.yaml --write

# Check if file is formatted (for CI)
arctic compose fmt cluster.yaml --check

Output (stdout mode)

The formatted YAML is written to stdout, allowing piping or redirection:

# Pipe to another file
arctic compose fmt cluster.yaml > formatted.yaml

# Review diff before writing
arctic compose fmt cluster.yaml | diff cluster.yaml -

Output (check mode)

cluster.yaml is formatted correctly

Or if not formatted:

cluster.yaml is not formatted

Exit code 1 indicates the file is not formatted.

init

Generate a starter cluster configuration template.

Usage

arctic compose init [flags]

Flags

Flag	Description	Default
`--file`	Output file path (defaults to stdout)
`--minimal`	Generate minimal valid config	`false`
`--example`	Generate full example with comments	`true`

Examples

# Generate example config to stdout
arctic compose init

# Generate example config to file
arctic compose init --file cluster.yaml

# Generate minimal config
arctic compose init --minimal

# Generate minimal config to file
arctic compose init --minimal --file cluster.yaml

Output (minimal mode)

version: v1

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

services: []

Output (example mode)

Generates a full-featured template with comments explaining each field:

# Arctic Cluster Configuration
# Schema version (required)
version: v1

# Path to license file (relative to this config file)
# Uncomment and update when bootstrapping a new cluster
# license: ./license.jwt

# Peers define the nodes in your cluster
peers:
  - name: datacenter-1
    address: 192.168.1.10:8080
  - name: datacenter-2
    address: 192.168.2.10:8080

# Services define the tunnels between peers
services:
  - name: dc1-to-dc2
    source_peer: datacenter-1
    target_peer: datacenter-2
    transport_type: tcp
    fully_transparent: false
    routes:
      - dest_cidr: 10.0.0.0/8
        priority: 100

validate

Validate cluster configuration YAML syntax and schema.

Usage

arctic compose validate <config-file> [flags]

Arguments

Argument	Description
`config-file`	Path to cluster configuration YAML file

Flags

Flag	Description	Default
`--strict`	Treat warnings as errors	`false`

Example

arctic compose validate cluster.yaml

Output (Valid)

Validating cluster.yaml...
OK - Configuration valid

Schema version: v1
Peers: 2
Services: 1
Routes: 1

Output (Invalid)

Validating cluster.yaml...
ERROR - Configuration invalid

Errors:
  - services[0]: source_peer "unknown" not found in peers list
  - services[0].routes[0]: invalid source_cidr "invalid"

Configuration Schema

See Compose Configuration Reference for the complete YAML schema documentation, including:

Field definitions and types
Validation rules (errors and warnings)
Canonical key ordering for fmt
Full examples

Quick Reference

version: v1                    # Schema version (required)
license: path/to/license.json  # License file path (optional)
peers:                         # Peer definitions (required)
  - name: string               # Unique peer name
    address: host:port         # Agent address
services:                      # Service definitions (optional)
  - name: string               # Unique service name
    source_peer: string        # Source peer name
    target_peer: string        # Target peer name
    transport_type: tcp|kcp    # Transport protocol
    fully_transparent: bool    # Full transparency mode (default: false)
    interface:                 # MACVLAN interface config (optional)
      enabled: bool
      ipv4: CIDR
      ipv6: CIDR
    qos:                       # QoS settings (optional)
      bandwidth_limit_mbps: uint64
    routes:                    # Routing rules (optional)
      - source_cidr: CIDR
        dest_cidr: CIDR
        priority: uint64

Note: A service requires either interface (enabled) or routes to be functional.

Exit Codes

Code	Condition
0	Success
1	General error
2	Validation error
3	Configuration error
4	Connection error

compose

On this page