Repair a connection

An installation is connected while Alien receives its heartbeat. A heartbeat counts as fresh for five minutes. Repair keeps the installation's identity: the same registration, encryption key, and identity storage. Do not replace any of them to fix a connection.

Read the current state

Open the installation on the setup page. The status tells you where it is:

On ECS, Observed installation state also shows the health, the image status, and the operations bundle status.

Before the first registration

Before the operator registers, setup can issue replacement values or a replacement registration token for the same installation. What you do next depends on whether an install attempt already created credentials:

• On Kubernetes, select Generate replacement values. If the credentials Secret has not been created, use both new files for the first dedicated install or to enable the operator in a product release that was installed with the operator disabled.
• If an earlier Kubernetes install or enable attempt created the credentials Secret, save the replacement files under different names. Keep the existing Secret name, encryption key, collector token, and original operator-values.yaml; the replacement files contain new encryption and collector keys, so do not apply them as a whole. Patch only sync-token in the existing Secret with the new token, and change only that field in the saved operator-credentials.yaml. Check that the saved file matches the live Secret with kubectl --context '<context>' --namespace <namespace> diff --filename operator-credentials.yaml, then retry the same generated install or enable command. If Helm has a failed or pending revision, recover it first. Do not rerun helm install for a completed release. If the original files are lost or the release appears deployed without registration, stop and inspect the existing release and connection before changing credentials.
• On ECS, select Generate replacement registration token and run the deploy command again with the new token.

Both buttons disappear once the operator registers. A registered installation never gets new bootstrap values. If Alien reports that the installation is already registered, open it and check its connection instead.

Kubernetes

1. Run Inspect this release from the setup page. It shows helm status, helm history, the pods and PersistentVolumeClaims in the namespace, and the credentials Secret.
2. If helm status is not deployed, the last Helm operation failed or stopped. Use the guarded recovery in Upgrade and roll back.
3. If the pod does not start, read its events. Check image pull access, the identity PersistentVolumeClaim, and the StorageClass.
4. If the pod runs but no heartbeat arrives, check outbound DNS and HTTPS from the namespace to the management endpoint in the template.

Keep the identity volume and the credentials Secret throughout. The chart refuses an upgrade when the identity volume is missing, and refuses a Secret whose encryption key differs from the one recorded at install.

Amazon ECS

Under Manage the ECS installation, open Repair task. The command starts a replacement task on the exact service without changing the stack:

1. Checks the AWS account and the stack outputs AccountId, Region, EnvironmentName, and ClusterArn.
2. Runs aws ecs update-service --force-new-deployment on the service from the ServiceArn output.
3. Waits until the service is stable.

If the new task also fails, read the CloudWatch Logs group in the stack output LogGroupName. Check that the subnets have outbound HTTPS, that the security groups allow NFS to the EFS mount targets, and that the registration secret still exists.

After a repair

Wait for a fresh heartbeat, then run a read-only diagnostic on the installation. The installation is repaired when that operation succeeds. A running pod or task alone does not prove it.

If the setup page shows Permissions need an update, the installed permissions no longer match the enabled operations. Apply the update as described in When permissions change.