Declarative Cluster Management

This guide explains how to use the arctic compose command to manage your cluster declaratively using YAML configuration files.

Overview

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

Benefits

• Version Control: Track cluster configuration changes in Git
• Reproducibility: Deploy identical configurations across environments
• Review Process: Use pull requests to review changes before applying
• Automation: Integrate with CI/CD pipelines

When to Use Compose vs Imperative Commands

Basic Workflow

The typical workflow for using compose is:

1. Init a starter configuration (for new clusters)
2. Export existing configuration (if upgrading from imperative management)
3. Edit the YAML file to define desired state
4. Format the configuration for consistency
5. Validate the configuration syntax
6. Diff to preview changes
7. Apply to make changes

# Create starter config (new clusters)
arctic compose init --file cluster.yaml

# Or export existing state (existing clusters)
arctic compose export --file cluster.yaml

# Edit cluster.yaml as needed

# Format after editing (optional but recommended)
arctic compose fmt cluster.yaml --write

# Validate syntax
arctic compose validate cluster.yaml

# Preview changes
arctic compose diff cluster.yaml

# Apply changes
arctic compose apply cluster.yaml

Configuration File Structure

Minimal Example

version: v1

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

services:
  - name: tunnel-1-to-2
    source_peer: agent-1
    target_peer: agent-2
    transport_type: tcp
    routes:
      - source_cidr: 0.0.0.0/0
        dest_cidr: 10.0.0.0/8
        priority: 100

Note: Services require transport_type and either interface or routes to be functional.

Important: Peers cannot be deleted via compose. Removing a peer from the configuration file will not remove it from the cluster. Use arctic peers delete or the API to remove peers.

Full Example

version: v1
license: ./license.json

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

services:
  - 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

  - 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

Validating Configuration

Always validate your configuration before applying:

arctic compose validate cluster.yaml

Validation checks:

• YAML syntax
• Schema version
• Required fields
• Peer name references in services
• CIDR notation format
• No duplicate names

Previewing Changes

Use diff to see what will change before applying:

arctic compose diff cluster.yaml

Output shows:

• + Resources to be created
• - Resources to be deleted (with --prune)
• ~ Resources to be modified

Applying Configuration

Basic Apply

arctic compose apply cluster.yaml

This will:

1. Validate the configuration
2. Connect to each peer
3. Show planned changes
4. Prompt for confirmation
5. Apply changes

Dry Run

Preview changes without applying:

arctic compose apply cluster.yaml --dry-run

Prune Orphaned Resources

Delete resources not defined in the configuration:

arctic compose apply cluster.yaml --prune

Warning: Use with caution. Review with --dry-run first.

Handle Unreachable Peers

Skip peers that cannot be contacted:

arctic compose apply cluster.yaml --ignore-unreachable

Bootstrap with License

When bootstrapping new agents:

arctic compose apply cluster.yaml \
  --license-file license.json \
  --credentials-file creds.json

The credentials file will contain OAuth credentials for each bootstrapped agent.

Exporting Configuration

Export current cluster state to YAML:

# To stdout
arctic compose export

# To file
arctic compose export --file cluster.yaml

This is useful for:

• Migrating from imperative to declarative management
• Creating backups
• Starting a new configuration from existing state

Best Practices

Use Version Control

Store your configuration files in Git:

git add cluster.yaml
git commit -m "Add west-to-east tunnel service"

Environment-Specific Files

Maintain separate files for each environment:

configs/
  development.yaml
  staging.yaml
  production.yaml

Review Before Applying

Always use diff and --dry-run before applying to production:

# First, see the diff
arctic compose diff production.yaml

# Then, dry run
arctic compose apply production.yaml --dry-run

# Finally, apply
arctic compose apply production.yaml

Credential Management

When using --credentials-file or --env-file:

1. Never commit credentials to version control
2. Use secure storage (e.g., secrets manager)
3. Rotate credentials regularly

Troubleshooting

Validation Errors

ERROR - Configuration invalid
Errors:
  - services[0]: source_peer "unknown" not found in peers list

Fix: Ensure all peer references match peer names defined in the peers section.

Connection Errors

Error: failed to connect to peer agent-2: connection refused

Options:

• Verify the peer address is correct
• Check network connectivity
• Use --ignore-unreachable to skip

Drift Detection

If the cluster state has drifted from your configuration:

# See differences
arctic compose diff cluster.yaml

# Re-apply to restore desired state
arctic compose apply cluster.yaml

See Also

• compose - CLI reference
• Compose Configuration - YAML schema reference
• services - Imperative service management
• peers - Imperative peer management