How to Rotate Credentials

This guide shows you how to rotate the shared cluster credential. Rotation generates a new client secret while maintaining a grace period for the old secret.

Before You Start

Understand that credential rotation:

Generates a new client secret for the cluster credential
Maintains the old secret for a 24-hour grace period
Propagates the new secret to all cluster peers via gossip
Requires updating any automation using the old secret

Rotate the Cluster Credential

arctic credentials rotate

# To automatically update your local CLI config with the new secret:
arctic credentials rotate --update-config

Response

The rotation returns the new credential:

{
  "client_id": "cl_01HXYZ...",
  "client_secret": "sec_NEW_SECRET...",
  "version": 2,
  "rotated_by": "01HXYZ...",
  "rotated_at": "2024-01-15T10:30:00Z"
}

Important: The new client_secret is only shown once. Store it securely.

Grace Period

After rotation:

New secret: Works immediately
Old secret: Continues to work for 24 hours
After 24 hours: Only the new secret works

This grace period allows you to update all systems without downtime.

Update Your Systems

After rotating, update all systems that use the credential:

CLI Configuration

If you did not use --update-config, manually update your config:

# View current config
arctic config view

# Edit the config file
# Location: ~/.config/arctic/config.yaml

Automation and Scripts

Update any scripts or automation that use the credential:

# Example: Environment variable
export ARCTIC_CLIENT_SECRET="sec_NEW_SECRET..."

# Example: Config file
client_secret = "sec_NEW_SECRET..."

CI/CD Systems

Update secrets in your CI/CD platform (GitHub Actions, GitLab CI, etc.).

Verify the New Credential

Test that the new credential works:

# Get a token with the new secret
curl -X POST http://AGENT_IP:8080/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=NEW_SECRET"

Rotation Best Practices

Schedule rotation during low-traffic periods
Communicate to your team before rotating
Update systems within the 24-hour grace period
Test after updating each system
Document the rotation in your change log

Troubleshooting

New Secret Not Working

If the new secret fails:

Verify you copied the secret correctly (no extra spaces)
Check the credential version: arctic credentials list
Wait a few seconds for gossip propagation

Old Secret Stopped Working

If the old secret stops working before 24 hours:

Check if another rotation occurred (version increased)
Verify the system clock is correct on all agents

Gossip Propagation Delayed

If peers do not receive the new credential:

Check cluster connectivity: arctic health --all-contexts
Trigger a sync: arctic cluster sync
Check agent logs for gossip errors

Rotate Credentials

On this page