Updating
Pull the latest version of the platform into your deployment.
How updates work
Each release of ESP Private Agents is published as a versioned CloudFormation template. The Deployment Management Dashboard's Updates tab shows:
- The version your deployment is currently running.
- Newer versions available.
- A button to apply a selected version.
Applying an update kicks off a CloudFormation stack update under the hood. CloudFormation rolls forward in place; stateful resources (DynamoDB, Cognito, KMS) are preserved.
Steps
1. Open the Updates tab
Deployment Management Dashboard → Updates tab.
You'll see your current version at the top, and a list of available versions below.
2. Pick a version
Versions are listed newest first. The latest version is auto-selected. Pre-release versions are flagged.
You can either:
- Click Update to apply the selected version directly, or
- Copy the update URL to share with someone (e.g., to apply during a maintenance window).
3. Apply the update
Click Update. The platform triggers a CloudFormation stack update. The page refreshes the stack info every few seconds.
A typical update takes 5–20 minutes, depending on what changed. During that time:
- Existing chats may briefly disconnect when the gateway service restarts.
- New sign-ins may queue while Cognito changes (if any) propagate.
- The Admin and User dashboards stay reachable but might briefly serve a slightly older version while CloudFront invalidates.
4. Verify
Once the stack is back to UPDATE_COMPLETE:
- Sign into the Admin Dashboard. Confirm your agents and tools are intact.
- Send a test message to an agent. Confirm replies still work.
- (If voice was used) start a voice chat. Confirm audio still flows.
5. (Re-applying for config changes)
The Updates tab also lets you re-apply your current version. Useful when:
- You changed something in Configuration that needs the stack to redeploy to take effect.
- You want to refresh derived resources (CloudFront origins, ECS task definitions, etc.) without bumping the version.
Read release notes first
Every release ships with notes describing:
- New features.
- Breaking changes (rare, but called out clearly).
- Operator actions required (e.g., "after this update, re-check the X setting").
Read them before clicking Update — saves surprises.
Rolling back
CloudFormation has built-in rollback for failed updates. If an update fails mid-flight, the stack reverts to the previous version automatically.
If a successful update introduces a problem (something broke that you don't want), pick the previous version from the list and apply it the same way.
Caveat. Rolling backwards isn't always reversible — releases sometimes change the database schema or stored data shape. The release notes will tell you when a version is one-way.
Tips
- Update during a quiet window. Off-peak hours mean fewer disrupted users.
- Always one version at a time. Apply v1.5 from v1.3 by stepping through v1.4 if the release notes recommend it.
- Watch the events tab in CloudFormation. If the update is going slowly, the stack events show which resource is being updated and any errors.
Common gotchas
| Symptom | Likely cause |
|---|---|
| Update fails immediately | Permission issue (super-admin's IAM lost a needed permission). Check CloudFormation events. |
| Stack stuck in UPDATE_IN_PROGRESS | One nested stack is rolling back. CloudFormation events tab → drill in. |
| Update succeeds but the dashboard still shows old behavior | CloudFront cache. Hard-refresh the page; wait a few minutes. |
| WebSocket reconnect loop right after update | Gateway service restarting. Wait 1–2 minutes; if it persists, check ECS logs. |