Install Updates

ServerlessInbox deployments update themselves automatically for routine (minor) releases. Some releases, however, change the shape of your CloudFormation stack — renamed or replaced resources, new IAM permissions, and similar structural changes. Those releases are never applied automatically. Instead, you review and apply them yourself from the admin UI, with a full preview of what will change before you commit to anything.

Where to find it

Open Infrastructure in the admin UI sidebar (/operations/lambda-concurrency) and scroll to the Install update section, below the concurrency, Lambda health, and recent-errors panels.

This section only appears if your deployment includes the install-update capability. It’s present in every standard ServerlessInbox deployment, but a bespoke or customized CDK deployment may not include it — if your deployment was built from a customized stack, check with whoever maintains it. When the capability isn’t present, this part of the Infrastructure page simply doesn’t render; there’s no error or placeholder in its place.

Minor updates vs. major updates

The Install update section shows your current version and, if newer versions exist, one or two buttons:

• Update to v{next minor} — a routine, non-breaking release. This is the same kind of update your deployment already installs on its own on a schedule; installing it manually here just applies it immediately instead of waiting.
• Update to v{next major}, marked with a Breaking badge — a structural update. Major releases can add, remove, or replace stack resources and can change IAM permissions. Because a structural change carries real risk (a resource being replaced can mean data loss for that resource, and a permission change deserves a human look before it’s granted), ServerlessInbox never applies these on its own. This page is the only way to install one.

If no newer version exists, the section shows a confirmation that you’re already on the latest version and there’s nothing further to do.

Reviewing an update

Clicking either update button creates a CloudFormation change set against your stack and opens the Review stack update dialog. Nothing is applied yet at this point — a change set is CloudFormation’s own preview of a proposed update, and creating one has no effect on your running stack.

While the change set is being computed, the dialog shows Preparing change set…. If creation fails, the dialog shows the reason and you can close it and try again.

Once the change set is ready, the dialog presents three ways to review exactly the same set of proposed changes:

• Resource changes — a grouped list of every resource CloudFormation plans to add, modify, or remove. Resources whose only change is the version tag are collapsed into a single Version-tag-only changes group by default, since a routine update commonly touches hundreds of resources this way and they aren’t useful to review individually. Any changes to IAM roles or permissions are pulled out into their own IAM-related changes group at the top, so they’re never buried in a long list. Everything else falls into Other changes.
• Construct tree — the same resource changes, but grouped by the part of the stack each one belongs to, rather than presented as a flat list. Useful if you want to see which area of your deployment — mail receiving, authentication, the admin UI, and so on — a given change affects.
• Raw template diff — a line-by-line diff of the underlying CloudFormation template, before and after. This is the ground truth the other two views are computed from; use it if you want to see precisely what will change, unfiltered and ungrouped.

A View in CloudFormation console link is also provided, if you’d rather inspect the change set directly in the AWS Console.

IAM changes require explicit acknowledgment

If any part of the update touches IAM roles, policies, or permissions, the dialog shows a warning: “This update changes IAM roles, policies, or permissions. Review the resource changes above before proceeding.” You must check “I have reviewed the IAM permission changes in this update” before you can proceed — this checkbox is required, not optional, whenever IAM changes are present, and is re-verified by the server at execution time regardless of what the page shows you. It’s there to make sure a permission change is never applied by accident or without a moment’s attention.

Confirm by typing the stack name

Before the Execute update button becomes enabled, you must also type your stack’s name into the “Type the stack name to confirm” field. This is a deliberate extra step for an action this consequential — it’s checked against your real stack name on the server when you execute, not just in the browser.

Applying the update

Once you click Execute update, the dialog switches to Applying update… and polls for progress. From here:

• If the update finishes successfully, you’ll see Update complete.
• If the update fails, you’ll see The update failed, along with the last status message CloudFormation reported, to help you understand what went wrong.
• If CloudFormation automatically rolls the stack back after a failure (its default behavior for a failed update), you’ll see a distinct The update failed and CloudFormation automatically rolled back the stack message instead, with a Rolling back the failed update… progress state while the rollback is in progress. A rollback returns your stack to the state it was in before the update was attempted.

Every attempt to install an update — successful or not — is recorded in the Update history table at the bottom of the Install update section, with the time it was executed, the version change, its final status, and who ran it. This is your record of what was installed and when, even for attempts that failed.

Resuming or recreating a review

If you navigate away from the Infrastructure page (or close the browser) after creating a change set but before executing it, your review isn’t lost. The next time you open the Infrastructure page, the Install update section detects the pending change set and shows a Resume review of pending update, created [time] ago banner instead of the normal update buttons. Click Resume review to reopen the same review dialog exactly where you left off — you don’t need to recreate anything, and a different admin opening the page will see the same pending review, since it’s tracked by CloudFormation itself rather than tied to your browser session.

If a newer version is published while a review is still pending, the banner instead reads “A pending review is out of date — a newer version is now available”, with a Recreate action. Recreating replaces the outdated change set with a fresh one built against the current version — you can’t execute a stale review, so recreating is the only way forward once this happens.

You’ll see a similar message — “This change set is no longer valid — the stack changed since it was created. Recreate it and try again” — if you try to execute a review that went stale after you opened it (for example, someone else applied a change to the stack in the meantime). Recreate the change set and review it again in that case too.

If another update is already being applied when you try to start or execute one, you’ll see “Another update is already in progress for this stack. Please wait for it to finish before trying again” — only one update can be in flight against your stack at a time.

A note on safety

Executing an update here triggers a real CloudFormation update against your own running stack — the same kind of operation as running cdk deploy or updating a stack from the AWS Console, just gated behind a review step instead of a command line. The three review views exist specifically so you can see exactly what’s about to change, in as much or as little detail as you want, before you commit to it — this matters most for major (structural) updates and for any update that touches IAM permissions, which is why those are called out explicitly rather than left for you to notice on your own.