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
31 changes: 29 additions & 2 deletions docs/services/cloudformation.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,31 @@ an atomic ownership check against another stack or a direct Cognito API writer r
Failed in-place restoration preserves the original name and scopes for a `ContinueUpdateRollback`
retry. Deleting the current server keeps this snapshot if deletion fails.

## SSM parameters

Like AWS's resource handler, `AWS::SSM::Parameter` is created with one `PutParameter` that carries
the template's tags and does not overwrite. A name that already exists outside the stack fails the
resource with `ParameterAlreadyExists`; the stack never overwrites, adopts or deletes that
parameter. Floci applies the `Name`, `Type`, `Value` and `Tags` properties.

An update that keeps `Name` overwrites the parameter. When a later resource fails the update, the
rollback writes the prior value and settings back, as a new SSM version when they changed (the
version history is not rewound, as on AWS), and returns the tags the previous or the failed
template set to their prior values; other tags are left alone. As on AWS, the update first checks
that the parameter exists: one deleted outside the stack fails it with `ParameterNotFound` before
anything is written. A rollback that finds the parameter gone fails the same way, leaving the stack
in `UPDATE_ROLLBACK_FAILED`.

Giving `Name` a new value replaces the parameter. The previous parameter stays until the update
commits, and is then deleted unless `UpdateReplacePolicy` is `Retain`; a failed update deletes the
replacement instead. A restore or delete that fails during the rollback leaves the stack in
`UPDATE_ROLLBACK_FAILED`, and `ContinueUpdateRollback` retries it (see
[Failed update rollbacks](#failed-update-rollbacks)). Deleting a parameter that is already gone
counts as deleted. Known differences: removing an explicit `Name` keeps the parameter under that
name, where AWS replaces it with one under a generated name; and an update in place of a parameter
deleted outside the stack ends in `UPDATE_ROLLBACK_COMPLETE`, since nothing was written, where AWS's
rollback repeats the existence check and likely ends in `UPDATE_ROLLBACK_FAILED`.

## Supported Resource Types

Resource types provisioned during `CreateStack` / `UpdateStack` / `DeleteStack`. Each delegates to
Expand Down Expand Up @@ -628,8 +653,10 @@ Deviations from AWS to be aware of:
removals as well.
- After `DeleteStack` completes, a retained resource's `DELETE_SKIPPED` record is only visible
through `DescribeStackEvents` for the deleted stack, not `DescribeStackResources`.
- `UpdateReplacePolicy`, and the `RetainExceptOnCreate` request parameter of `CreateStack` /
`UpdateStack`, are not implemented.
- `UpdateReplacePolicy` is honored only by the resource types that delete a displaced resource once
the update commits, such as an SSM parameter or a log stream; other types keep the displaced
resource, or delete it during the update, whatever the policy. The `RetainExceptOnCreate` request
parameter of `CreateStack` / `UpdateStack` is not implemented.

## StackSets

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,14 @@ public final class CfnRollback {
*/
public static final String SQS_UPDATE_SNAPSHOT_ATTR = "__FlociSqsUpdateSnapshot";

/**
* Holds the value, settings and managed tags an SSM parameter carried before an in-place
* update changed them, with the resource's attributes from before, so a failed stack update
* can put them back. Written by {@code SsmCfnProvisioner} before its put and spent by its
* {@code rollbackUpdate}; a rename leaves its rollback to {@link #REPLACEMENT_CLEANUP_ATTR}.
*/
public static final String SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR = "__FlociSsmParameterUpdateSnapshot";

/**
* Holds the settings a Cognito user pool or user pool client had before an in-place update
* changed them, so a failed stack update can put them back. Written by
Expand Down
Original file line number Diff line number Diff line change
@@ -1,23 +1,43 @@
package io.github.hectorvent.floci.services.cloudformation.provisioners;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import io.github.hectorvent.floci.core.common.AwsArnUtils;
import io.github.hectorvent.floci.services.cloudformation.model.StackResource;
import io.github.hectorvent.floci.services.ssm.SsmService;
import io.github.hectorvent.floci.services.ssm.model.Parameter;
import jakarta.enterprise.context.ApplicationScoped;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.TreeSet;

/** Provisions {@code AWS::SSM::Parameter}. */
/**
* Provisions {@code AWS::SSM::Parameter}. The parameter name is the physical id and {@code Ref}.
*
* <p>A create, and the replacement a changed name makes, is one {@code PutParameter} that carries
* the template's tags and does not overwrite, as AWS's handler sends it: a name that already exists
* outside the stack fails the resource instead of being overwritten or adopted. An update that keeps
* the name overwrites the parameter and drives the template's tags, after keeping what it changes on
* the resource, so a failed stack update can put it back. A replacement leaves the displaced
* parameter to the {@link ReplacementCleanup} record: deleted once the update commits, unless
* {@code UpdateReplacePolicy} is {@code Retain}, and named again when the update rolls back.
*/
@ApplicationScoped
public class SsmCfnProvisioner implements CfnResourceProvisioner {

private static final int PARAMETER_NAME_MAX_LENGTH = 2048;
private static final String SSM_TEMPLATE_TAG_KEYS_ATTR = "FlociSsmTemplateTagKeys";
private static final ObjectMapper MAPPER = new ObjectMapper();

private final SsmService ssmService;

Expand All @@ -32,6 +52,14 @@ public Set<String> resourceTypes() {

@Override
public void provision(StackResource r, JsonNode props, ProvisionContext ctx) {
// A snapshot describes the update in flight; one an earlier update left behind is stale.
r.getAttributes().remove(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR);
if (ctx.isUpdate()) {
// Rolling this update back undoes it alone; only ContinueUpdateRollback retries the
// delete the last rollback could not make.
ReplacementCleanup.endRollbackRetry(r);
}
Map<String, String> attributesBefore = new HashMap<>(r.getAttributes());
String name = ctx.stablePhysicalName(ctx.resolveOptional(props, "Name"),
r.getLogicalId(), PARAMETER_NAME_MAX_LENGTH, false);
String value = ctx.resolveOptional(props, "Value");
Expand All @@ -44,8 +72,14 @@ public void provision(StackResource r, JsonNode props, ProvisionContext ctx) {
}
Map<String, String> tags = ctx.resolveTags(props, "Tags");
SsmService.validateTagKeys(tags);
ssmService.putParameter(name, value, type, null, true, ctx.region());
reconcileTags(name, r.getAttributes().get(SSM_TEMPLATE_TAG_KEYS_ATTR), tags, ctx.region());
// A dispatcher stub created nothing, so a parameter that takes over its id is a create.
if (ctx.reusesPriorEntity(name) && !CfnResourceDispatcher.isStub(name, attributesBefore)) {
snapshotBeforeUpdate(r, name, attributesBefore, tags.keySet(), ctx.region());
ssmService.putParameter(name, value, type, null, true, ctx.region());
reconcileTags(name, templateTagKeys(attributesBefore), tags, ctx.region());
} else {
ssmService.putParameter(name, value, type, null, false, tags, ctx.region());
}
r.setPhysicalId(name);
r.getAttributes().put("Name", name);
r.getAttributes().put("Type", type);
Expand All @@ -57,21 +91,62 @@ public void provision(StackResource r, JsonNode props, ProvisionContext ctx) {
} else {
r.getAttributes().put(SSM_TEMPLATE_TAG_KEYS_ATTR, String.join(",", new TreeSet<>(tags.keySet())));
}
ReplacementCleanup.record(r, ctx, attributesBefore);
}

/**
* Applies the template's tags and removes only the keys the previous template set and this one
* drops, so a tag added outside the template stays, as in AWS. The overwriting put keeps the
* parameter's existing tags, and a parameter provisioned before the keys were recorded has none
* to drop.
* Keeps what an update in place is about to change, so {@link #rollbackUpdate} can put it back:
* the parameter's value and settings, the tags of the keys the previous template or this one
* manages, and the resource's attributes. Reading it first also fails the update of a parameter
* deleted outside the stack with {@code ParameterNotFound} before anything is written, as AWS's
* handler checks that the parameter exists.
*/
private void reconcileTags(String name, String previousTemplateKeys, Map<String, String> desired,
private void snapshotBeforeUpdate(StackResource r, String name, Map<String, String> attributesBefore,
Set<String> desiredTagKeys, String region) {
ObjectNode snapshot = MAPPER.createObjectNode();
snapshot.put("region", region);
snapshot.put("name", name);
ObjectNode attributes = snapshot.putObject("attributes");
attributesBefore.forEach((key, attribute) -> {
if (!key.startsWith("__Floci") && attribute != null) {
attributes.put(key, attribute);
}
});
Parameter current = ssmService.getParameter(name, region);
snapshot.put("value", current.getValue());
snapshot.put("type", current.getType());
snapshot.put("description", current.getDescription());
snapshot.put("keyId", current.getKeyId());
snapshot.put("allowedPattern", current.getAllowedPattern());
snapshot.put("tier", current.getTier());
if (current.getPolicies() != null) {
snapshot.putArray("policies").addAll(current.getPolicies());
}
// A managed key the parameter did not carry is listed without a value, so the rollback removes it.
Set<String> managedKeys = new TreeSet<>(templateTagKeys(attributesBefore));
managedKeys.addAll(desiredTagKeys);
Map<String, String> currentTags = current.getTags() == null ? Map.of() : current.getTags();
ArrayNode tagKeys = snapshot.putArray("tagKeys");
ObjectNode tags = snapshot.putObject("tags");
for (String key : managedKeys) {
tagKeys.add(key);
if (currentTags.containsKey(key)) {
tags.put(key, currentTags.get(key));
}
}
r.getAttributes().put(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR, snapshot.toString());
}

/**
* Applies {@code desired} and removes the {@code managedKeys} it does not hold, so a tag added
* outside the template stays, as in AWS. The overwriting put keeps the parameter's existing tags,
* and a parameter provisioned before the keys were recorded has none to drop.
*/
private void reconcileTags(String name, Collection<String> managedKeys, Map<String, String> desired,
String region) {
List<String> dropped = previousTemplateKeys == null || previousTemplateKeys.isEmpty()
? List.of()
: Arrays.stream(previousTemplateKeys.split(","))
.filter(key -> !desired.containsKey(key))
.toList();
List<String> dropped = managedKeys.stream()
.filter(key -> !desired.containsKey(key))
.toList();
if (!dropped.isEmpty()) {
ssmService.removeTagsFromResource(name, dropped, region);
}
Expand All @@ -80,6 +155,12 @@ private void reconcileTags(String name, String previousTemplateKeys, Map<String,
}
}

/** The tag keys the template that provisioned the resource set. */
private static List<String> templateTagKeys(Map<String, String> attributes) {
String keys = attributes.get(SSM_TEMPLATE_TAG_KEYS_ATTR);
return keys == null || keys.isEmpty() ? List.of() : Arrays.asList(keys.split(","));
}

/** AWS's form is {@code parameter/<name>} whether or not the name starts with a slash. */
private static String parameterArn(String name, ProvisionContext ctx) {
String path = name.startsWith("/") ? name : "/" + name;
Expand All @@ -88,6 +169,111 @@ private static String parameterArn(String name, ProvisionContext ctx) {

@Override
public void delete(String resourceType, String physicalId, String region) {
ssmService.deleteParameter(physicalId, region);
// ParameterNotFound is SSM's own code for a parameter that is already gone.
CfnDeletes.safeDelete("SSM parameter", physicalId,
() -> ssmService.deleteParameter(physicalId, region), "ParameterNotFound");
}

/**
* An update in place that failed after its snapshot may already have changed the parameter, so
* the engine keeps this attempt for {@link #rollbackUpdate} instead of putting the previous
* resource back over it. A failure before the snapshot changed nothing and is left to the engine.
*/
@Override
public boolean retainsFailedUpdateState(StackResource resource) {
return resource.getAttributes().containsKey(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR);
}

@Override
public boolean hasReplacementUpdate(StackResource resource) {
return ReplacementCleanup.hasReplacement(resource);
}

@Override
public String updateCleanupPhysicalId(StackResource resource) {
return ReplacementCleanup.cleanupPhysicalId(resource);
}

/**
* The engine calls this for every resource once a stack update commits, but {@link #clearUpdate}
* only after a replacement's cleanup, so an in-place update's snapshot is dropped here: the update
* committed and nothing will roll it back.
*/
@Override
public UpdateCleanupResult completeUpdate(StackResource resource) {
resource.getAttributes().remove(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR);
return ReplacementCleanup.complete(resource, this::delete);
}

@Override
public void clearUpdate(StackResource resource) {
resource.getAttributes().remove(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR);
ReplacementCleanup.clear(resource);
}

/**
* A replacement is undone through the cleanup record, and an update in place from the snapshot
* taken before it. Like AWS's rollback, which runs its update handler, the restore needs the
* parameter to exist: one deleted outside the stack fails it with {@code ParameterNotFound}. The
* value and settings go back with one overwrite, which SSM keeps as a new version, unless the
* parameter already holds them; the managed tags go back to the values they had, and the resource
* gets back the attributes it had. The snapshot is spent only once the restore succeeded, so a
* restore that throws leaves it for ContinueUpdateRollback to retry. With neither on the resource
* there is nothing to restore from.
*/
@Override
public boolean rollbackUpdate(StackResource resource) {
if (ReplacementCleanup.rollback(resource, this::delete)) {
return true;
}
String raw = resource.getAttributes().get(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR);
if (raw == null) {
return false;
}
JsonNode snapshot;
try {
snapshot = MAPPER.readTree(raw);
} catch (JsonProcessingException e) {
throw new IllegalStateException("Could not read the SSM parameter update snapshot for "
+ resource.getLogicalId(), e);
}
String region = snapshot.path("region").asText();
String name = snapshot.path("name").asText();
restore(ssmService.getParameter(name, region), snapshot, name, region);
resource.getAttributes().keySet().removeIf(key -> !key.startsWith("__Floci"));
snapshot.path("attributes").properties()
.forEach(attribute -> resource.getAttributes().put(attribute.getKey(), attribute.getValue().asText()));
resource.getAttributes().remove(CfnRollback.SSM_PARAMETER_UPDATE_SNAPSHOT_ATTR);
return true;
}

/** Puts the snapshot's value, settings and managed tags back on the parameter. */
private void restore(Parameter current, JsonNode snapshot, String name, String region) {
String value = snapshot.path("value").asText();
String type = snapshot.path("type").textValue();
String description = snapshot.path("description").textValue();
String keyId = snapshot.path("keyId").textValue();
String allowedPattern = snapshot.path("allowedPattern").textValue();
String tier = snapshot.path("tier").textValue();
List<JsonNode> policies = null;
if (snapshot.has("policies")) {
policies = new ArrayList<>();
snapshot.path("policies").forEach(policies::add);
}
boolean unchanged = value.equals(current.getValue()) && Objects.equals(type, current.getType())
&& Objects.equals(description, current.getDescription())
&& Objects.equals(keyId, current.getKeyId())
&& Objects.equals(allowedPattern, current.getAllowedPattern())
&& Objects.equals(tier, current.getTier())
&& Objects.equals(policies, current.getPolicies());
Comment on lines +263 to +268

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

2. Rollback can write a needless extra ssm version 🐞 Bug ≡ Correctness

restore compares the snapshot's tier field directly against current.getTier() via
Objects.equals, but storeParameter normalizes a missing tier to the default (tierOf(existing)
or "Standard") when writing, so a parameter stored before Floci tracked a tier has a null tier in
the live Parameter object while the snapshot may hold the normalized string, or vice versa
depending on when the snapshot was taken. This makes unchanged false when the parameter actually
holds the same effective settings, causing the rollback to call putParameter and bump the SSM
version even though nothing meaningfully changed, which contradicts the documented behavior that a
restore that already holds the prior values does not write a new version.
Agent Prompt
## Issue description
The `unchanged` check in `restore` compares the snapshot's `tier` (and similarly `keyId` for SecureString) directly against the live parameter's raw field, without applying the same normalization `SsmService.storeParameter` applies when persisting (`tierOf`, `keyIdOf`). This can make the check report a difference when none effectively exists, causing an unnecessary new SSM version to be written during rollback.

## Fix Focus Areas
- src/main/java/io/github/hectorvent/floci/services/cloudformation/provisioners/SsmCfnProvisioner.java[263-268]

## Recommended Fix
Before comparing, normalize both sides using `SsmService.tierOf`/`SsmService.keyIdOf` (or equivalent accessible helpers) so the comparison reflects the same defaulting logic used when the parameter was originally stored, avoiding spurious version bumps on an otherwise no-op restore.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

if (!unchanged) {
ssmService.putParameter(name, value, type, description, true, null, keyId, allowedPattern, tier,
policies, region);
Comment on lines +270 to +271

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

1. Rollback leaves added parameter policies 🐞 Bug ≡ Correctness

restore passes null for policies when the snapshot had none, but SsmService.putParameter
interprets null as an instruction to preserve the current policies. If a direct SSM write adds
policies after the snapshot and before rollback, the rollback completes with those policies still
present and discards the snapshot.
Agent Prompt
## Issue description
Rollback cannot restore a parameter's prior absence of policies because a null policies argument preserves the current policies.
## Fix Focus Areas
- src/main/java/io/github/hectorvent/floci/services/cloudformation/provisioners/SsmCfnProvisioner.java[258-271]
- src/main/java/io/github/hectorvent/floci/services/ssm/SsmService.java[280-286]
## Recommended Fix
When the snapshot has no policies and the current parameter has some, pass an empty policies list to `putParameter` so SSM clears them. Add a rollback test where a direct SSM write adds policies after the snapshot.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

}
List<String> managedKeys = new ArrayList<>();
snapshot.path("tagKeys").forEach(key -> managedKeys.add(key.asText()));
Map<String, String> tags = new HashMap<>();
snapshot.path("tags").properties().forEach(tag -> tags.put(tag.getKey(), tag.getValue().asText()));
reconcileTags(name, managedKeys, tags, region);
}
}
Loading
Loading