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
10 changes: 10 additions & 0 deletions docs/services/cloudformation.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,16 @@ references in `MasterUsername` and `MasterUserPassword` during resource creation

Dynamic-reference expansion is currently scoped to these RDS credential properties.

## RDS Associated Roles

`AWS::RDS::DBCluster` and `AWS::RDS::DBInstance` apply `AssociatedRoles` through the same checks as
`AddRoleToDBCluster` / `AddRoleToDBInstance` (see [RDS IAM role associations](rds.md#iam-role-associations)):

- `Fn::If` may select the whole list or a single entry, and `AWS::NoValue` leaves it out. A value that is not a list of roles is a `ValidationError`.
- On create, the roles are associated with the new cluster or instance. A list RDS refuses (a missing `RoleArn`, an instance role without `FeatureName`, or a cluster role named twice) fails the resource, and the new database is deleted again. As in AWS, an instance role or feature the list repeats is skipped, not refused. A renamed instance keeps its predecessor until the new one has its roles.
- On `UpdateStack` (no interruption, as in AWS), a cluster's list is checked first, then the roles the template gained are added, and the roles the previous template declared and the new one drops are removed. A role associated outside the stack is kept while the template leaves it out; declaring it fails the update with `DBClusterRoleAlreadyExists`, as in AWS. If any step of an update is refused, the roles it already added are removed and the ones it removed are put back, so the database matches what the stack still records and a retry starts from there. A rolled-back cluster replacement restores the record of which roles the stack declared.
- An Aurora cluster member (`AWS::RDS::DBInstance` with `DBClusterIdentifier`) cannot carry `AssociatedRoles`: the schema documents the property as not applicable there, since the cluster manages its roles. The resource fails with a `ValidationError` pointing at the cluster's `AssociatedRoles`.

## Account-Aware Provisioning

Resources provisioned by `CreateStack` / `UpdateStack` land in the **caller's account** namespace
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
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.AwsException;
import io.github.hectorvent.floci.services.cloudformation.CloudFormationTemplateEngine;
Expand All @@ -14,6 +16,7 @@
import io.github.hectorvent.floci.services.rds.model.DbProxy;
import io.github.hectorvent.floci.services.rds.model.DbProxyAuth;
import io.github.hectorvent.floci.services.rds.model.DbProxyTargetGroup;
import io.github.hectorvent.floci.services.rds.model.DbRoleAssociation;
import io.github.hectorvent.floci.services.rds.model.DbSubnetGroup;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
Expand Down Expand Up @@ -85,6 +88,18 @@ public class RdsCfnProvisioner implements CfnResourceProvisioner {
*/
static final String DB_CLUSTER_CREATE_ONLY_PRIOR_ATTR = "__FlociDbClusterCreateOnlyPrior";

/**
* The {@code AssociatedRoles} the template declared at the last successful provision, a JSON
* array of {@code {RoleArn, FeatureName}}. An update removes only roles this record names and
* the template no longer does, so a role associated outside the stack is left in place.
*/
static final String ASSOCIATED_ROLES_ATTR = "__FlociAssociatedRoles";
/**
* The roles record an update overwrote, kept until the update commits so a rollback that puts
* the prior cluster back puts its record back too; an empty value means there was none.
*/
static final String ASSOCIATED_ROLES_PRIOR_ATTR = "__FlociAssociatedRolesPrior";

private final RdsService rdsService;
private final CfnDynamicReferences dynamicReferences;

Expand Down Expand Up @@ -163,6 +178,7 @@ public UpdateCleanupResult completeUpdate(StackResource resource) {
@Override
public void clearUpdate(StackResource resource) {
resource.getAttributes().remove(DB_CLUSTER_CREATE_ONLY_PRIOR_ATTR);
resource.getAttributes().remove(ASSOCIATED_ROLES_PRIOR_ATTR);
ReplacementCleanup.clear(resource);
}

Expand All @@ -184,6 +200,14 @@ public boolean rollbackUpdate(StackResource resource) {
resource.getAttributes().put(DB_CLUSTER_CREATE_ONLY_ATTR, priorRecord);
}
}
String priorRoles = resource.getAttributes().remove(ASSOCIATED_ROLES_PRIOR_ATTR);
if (priorRoles != null) {
if (priorRoles.isEmpty()) {
resource.getAttributes().remove(ASSOCIATED_ROLES_ATTR);
} else {
resource.getAttributes().put(ASSOCIATED_ROLES_ATTR, priorRoles);
}
}
return replaced;
}

Expand Down Expand Up @@ -315,7 +339,16 @@ private void provisionDbInstance(StackResource r, JsonNode props, CloudFormation
// threading them through an UpdateStack is a separate change: DBInstanceClass and
// AllocatedStorage are update-in-place on the AWS::RDS::DBInstance schema while Engine is
// create-only, so passing them needs the replacement handling the DB cluster arm has.
List<DbRoleAssociation> roles = parseAssociatedRoles(props, engine);
String clusterMember = resolveOptional(props, "DBClusterIdentifier", engine);
if (!roles.isEmpty() && clusterMember != null && !clusterMember.isBlank()) {
// The schema: "Amazon Aurora: Not applicable. The associated roles are managed by the DB cluster."
throw new AwsException("ValidationError", "AssociatedRoles is not applicable to DB instance " + id
+ ", a member of DB cluster " + clusterMember
+ "; set AssociatedRoles on the AWS::RDS::DBCluster instead.", 400);
}
DbInstance instance = sameNameExistingResource(priorPhysicalId, id, rdsService::getDbInstance);
boolean created = instance == null;
if (instance != null) {
instance = rdsService.modifyDbInstance(
id,
Expand All @@ -337,6 +370,11 @@ private void provisionDbInstance(StackResource r, JsonNode props, CloudFormation
resolveOptional(props, "DBSubnetGroupName", engine),
resolveOptional(props, "DBClusterIdentifier", engine),
null, false, false, null, Map.of(), region);
}
// The roles go on before a renamed instance's predecessor is deleted, so a refused list
// deletes only the new instance and the stack still has the old one to roll back to.
instance = reconcileInstanceRoles(r, instance, roles, created, ctx.isUpdate(), region);
if (created) {
deleteRenamedResource(priorPhysicalId, id, rdsService::deleteDbInstance, "DB instance");
}
r.setPhysicalId(instance.getDbInstanceIdentifier());
Expand Down Expand Up @@ -400,6 +438,11 @@ private void provisionDbCluster(StackResource r, JsonNode props, CloudFormationT
LOG.infov("Replacing DB cluster {0} with {1}: {2}", priorPhysicalId, id, replacementReason);
cluster = null;
}
List<DbRoleAssociation> roles = parseAssociatedRoles(props, engine);
if (!roles.isEmpty()) {
rdsService.validateClusterRoleAssociations(id, resolveOptional(props, "Engine", engine), roles);
}
boolean created = cluster == null;
if (cluster != null) {
cluster = rdsService.modifyDbCluster(
id,
Expand All @@ -426,6 +469,7 @@ private void provisionDbCluster(StackResource r, JsonNode props, CloudFormationT
serverlessV2MinCapacity, serverlessV2MaxCapacity, serverlessV2SecondsUntilAutoPause,
false, null, engineMode, storageEncrypted);
}
cluster = reconcileClusterRoles(r, cluster, roles, created, ctx.isUpdate(), region);
r.setPhysicalId(cluster.getDbClusterIdentifier());
r.getAttributes().put("DBClusterIdentifier", cluster.getDbClusterIdentifier());
if (cluster.getEndpoint() != null) {
Expand All @@ -447,6 +491,241 @@ private void provisionDbCluster(StackResource r, JsonNode props, CloudFormationT
ReplacementCleanup.record(r, ctx, attributesBefore);
}

/**
* The template's {@code AssociatedRoles}, in order, with {@code Fn::If} resolved around the list
* and its entries. An absent property, or one that resolves to {@code AWS::NoValue}, is an empty
* list; any other value that is not a list of objects is a {@code ValidationError}, so a
* malformed property never reads as "no roles" and removes the ones the stack declared.
*/
private List<DbRoleAssociation> parseAssociatedRoles(JsonNode props, CloudFormationTemplateEngine engine) {
List<DbRoleAssociation> roles = new ArrayList<>();
if (props == null || !props.has("AssociatedRoles")) {
return roles;
}
JsonNode list = engine.resolveNodeOmittingNoValue(props.get("AssociatedRoles"));
if (list == null || list.isMissingNode()) {
return roles;
}
if (!list.isArray()) {
throw new AwsException("ValidationError", "AssociatedRoles must be a list of roles.", 400);
}
for (JsonNode role : list) {
if (role == null || role.isMissingNode()) {
continue;
}
if (!role.isObject()) {
throw new AwsException("ValidationError",
"Each AssociatedRoles entry must be an object with a RoleArn.", 400);
}
roles.add(new DbRoleAssociation(textOrNull(role.get("RoleArn")), textOrNull(role.get("FeatureName"))));
}
return roles;
}

private static String textOrNull(JsonNode node) {
return node == null || node.isNull() || node.isMissingNode() ? null : node.asText();
}

/**
* Brings a cluster's roles in line with the template. A new cluster takes them all in one step,
* and is deleted again if they are refused, so a failed resource leaves no cluster behind. On an
* update the roles the last template declared and this one does not are removed, and the ones
* this template adds are associated.
*/
private DbCluster reconcileClusterRoles(StackResource r, DbCluster cluster, List<DbRoleAssociation> roles,
boolean created, boolean update, String region) {
String id = cluster.getDbClusterIdentifier();
if (created) {
if (!roles.isEmpty()) {
try {
cluster = rdsService.addRolesToNewDbCluster(region, id, roles);
} catch (AwsException e) {
CfnDeletes.safeDelete("DB cluster", id, () -> rdsService.deleteDbCluster(id, region),
"DBClusterNotFoundFault");
throw e;
}
}
} else {
List<DbRoleAssociation> removed = new ArrayList<>();
List<DbRoleAssociation> added = new ArrayList<>();
try {
List<DbRoleAssociation> current = cluster.getAssociatedRoles();
for (DbRoleAssociation dropped : droppedRoles(r, roles)) {
if (containsRole(current, dropped)) {
cluster = rdsService.removeRoleFromDbCluster(region, id, dropped.getRoleArn(),
dropped.getFeatureName());
removed.add(dropped);
}
}
// A role the last template already declared is left as it is. One the template newly
// declares is always added, so a role attached by hand first fails the update with
// DBClusterRoleAlreadyExists, as it does on AWS.
List<DbRoleAssociation> declared = readAssociatedRoles(r.getAttributes().get(ASSOCIATED_ROLES_ATTR));
for (DbRoleAssociation role : roles) {
if (!containsRole(declared, role) || !containsRole(cluster.getAssociatedRoles(), role)) {
cluster = rdsService.addRoleToDbCluster(region, id, role.getRoleArn(), role.getFeatureName());
added.add(role);
}
}
} catch (AwsException e) {
undoClusterRoleChanges(id, region, added, removed);
throw e;
}
}
recordAssociatedRoles(r, roles, update);
return cluster;
}

/** As {@link #reconcileClusterRoles}, for an instance; each role is added on its own. */
private DbInstance reconcileInstanceRoles(StackResource r, DbInstance instance, List<DbRoleAssociation> roles,
boolean created, boolean update, String region) {
String id = instance.getDbInstanceIdentifier();
if (created) {
try {
for (DbRoleAssociation role : roles) {
instance = addInstanceRole(instance, id, role, region);
}
} catch (AwsException e) {
rdsService.deleteDbInstance(id, region);
throw e;
}
} else {
List<DbRoleAssociation> removed = new ArrayList<>();
List<DbRoleAssociation> added = new ArrayList<>();
try {
List<DbRoleAssociation> current = instance.getAssociatedRoles();
for (DbRoleAssociation dropped : droppedRoles(r, roles)) {
if (containsRole(current, dropped)) {
instance = rdsService.removeRoleFromDbInstance(region, id, dropped.getRoleArn(),
dropped.getFeatureName());
removed.add(dropped);
}
}
for (DbRoleAssociation role : roles) {
if (!containsRole(instance.getAssociatedRoles(), role)) {
instance = addInstanceRole(instance, id, role, region);
if (containsRole(instance.getAssociatedRoles(), role)) {
added.add(role);
}
}
}
} catch (AwsException e) {
undoInstanceRoleChanges(id, region, added, removed);
throw e;
}
}
recordAssociatedRoles(r, roles, update);
return instance;
}

/**
* Puts a cluster's roles back as they were before a failed update: the roles it added are
* removed and the ones it removed are added again, so the cluster matches the record the stack
* restores and a retry starts from there. A step that fails here is logged and the rest go on,
* so the original refusal is what the stack reports.
*/
private void undoClusterRoleChanges(String id, String region, List<DbRoleAssociation> added,
List<DbRoleAssociation> removed) {
for (DbRoleAssociation role : added) {
undoStep(() -> rdsService.removeRoleFromDbCluster(region, id, role.getRoleArn(), role.getFeatureName()),
"remove", role, "DB cluster", id);
}
for (DbRoleAssociation role : removed) {
undoStep(() -> rdsService.addRoleToDbCluster(region, id, role.getRoleArn(), role.getFeatureName()),
"restore", role, "DB cluster", id);
}
}

/** As {@link #undoClusterRoleChanges}, for an instance. */
private void undoInstanceRoleChanges(String id, String region, List<DbRoleAssociation> added,
List<DbRoleAssociation> removed) {
for (DbRoleAssociation role : added) {
undoStep(() -> rdsService.removeRoleFromDbInstance(region, id, role.getRoleArn(), role.getFeatureName()),
"remove", role, "DB instance", id);
}
for (DbRoleAssociation role : removed) {
undoStep(() -> rdsService.addRoleToDbInstance(region, id, role.getRoleArn(), role.getFeatureName()),
"restore", role, "DB instance", id);
}
}

private static void undoStep(Runnable step, String verb, DbRoleAssociation role, String kind, String id) {
try {
step.run();
} catch (AwsException e) {
LOG.warnv("Could not {0} role {1} on {2} {3} while undoing a failed update: {4}",
verb, role.getRoleArn(), kind, id, e.getMessage());
}
}

/**
* Associates one instance role. AWS's {@code AWS::RDS::DBInstance} handler ignores
* {@code DBInstanceRoleAlreadyExists}, so a role or feature the list repeats, or one already on
* the instance, is skipped rather than failing the resource.
*/
private DbInstance addInstanceRole(DbInstance instance, String id, DbRoleAssociation role, String region) {
try {
return rdsService.addRoleToDbInstance(region, id, role.getRoleArn(), role.getFeatureName());
} catch (AwsException e) {
if ("DBInstanceRoleAlreadyExists".equals(e.getErrorCode())) {
return instance;
}
throw e;
}
}

/** The roles the last template declared that this one does not. */
private static List<DbRoleAssociation> droppedRoles(StackResource r, List<DbRoleAssociation> roles) {
List<DbRoleAssociation> dropped = new ArrayList<>();
for (DbRoleAssociation previous : readAssociatedRoles(r.getAttributes().get(ASSOCIATED_ROLES_ATTR))) {
if (!containsRole(roles, previous)) {
dropped.add(previous);
}
}
return dropped;
}

/** Whether {@code roles} holds {@code role}: the same RoleArn for the same feature, or both without one. */
private static boolean containsRole(List<DbRoleAssociation> roles, DbRoleAssociation role) {
return roles.stream().anyMatch(candidate -> Objects.equals(candidate.getRoleArn(), role.getRoleArn())
&& Objects.equals(blankToNull(candidate.getFeatureName()), blankToNull(role.getFeatureName())));
}

private static String blankToNull(String value) {
return value == null || value.isBlank() ? null : value;
}

private static void recordAssociatedRoles(StackResource r, List<DbRoleAssociation> roles, boolean update) {
String priorRecord = r.getAttributes().get(ASSOCIATED_ROLES_ATTR);
if (update && !r.getAttributes().containsKey(ASSOCIATED_ROLES_PRIOR_ATTR)) {
r.getAttributes().put(ASSOCIATED_ROLES_PRIOR_ATTR, priorRecord == null ? "" : priorRecord);
}
ArrayNode record = MAPPER.createArrayNode();
for (DbRoleAssociation role : roles) {
ObjectNode entry = record.addObject().put("RoleArn", role.getRoleArn());
if (blankToNull(role.getFeatureName()) != null) {
entry.put("FeatureName", role.getFeatureName());
}
}
r.getAttributes().put(ASSOCIATED_ROLES_ATTR, record.toString());
}

private static List<DbRoleAssociation> readAssociatedRoles(String raw) {
List<DbRoleAssociation> roles = new ArrayList<>();
if (raw == null || raw.isBlank()) {
return roles;
}
try {
for (JsonNode entry : MAPPER.readTree(raw)) {
roles.add(new DbRoleAssociation(entry.path("RoleArn").asText(null),
entry.path("FeatureName").asText(null)));
}
} catch (JsonProcessingException e) {
LOG.warnv("Ignoring unreadable AssociatedRoles record: {0}", raw);
}
return roles;
}

/**
* Why the template's createOnly properties call for a replacement of the cluster on file, or
* null when they describe it. {@code EngineMode}, {@code StorageEncrypted} and
Expand Down
Loading
Loading