Upgrades

This guide covers the process of upgrading Arctic agents and the CLI to a new version.

Pre-upgrade checklist

Before upgrading, verify:

• All peers are healthy. There is no cluster-wide health command; check each peer individually (see below).
• No active configuration changes are in progress.
• You have a backup of /opt/tillered/arctic.db on each peer.
• You have reviewed the release notes for breaking changes.

To check peer health, list the peers and run a readiness check against each one:

arctic peers list

# Against a specific peer/context
arctic health --readyz

Upgrading the Arctic Agent

The downloaded agent binary (distinct from the arctic CLI) ships an upgrade subcommand that handles the service swap. Upgrade each node running the agent:

1. Shell into the node.

2. Download the agent binary for the host architecture:

curl -L https://release.tillered.com/arctic/latest/agent_amd64 -o ./agent
chmod +x ./agent

For arm64 hosts, use agent_arm64.

3. Run the upgrade:

./agent upgrade

This stops the running agent, replaces the binary, then enables and starts the arctic service.

Rolling upgrade across a cluster

Upgrade one peer at a time to maintain cluster availability:

1. Start with non-critical peers first.
2. On each peer, download the agent binary and run ./agent upgrade.
3. After each peer upgrade, verify cluster health before proceeding:

arctic peers list
arctic health --readyz

4. Upgrade the remaining peers one at a time.

Upgrading the Arctic CLI

Download the new CLI binary:

curl -L https://release.tillered.com/arctic/latest/arctic_linux_amd64 -o arctic
chmod +x ./arctic

For other platforms use the matching artifact, e.g. arctic_linux_arm64 or arctic_darwin_arm64.

You can either use it directly from the current directory or install it to a location on your PATH:

sudo mv ./arctic /usr/local/bin/arctic

There is no service to stop or start. The CLI reads ~/.config/arctic/config.yaml for authentication automatically.

Post-upgrade verification

Use the CLI to verify the state of your agents after upgrading:

1. Verify peers are reachable and at the expected version:

arctic peers list

2. Verify services are operational:

arctic services list

3. Confirm the license is still valid:

arctic license status

4. Test traffic flow through representative services.

5. Check agent logs for any warnings:

journalctl -u arctic --since "10 minutes ago"