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 stateCopy Anchor Link

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 registrationCopy Anchor Link

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.

To find a setup you started earlier, open the project overview. In a project that uses only Remote Operator, Unfinished setups lists each installation whose operator never registered. Select Resume setup.

Repair from the installation pageCopy Anchor Link

Open the installation under Deployments. The Repair connection section opens by itself when the installation is stale, unhealthy, or still connecting. Check connection on the project overview links to it.

For Kubernetes, the section has two commands. Run them with the kube context of the cluster that runs the installation. Alien does not record the context.

1. Inspect Operator prints the Helm status, the operator Deployment, its pods, the last hour of logs, and recent events.
2. Restart Operator runs kubectl rollout restart on the operator Deployment and waits up to five minutes for the rollout. Use it when the pod is crash-looping, stuck, or has lost its network path to Alien. The Deployment uses the Recreate strategy, so the old pod stops before the new pod starts, and the operator keeps its identity volume.

Both commands find the Deployment through the installation's Helm release and the label app.kubernetes.io/component=operator. They stop when no Deployment matches or more than one matches. They need helm, kubectl, and jq.

The installation reconnects with its next heartbeat. If the logs show a rejected or expired credential, select Manage installation and rotate the connection key.

For Amazon ECS, the section links to Manage installation, where the Repair task command is. See Amazon ECS.

KubernetesCopy Anchor Link

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 ECSCopy Anchor Link

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 repairCopy Anchor Link

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.