Updates and connection
After initial setup, your deployment card stays on the page for the life of the deployment. Two states need care: a release that waits for the customer's admin, and a deployment that stopped reporting. Both apply when you launch the portal from your product with a Deploy button, and when you build it into your product with your own setup screen.
Example UI /Update needs the admin
Document processing
Settings · Deploy in your cloud
Version 13 needs your AWS admin
Version 12 keeps running. Version 13 adds a permission, so an admin must update the setup in AWS.
A permanent green badge hides failed updates and lost connections. Keep a compact card instead:
- The release, the size, the endpoint, and "Last report" from
lastHeartbeatAt. - Your own Active flag, from Verify and activate.
- The last confirmed state with its time, instead of a guess.
Updates that need the admin
A release that adds a permission or a frozen resource can't apply on its own: only the admin's initial setup can create those. The deployment stays running on the old release, and updateState.active explains why. The example at the top of this page shows this state.
Show it when updateState.active.status is blocked. blocker.kind says why: setup, input, or other.
- Still running. The deployment stays
runningon the old release. A page that reads onlystatushides the wait. - Retry doesn't help. Only the admin rerunning initial setup, or the missing input, moves the update.
- Missing input. For
blocker.kind: "input", name the input fromblocker.inputIdand ask for its value. - Hold other changes. Disable size changes until the blocker clears, and say why.
- Name both releases. "Version 12 keeps running. Version 13 needs your AWS admin."
{
"status": "running",
"updateState": {
"active": {
"id": "duop_1x8kq2m4n6p8r0t2v4w6y8z0ab",
"status": "blocked",
"reasons": ["release"],
"targetReleaseId": "rel_13…",
"blocker": { "kind": "setup", "message": "Permission profile \"application\" was modified." },
"actionRequired": "Apply the updated setup to continue this update.",
"requestedAt": "2026-01-21T08:30:00Z"
},
"next": null,
"latest": null
}
}| Field | Meaning |
|---|---|
status | blocked, queued, applying, succeeded, failed, or superseded |
blocker.kind | setup: the admin must rerun initial setup. input: a value is missing (blocker.inputId). other: read blocker.message. |
blocker.message | What changed, for the admin |
actionRequired | The next step, written for people |
targetReleaseId | The release waiting to apply |
Review the setup change sends the admin to the deployment portal with a setup link, where Continue update shows the steps for their setup method.
Updating a Helm install
For a Helm install, rerunning initial setup is the normal chart upgrade. The deployment page shows one command, filled in with the release name, namespace, and the chart version the update waits on:
helm upgrade <release> <chart> --version <version> -n <namespace> --reset-then-reuse-values--reset-then-reuse-values keeps the customer's values and takes the defaults the new chart adds. It needs Helm 3.14 or later. Don't use --reuse-values: it drops those new defaults.
On an older Helm, save the current values and pass them as a file:
helm get values <release> -n <namespace> -o yaml > current.yaml
helm upgrade <release> <chart> --version <version> -n <namespace> -f current.yamlDelete current.yaml after the upgrade. It can contain the install's token.
Argo CD, Flux, and Terraform work the same way: set the chart version shown on the page and apply as usual. helm template | kubectl apply works too, with the encryption key pinned in the values, as for any GitOps install. The upgraded chart tells Alien which setup it carries, and the update continues with no further step.
Alien accepts that only when the chart was built for the waiting release and the change only touches Kubernetes objects the chart creates, such as service accounts. If Alien declines a chart, helm upgrade still succeeds, the old version keeps running, and the page shows the reason.
A chart upgrade can't carry these changes, so the page shows Run your cloud setup, then upgrade with the reason:
- A frozen resource in the customer's cloud account is added or changed. On EKS, GKE, and AKS this includes a service account, which gets a cloud identity.
- What the management identity may do changes.
- On EKS, GKE, and AKS, the cloud permissions of your workloads change.
The admin reruns the cloud part of initial setup, then upgrades the chart. An install whose Operator enrolled with a one-use code reports its chart the same way.
A chart upgrade can't change setup inputs after install: the chart refuses it. So the command never has --set flags for inputs.
If the chart is rolled back before the update finishes, the deployment stays paused. Upgrade to the chart version the page shows to finish it.
Not reporting
lastHeartbeatAt is the last time the deployment reported. The service keeps running when it loses its connection to Alien, so a late report doesn't prove an outage.
Example UI /Not reporting
Document processing
Settings · Deploy in your cloud
We can’t confirm the current state
The service last reported 25 minutes ago. It may still be running.
- Last confirmed
- Running version 12 at 09:21
- Last report
- 25 minutes ago
Show it when lastHeartbeatAt is older than your threshold, such as 10 minutes.
- Not an outage. A stale heartbeat means Alien can't see the deployment. The service may still serve requests.
- Last confirmed state. Show what you last knew with its time: "Running version 12 at 09:21."
- No traffic switch. Don't move traffic away on a stale heartbeat alone. Use your own health check for that.
- Heartbeats off. With
stackSettings.heartbeats: "off", the customer turned health checks off. Don't show a stale heartbeat as a warning.
{
"status": "running",
"lastHeartbeatAt": "2026-01-15T09:21:03Z",
"stackSettings": { "heartbeats": "on" }
}Pick a threshold, such as 10 minutes, and use it for a "Last report" line:
const STALE_AFTER_MS = 10 * 60 * 1000
export function connection(lastHeartbeatAt: Date | null) {
if (!lastHeartbeatAt) return { label: "Not connected yet" }
const age = Date.now() - lastHeartbeatAt.getTime()
if (age > STALE_AFTER_MS) return { label: "Not reporting", lastHeartbeatAt }
return { label: "Connected", lastHeartbeatAt }
}Test it
- Block an update. Release a version that adds a permission, and check your page says the admin must act while the old version keeps serving.
- Stop the heartbeat clock. Set
lastHeartbeatAt25 minutes back in a test response. The page says Not reporting, not Down. - Heartbeats off. Set
stackSettings.heartbeatstooff, and confirm the page shows no warning.
Next
- Show deployment progress: the states before ready
- Resize a deployment: size changes after initial setup
- Releases that need initial setup again: what your team sees
Verify and activate
Check that your product can reach a customer's new deployment, then turn the feature on. Running means Alien finished, not that the feature works.
Remove a deployment
Remove a customer's deployment from your product, switch traffic off first, and keep or erase the data in their cloud.