Rolling back

Rollback restores a previous release state by retrieving deployment context from S3. This enables you to revert infrastructure changes to a known-good configuration when issues arise.

Rollback operations use a two-phase workflow: first create a rollback plan to review proposed changes, then apply it to execute the rollback. Each rollback preserves a reference to the target release through the rollbackDeploymentId field.

---

Prerequisites

• At least one successful release with stored deployment context
• Target release must have been created after the deployment context storage feature rollout
• Appropriate release authority permissions

---

Understanding Rollback Prerequisites

For a release to serve as a rollback target, it must have a deploymentContextFilePath stored in S3. This file contains the complete deployment state including stack version, overrides, resource metadata, modules, and resources.

Older deployments created before the deployment context storage feature cannot be used as rollback targets. If you attempt to roll back to such a release, the system will prompt you to select a more recent release.

The deployment context is stored in S3 rather than MongoDB to avoid document size limits and enable efficient retrieval of full historical state.

---

Creating a Rollback Plan

Follow these steps to create a rollback plan:

1. Open the resource in Projects > Resources, select it, and go to its Release History tab.
2. On the release you want to roll back to, click Rollback. The rollback plan is scoped to that one resource. The button is hidden on APPLY_ROLLBACK_PLAN rows, and disabled when the old and new versions are identical.
3. The system generates a ROLLBACK_PLAN release type that shows what will change.
4. Review the plan to see:
   • Resources that will be restored
   • Stack versions that will be applied
   • Configuration changes between current and previous state
   • Terraform changes that will execute

The rollback plan fetches the target deployment context from S3 using the deploymentContextFilePath. It retrieves the full context including stackSourceVersion, overrides, resourceMetadata, modules, and resources from the previous release.

The plan presents a comparison between your current state and the state you're reverting to, allowing you to verify the impact before proceeding.

---

Applying the Rollback Plan

Creating the plan changes nothing on the environment. The rollback only takes effect once you apply it.

1. Open the ROLLBACK_PLAN release from the environment's release history.
2. Review the planned changes one more time, in particular any resource the plan will destroy or replace.
3. Click Apply Plan and confirm.

Facets records the applied release as an APPLY ROLLBACK PLAN release, separate from the ROLLBACK_PLAN release that produced it. Both stay in the release history, so the plan you reviewed and the apply that acted on it remain auditable.

To verify the restored state:

• Confirm the APPLY ROLLBACK PLAN release finished with a SUCCEEDED status.
• Open the release and check the Terraform logs to confirm the changes the plan listed are the changes that ran.
• Check the environment's resources against the release you rolled back to.

If the environment has a release approval gate configured, the apply passes through it like any other release.