Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 52 additions & 4 deletions docs/services/cloudformation.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
| `CreateStack` | Deploy a CloudFormation template |
| `UpdateStack` | Update an existing stack |
| `DeleteStack` | Delete a stack and its resources |
| `ContinueUpdateRollback` | Retry the rollback of a stack in `UPDATE_ROLLBACK_FAILED`, optionally skipping resources or forcing past every failed one (see [Failed update rollbacks](#failed-update-rollbacks)) |
| `UpdateTerminationProtection` | - |
| `CreateChangeSet` | Create a change set |
| `DescribeChangeSet` | Get change set details with a computed Add/Modify/Remove resource diff |
Expand Down Expand Up @@ -127,10 +128,8 @@ owed cleanup while their retry budget remains. Exhausted historical records are
later updates and stack-delete retries. Historical cleanup is address-based and does not provide
an atomic ownership check against another stack or a direct Cognito API writer reusing the address.

Failed in-place restoration preserves the original name and scopes for a later update retry.
Deleting the current server keeps this snapshot if deletion fails. An update that skips a server
with pending restoration can remain in `UPDATE_COMPLETE_CLEANUP_IN_PROGRESS`, blocking another
update. `ContinueUpdateRollback` remains unsupported.
Failed in-place restoration preserves the original name and scopes for a `ContinueUpdateRollback`
retry. Deleting the current server keeps this snapshot if deletion fails.

## Supported Resource Types

Expand Down Expand Up @@ -467,6 +466,55 @@ was sent gets a `Delete` straight away for the same reason. An update that chang
reaches no handler: it fails with `Modifying service token is not allowed.`, as on AWS, and its
rollback sends nothing.

## Failed update rollbacks

When an update fails, Floci rolls back the resources it changed. A resource whose rollback fails
is left `UPDATE_FAILED`, and the stack settles in `UPDATE_ROLLBACK_FAILED`. As on AWS, `UpdateStack`
and an `UPDATE` change set are then refused with `ValidationError` (`Stack:<arn> is in
UPDATE_ROLLBACK_FAILED state and can not be updated.`). Two ways out remain:

- `DeleteStack` deletes the stack and its resources, the `UPDATE_FAILED` ones included (see
[Deletion Policies](#deletion-policies)).
- `ContinueUpdateRollback` runs the rollback again for the resources still owed one, starting with
an `UPDATE_ROLLBACK_IN_PROGRESS` stack event whose reason is `User Initiated`. A retry re-runs
the restore of each resource still owed one, including the delete of a replacement whose earlier
delete failed; a resource whose restore cannot be redone fails again, leaving the stack in
`UPDATE_ROLLBACK_FAILED`, and can be passed in `ResourcesToSkip`. `ResourcesToSkip` names
`UPDATE_FAILED` resources to report as `UPDATE_COMPLETE` with the reason `Resource skipped
during UpdateRollback`, without rolling them back; a skipped resource keeps the state the failed
update left it in. Once every other resource rolled back, the stack reaches
`UPDATE_ROLLBACK_COMPLETE` with the template, parameters and outputs from before the failed
update, and takes updates again.

`ForceRollback=true` skips every `UPDATE_FAILED` resource of the stack, each reported as a
`ResourcesToSkip` skip is. When a forced rollback skipped a resource and completes, the stack's
`StackStatusReason` and the reason of its `UPDATE_ROLLBACK_COMPLETE` event are `One or more
resources were skipped during UpdateRollback. These resources were not rolled back and may have
drifted from the template. Run drift detection (DetectStackDrift) to review their current state
before your next update.` A rollback completed with `ResourcesToSkip` has no stack reason, as on
AWS.

As on AWS, a malformed `ContinueUpdateRollback` is refused with `ValidationError` before the stack
is looked up, listing every violation: a `StackName` that is missing, empty, or does not match
`[a-zA-Z][-a-zA-Z0-9]*|arn:[-a-zA-Z0-9:/._+]*`, and a `ResourcesToSkip` member that does not
match `[a-zA-Z0-9]+|[a-zA-Z][-a-zA-Z0-9]*\.[a-zA-Z0-9]+`. `ForceRollback=true` with a non-empty
`ResourcesToSkip` is then refused with `ForceRollback and ResourcesToSkip are mutually exclusive`,
a stack that does not exist with `Stack: <StackName> does not exist`, and a stack in any status
other than `UPDATE_ROLLBACK_FAILED` with `RollbackUpdatedStack cannot be called from current stack
status`. `ResourcesToSkip` is checked against the stack after the call is accepted: a skip that is
not a resource of the stack, or not `UPDATE_FAILED`, returns the stack to `UPDATE_ROLLBACK_FAILED`
with the reason, touching no resource, and a later call can still finish the rollback. `RoleARN`
and `ClientRequestToken` are accepted and have no effect.

Known difference: `ResourcesToSkip` does not support a nested stack's resource
(`NestedStackName.ResourceLogicalID`). When the prefix names a nested stack of the stack, the
rollback fails again with a reason saying Floci does not support it, where AWS would skip that
resource.

A stack that reached `UPDATE_ROLLBACK_FAILED` under an earlier Floci version kept no record of its
state before the update. `ContinueUpdateRollback` then retries every `UPDATE_FAILED` resource and
keeps the template the stack holds.

## Deleted Stacks

A deleted stack is kept for a short window afterwards rather than being forgotten at
Expand Down
2 changes: 1 addition & 1 deletion docs/services/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac
| [Secrets Manager](secrets-manager.md) | `POST /` + `X-Amz-Target: secretsmanager.*` | JSON 1.1 | 23 |
| [Step Functions](step-functions.md) | `POST /` + `X-Amz-Target: AmazonStatesService.*` | JSON 1.1 | 32 |
| [SWF](swf.md) | `POST /` + `X-Amz-Target: SimpleWorkflowService.*` | JSON 1.0 | 39 |
| [CloudFormation](cloudformation.md) | `POST /` with `Action=` param | Query | 35 |
| [CloudFormation](cloudformation.md) | `POST /` with `Action=` param | Query | 36 |
| [Cloud Control API](cloudcontrol.md) | `POST /` + `X-Amz-Target: CloudApiService.*` | JSON 1.1 | 5 |
| [EventBridge](eventbridge.md) | `POST /` + `X-Amz-Target: AmazonEventBridge.*` | JSON 1.1 | 40 |
| [EventBridge Scheduler](scheduler.md) | `/schedules/*`, `/schedule-groups/*`, `/tags/*` | REST JSON | 12 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -576,6 +576,7 @@ private Response handleCognitoQuery(String action, MultivaluedMap<String, String

private static final Set<String> CLOUDFORMATION_ACTIONS = Set.of(
"CreateStack", "DeleteStack", "UpdateStack", "DescribeStacks", "UpdateTerminationProtection",
"ContinueUpdateRollback",
"ListStacks", "ListExports", "GetTemplate", "GetTemplateSummary", "ValidateTemplate",
"CreateChangeSet", "DeleteChangeSet", "DescribeChangeSet", "ExecuteChangeSet", "ListChangeSets",
"DescribeStackEvents", "DescribeStackResources", "ListStackResources", "DescribeStackResource",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ public Response handle(String action, MultivaluedMap<String, String> params, Str
case "CreateStack" -> createStack(params, region);
case "UpdateStack" -> updateStack(params, region);
case "DeleteStack" -> deleteStack(params, region);
case "ContinueUpdateRollback" -> continueUpdateRollback(params, region);
case "UpdateTerminationProtection" -> updateTerminationProtection(params, region);
case "CreateChangeSet" -> createChangeSet(params, region);
case "DescribeChangeSet" -> describeChangeSet(params, region);
Expand Down Expand Up @@ -189,6 +190,28 @@ private Response deleteStack(MultivaluedMap<String, String> params, String regio
}
}

// ── ContinueUpdateRollback ───────────────────────────────────────────────

private Response continueUpdateRollback(MultivaluedMap<String, String> params, String region) {
String stackName = params.getFirst("StackName");
List<String> resourcesToSkip = extractList(params, "ResourcesToSkip.member.");
Comment thread
mariotoffia marked this conversation as resolved.
Resolved
boolean forceRollback = Boolean.parseBoolean(params.getFirst("ForceRollback"));
// RoleARN and ClientRequestToken are accepted and have no effect: Floci assumes no role
// for stack operations and does not deduplicate retried requests.
try {
cfnService.continueUpdateRollback(stackName, resourcesToSkip, forceRollback, region);
} catch (AwsException e) {
return xmlError(e.getErrorCode(), e.getMessage(), e.getHttpStatus());
}
String xml = new XmlBuilder()
.start("ContinueUpdateRollbackResponse", CF_NS)
.raw("<ContinueUpdateRollbackResult/>")
.raw(AwsQueryResponse.responseMetadata())
.end("ContinueUpdateRollbackResponse")
.build();
return Response.ok(xml).type("text/xml").build();
}

// ── UpdateTerminationProtection ─────────────────────────────────────────────

private Response updateTerminationProtection(MultivaluedMap<String, String> params, String region) {
Expand Down Expand Up @@ -450,6 +473,7 @@ private Response describeStackResource(MultivaluedMap<String, String> params, St
.elem("PhysicalResourceId", res.getPhysicalId())
.elem("ResourceType", res.getResourceType())
.elem("ResourceStatus", res.getStatus())
.elem("ResourceStatusReason", res.getStatusReason())
.elem("LastUpdatedTimestamp", ISO.format(res.getTimestamp()))
.end("StackResourceDetail")
.end("DescribeStackResourceResult")
Expand Down
Loading
Loading