Rotate the connection key

Each installation connects to Alien with its own deployment-scoped connection key. After first registration, the operator stores that key on its identity volume; the Kubernetes credentials Secret's sync-token or the ECS Secrets Manager secret's syncToken may still hold the original one-time registration token. During rotation, the replacement key is written to that Secret, then the operator validates and stores it on the identity volume. Rotation changes only the connection key. The installation keeps its deployment identity, encryption key, and identity storage. On Kubernetes, it also keeps the collector token.

Before you start

• You must be a workspace administrator. Other roles cannot view, prepare, cancel, or download a rotation.
• The installation must be registered through Kubernetes manual setup or ECS CloudFormation setup, and it must be running a build that supports rotation.
• Rotate on its own. Do not combine it with an image, plugin, permission, or CRD change.

The downloaded credential patch or JSON value, including a rollback download, contains a live connection key. Keep these files in a private directory outside version control and synced or shared folders, restrict them to your user with chmod 600, and remove them after the rotation completes or the rollback has been applied. Do not commit or share them.

How a rotation completes

A rotation has three states:

Each rotation has a revision number. The operator ignores credentials with an older revision than the one it has.

Kubernetes

Open the installation on the setup page. After it registers, the Install and verify step shows Rotate this installation’s connection key.

1. Under Installed release ownership, select Dedicated Remote Operator release or Product release with embedded Remote Operator. Take this from your installation records. The release name alone does not tell them apart.
2. Confirm the target:
   • For a dedicated release, select the checkbox that confirms the release, namespace, and Kubernetes context.
   • For a product release, enter the Installed chart reference from the saved install command or deployment record, the Installed chart version from helm history, and the Installed credentials Secret from helm get values. The Secret name is remoteOperator.existingSecret.name. helm history does not retain the repository or OCI source; if the reference was not recorded, recover it from the deployment configuration or package record before continuing. Select the Credentials Secret owner: Setup flow or Terraform. Then select the checkbox.
3. Select Prepare replacement key.
4. Select Download credential patch. The browser saves operator-credential-patch.yaml, which contains only the new sync-token:

stringData:
  sync-token: "<replacement key>"

5. Copy Apply this credential revision and run it from the directory that contains the patch file. For a dedicated release, run it from the directory that also contains the remote-operator chart.

For a Secret owned by the setup flow, the command:

1. Checks the target. The release must be deployed, its values must point at the Secret, the Secret must hold exactly collector-token, encryption-key, and sync-token, and the SHA-256 of encryption-key must match remoteOperator.existingSecret.encryptionKeySha256.
2. Stops unless the patch file contains exactly one non-empty stringData.sync-token.
3. Patches only sync-token in the Secret with kubectl patch secret --type merge.
4. Runs helm upgrade --reuse-values --set remoteOperator.syncTokenRevision=<revision> --atomic --wait --timeout 5m so the operator restarts with the new key.

For a Secret owned by Terraform, the command writes the key and revision to .alien-remote-operator.auto.tfvars.json as remote_operator_sync_token and remote_operator_sync_token_revision. It then runs terraform plan and applies the plan only if it updates nothing except kubernetes_secret_v1.remote_operator_credentials and helm_release.runtime. Run it in the exact module and workspace that installed the release. In a Git checkout, the tfvars file must be ignored by Git, or the command stops.

When the operator reports the replacement, the status changes to Replacement active. Run a read-only diagnostic to confirm operations still work.

Amazon ECS

Open the installation on the setup page. Under Manage the ECS installation, find Rotate the deployment-scoped connection key.

1. Select the checkbox that confirms the account, Region, stack, and cluster from the installed stack outputs.
2. Select Prepare replacement key.
3. Select Download credential value. The browser saves remote-operator-credential-rotation.json with syncToken, revision, and, for a prepared rotation, expiresAt.
4. Copy Apply rotation and run it from the directory that contains that file.

The command:

1. Checks that the file's revision matches the rotation. For a prepared rotation, it also checks the expiry and that the replacement has not expired.
2. Checks the AWS account and the stack outputs AccountId, Region, EnvironmentName, and ClusterArn.
3. Writes a new version of the registration secret with the new syncToken and the same encryptionKey.
4. Creates a CloudFormation change set that changes only the RegistrationSecretVersionId parameter, executes it, and waits for the stack update. ECS replaces the task.
5. Waits until the ECS service is stable.

If another stack update wins, the command stops. Wait for that update to finish, then rerun the same command to reconcile the secret and stack. When safe, the command moves the secret's current stage back to the version pinned by the stack.

If the rotation is interrupted

• If the apply command stops after it changed the Secret or secret version, run the same command again. Do not prepare another revision.
• If the replacement expired or you need to stop, select Cancel pending rotation. Then select Download rollback patch (Kubernetes) or Download rollback value (ECS), and run the apply command again with that file. It puts the current key back.
• Do not delete the identity volume, the credentials Secret, or the registration secret to recover.