Upgrade and roll back

An upgrade keeps the installation. It reuses the same Alien registration, credentials, encryption key, and identity storage. Only the chart or stack, the image, and the permissions change.

Except for removing the operator from a product release, every upgrade and rollback command comes from the setup page for that installation. Open the installation in setup, enter the same Kubernetes context and namespace, and select the owning release type you installed with.

When permissions change

If the enabled operations need different permissions than the ones installed, the setup page shows Permissions need an update with the added and removed AWS, Google Cloud, or Kubernetes requirements. Existing installations keep their current access until you upgrade them.

To apply the change:

• On Kubernetes, download the regenerated chart and run the upgrade command below. If the operator uses AWS or Google Cloud access, also apply the updated cloud access configuration.
• On ECS, generate and review the CloudFormation template, then run Apply reviewed update. The stack replaces the task role with the permissions of the enabled operations.

Then select I re-applied this setup. Alien records the permissions of the enabled operations as installed.

Stop new operations while you change permissions, and let running operations finish.

Kubernetes: dedicated release

The upgrade and restore commands are under Upgrade or restore this operator once the installation has registered.

Upgrade

1. Rename your current reviewed remote-operator directory to remote-operator-previous. The restore command needs it.
2. Configure the operations you want on the setup page and wait for the new operator image to build.
3. Download every chart file again into a new remote-operator directory.
4. Review the image, plugin versions, and Role changes with the cluster administrator.
5. Run Upgrade this operator.

The command stops unless the release is deployed and its stored values match the external-Secret layout that setup generates. It copies the current templates/check-installation.yaml into remote-operator-previous, so an older chart also gets the current restore checks. It then runs helm upgrade ./remote-operator --reset-values with the release's current values, --atomic --wait --timeout 5m.

Restore the previous chart

Before restoring an older package, restore the project's operation selection to the set used for that package. Keep its image available in your registry. Run Restore previous operator chart to go back to remote-operator-previous. It runs helm upgrade ./remote-operator-previous with the release's current values, so credentials rotated since the old version stay in place. The command stops if the saved chart has no values.schema.json, because a chart from before the external-Secret layout cannot use the current credentials.

Move a v0.2 release to v0.3

Dedicated releases from the v0.2 chart stored plaintext credentials in Helm values (registrationToken, encryptionKey, and collectorToken). Before the first normal upgrade, run Migrate dedicated operator from v0.2 to v0.3 once with the v0.3 remote-operator chart. It needs an operator-values.yaml in the v0.3 layout, with syncTokenRevision: 0 and the same serviceAccountAnnotations and podLabels as the v0.2 release. It checks the live release and resource ownership, copies the exact live credentials into the setup-owned Secret, records the Secret name and encryption-key fingerprint, and leaves only sanitized v0.3 history. It stops on any conflicting Secret or installation record.

Kubernetes: product release

For a product release, setup fills in Exact chart reference and Current reviewed version from the newest ready Helm package that embeds this installation's operator image. Record the operation selection used for each accepted package. Before restoring an older package, restore that package's operation selection under Choose operations; otherwise Alien may still offer operations whose plugins are absent from its image. If you cannot verify the prior selection, do not apply the restore. Then enter Previous reviewed product version under Upgrade or restore this operator.

These are upgrades of the whole product chart. Helm runs its upgrade hooks, and the chart may reconcile application workloads. Use Inspect this release to review the installed hooks and plan a maintenance window before upgrading, restoring, or removing the operator.

• Upgrade product release checks that the release is deployed and that the chart has the alien.dev/remote-operator-lifecycle: "v2" annotation. It then runs helm upgrade <release> <chart> --version <version> --reuse-values --atomic --wait --timeout 5m.
• Restore previous product version runs the same helm upgrade --reuse-values with the previous version. The previous chart can have lifecycle annotation v1 or v2.

Remove only the operator

You can remove the operator while keeping the product release installed. Under Remove or restore the Remote Operator in this product release, copy Remove the Remote Operator from this product release from setup. Its generated command checks that the release is deployed, the chart and version match the installed release, and the chart supports removal. It then upgrades with remoteOperator.enabled=false and remoteOperator.confirmRemoval=<release>. Copy the full guarded command; a bare helm upgrade skips those checks. The chart refuses removal unless confirmRemoval is the exact release name.

The removal deletes the operator Deployment, ServiceAccount, and RBAC. The chart's notes list what it keeps in the namespace, so you can restore the operator or retire its registration:

• The PersistentVolumeClaim <identity-record>-identity, which holds the operator identity.
• The ConfigMaps <identity-record>, <identity-record>-initialized, and <identity-record>-complete, which record the identity.
• The credentials Secret named in remoteOperator.existingSecret.name. The chart does not manage it.

<identity-record> is the operator's resource name. The chart notes print the exact names.

While the operator stays removed, keep remoteOperator.confirmRemoval=<release> on later upgrades. --reuse-values keeps it for you.

To bring the operator back with the same identity, keep the same remoteOperator.existingSecret values and copy Restore the Remote Operator from setup. Its generated command checks the installed release and confirmed removal, then enables the operator while clearing confirmRemoval and keeping bootstrapIdentity=false. The chart refuses confirmRemoval when the operator is enabled.

To retire the operator for good, retire its Alien registration, then delete the kept records. The chart notes print these commands with the exact names:

kubectl --context '<context>' --namespace <namespace> delete persistentvolumeclaim <identity-record>-identity
kubectl --context '<context>' --namespace <namespace> delete configmap <identity-record> <identity-record>-initialized <identity-record>-complete

Delete the retained credentials Secret named in remoteOperator.existingSecret.name only after confirming no other installation uses it. If the setup flow owns it, delete it with kubectl. If Terraform owns it, remove it through the owning Terraform configuration and review the plan before applying; deleting it only in Kubernetes lets the next Terraform apply recreate it.

After that, enabling the operator again requires first-time setup with new values. Uninstalling the product release also deletes these records.

Recover a failed or stopped Helm operation

Use recovery only when Helm is not running. If your terminal disconnected, check helm history first. A pending operation may still be running. Wait for it.

Do not delete Helm release Secrets, the identity volume, or the shared CRD to clear a lock. Use an exclusive maintenance window: no other Helm process, credential rotation, or CRD migration at the same time.

1. Under Upgrade or restore this operator, enter a Recovery Helm revision:
   • For a pending install or upgrade whose identity hook already completed, enter the current pending revision. Recovery checks it and finalizes that same revision without running hooks again.
   • For any other failed revision, enter the last successful revision from helm history. For a dedicated release, save its exact reviewed chart as remote-operator-previous. For a product release, enter its exact previous version.
2. Run Recover failed or stopped Helm operation. It requires Bash and jq.

Recovery checks the chart against the selected revision, the current credentials, resource ownership, and the shared CRD before it clears the pending operation. It stops if the selected revision used different credentials.

After any upgrade, restore, or recovery, wait for a fresh heartbeat from this installation and run a read-only diagnostic. A ready pod alone does not prove recovery.

Amazon ECS

To upgrade, generate the template again on the setup page and run Apply reviewed update, as described in Install on Amazon ECS. Record the operation selection used for each accepted image so you can restore it with that image.

Alien keeps the previously accepted operator image as the rollback target. Rollback becomes available after the installation accepts a newer image. Before rolling back an update that changed the selected operations, restore the selection used for the previous image under Choose operations. The rollback template uses that previous image with the operations and task-role permissions selected now. If you cannot verify the previous selection, do not apply the rollback; the older image may lack a newly selected plugin. To roll back:

1. Under Rollback template, select Prepare rollback to the previously accepted image. The page renders the previous image for the same stack. Its task role uses the operations selected now.
2. Select Download previous reviewed template. The browser saves remote-operator.previous.json.
3. Run Rollback from the directory that contains the file. It runs the same deploy command with --template-file 'remote-operator.previous.json'. At its hidden token prompt, paste the current syncToken from the existing Secrets Manager secret, as described in Apply an update.
4. When the latest heartbeat reports the rolled-back image, select Accept rolled-back image as desired.

Credentials and EFS identity storage are never rolled back.