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.
• Each peer has a recent database snapshot. The agent takes one automatically (daily by default) into /opt/tillered/backup/; check the newest file's timestamp there, or capture one from immediately before the upgrade with arctic database snapshot (see backup and restore).
• You have reviewed the release notes for breaking changes and upgrade-order constraints. Some releases cannot be rolled one node at a time; v1.4.2 is one (see Upgrading to v1.4.2).

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

Unless the release notes say otherwise, 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.

Upgrading to v1.4.2

v1.4.2 turns on peer TLS cluster-wide, so upgrade every node in the cluster together rather than rolling. An upgraded agent dials its peers expecting TLS and pins their identity keys, so a mixed cluster cannot form a mesh. Plan one window, run ./agent upgrade on every node, then verify.

Other v1.4.2 specifics:

• Database migrations run themselves. Migrations 000014 (device selection) and 000015 (MPTCP) run automatically on the agent's first start. No operator action is needed.
• The CLI state file moved to schema v2. .arctic/cluster.state migrates automatically the first time the new CLI loads it. A downgraded CLI reading a v2 state file exits with code 3 and a message naming both versions; if you must stay on the older CLI, remove the .arctic/ directory and let it re-bootstrap.
• Existing systemd units are preserved. The upgrade keeps your current (possibly customized) arctic.service. To adopt the new default hardened unit on an existing host, run sudo agent install --force; see Hardening.
• Password hashes migrate on use. Existing credential hashes are re-derived to PBKDF2 transparently on the next successful authentication. No action is needed.
• The CLI discovers TLS on its own. After upgrading a cluster that ran plaintext, the first compose apply or compose diff probes the agents, discovers TLS, and pins their identities automatically; no --insecure run or config edits are needed for scheme-less endpoints. See TLS and trust.

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"