Superblocks Database Reference

This page is a reference for the full lifecycle of an app database: what exists at each stage, what it is named, and which IAM role is allowed to act on it. For initial setup, start with Setup. For what the feature does for builders, see Superblocks Database. For the trust boundaries and network paths behind these details, see Security model.

One-time setup

One-time setup is a single Terraform module, modules/app-db-prereqs, recommended for every deployment. It creates IAM roles, policies, and an S3 bucket for storing OpenTofu state.

module "app_db_prereqs" {
  source  = "superblocksteam/superblocks/aws//modules/app-db-prereqs"
  version = ">= 1.5.3, < 2.0.0"

  deployment_type = "fargate" # or "eks"
  region          = "<REGION>"

  # One entry per data plane. The map key is the agent name.
  agents = {
    "<AGENT_NAME>" = {
      agent_tags = ["<DATA_TAG_1>"]
      vpc_id     = "<VPC_ID>"
    }
  }
}

Run it once per region, declaring every data plane in that region in the same agents map so they share one state bucket. For the walkthrough that wires its outputs into Fargate or Helm, see Setup: Step 1.

Resources created

Resource	Default name	Purpose
Lifecycle worker IAM role, plus seven policies	`sb-app-db-<AGENT_NAME>-lifecycle-worker-<REGION>`	To provision and modify only the resources Superblocks tagged, in the VPC you declared. See Raw IAM policy JSON
Connector IAM role, plus its policy	`superblocks-app-db-connector-<AGENT_NAME>`	To authenticate at query time as `sbndb_<profile-token>_<application-token>_runtime`, assumable only by this data plane’s lifecycle worker. See Connecting
Enhanced Monitoring IAM role	`sb-app-db-enhanced-monitoring`	To let RDS publish operating-system metrics. The worker may pass this role only, and only to `rds.amazonaws.com`
S3 state bucket	`sb-app-db-<REGION>-<ACCOUNT_ID>`	To store OpenTofu state at `{key_prefix}/{tag}/{resource_key}.tfstate`, versioned and private. Superblocks reads and writes this bucket in your account; Superblocks does not retain a copy. See S3 state bucket properties

Module options

Option	Default	Purpose
`agents`	Required	To declare one entry per data plane, keyed by agent name
`deployment_type`	Required	To pick the lifecycle worker trust policy: `fargate` or `eks`
`existing_monitoring_role_arn`	Module creates the role	To reuse an Enhanced Monitoring role, since IAM role names are account-global and a second region cannot create the same name
`iam_name_prefix`	`sb-app-db`	To prefix IAM role and policy names, up to 16 characters
`kms_key_arn`	SSE-S3	To encrypt state with your own KMS key, and to scope the worker’s KMS access to that key alone
`region`	Required	To set the region these resources are created in
`s3_name_prefix`	`sb-app-db`	To prefix the state bucket name, up to 16 characters
`tags`	`{}`	To add inventory tags. `ManagedBy`, `superblocks:owned`, and `aws-apn-id` are reserved and always enforced

Per-data-plane options

Each entry in the agents map takes these options.

Option	Default	Purpose
`agent_tags`	Required	To name the data tags this data plane serves, which derive its database and role names
`existing_role_name`	Module creates a role	To attach the worker policies to an ECS task role you already have, for brownfield deployments
`key_prefix`	`app-db/<AGENT_NAME>`	To namespace this data plane’s state inside the shared bucket, and to scope its S3 permissions. Must not overlap another data plane’s prefix
`namespace`	`superblocks`	To name the data plane’s Kubernetes namespace, on EKS
`oidc_provider_arn`	Required on EKS	To trust the data plane’s Kubernetes service account through IRSA
`rds_secret_kms_key_arn`	AWS-managed key	To encrypt the RDS-managed master secret with your own KMS key
`service_account_name`	`superblocks-agent`	To name the data plane’s Kubernetes service account, on EKS
`vpc_id`	Required	To scope every IAM policy for this data plane to one VPC

Multiple data planes in one account and region

Superblocks recommends one data plane per AWS account and VPC, so most deployments never need this. When you do run more than one in the same account and region, declare them all in one app_db_prereqs invocation. They share the state bucket, but not IAM roles or VPCs.

module "app_db_prereqs" {
  # ...same source, version, deployment_type, and region as a single data plane...
  agents = {
    "<AGENT_NAME>" = {
      agent_tags = ["<DATA_TAG>"]
      vpc_id     = "<VPC_ID>"
    }
    "<AGENT_NAME_2>" = {
      agent_tags = ["<DATA_TAG_2>"]
      vpc_id     = "<VPC_ID_2>"
    }
  }
}

Additional AWS regions

Each region needs its own app_db_prereqs invocation with an AWS provider alias, and gets its own S3 state bucket. The Enhanced Monitoring role is the exception: IAM role names are account-global, so designate the first region as the role’s durable home and pass its ARN to every additional region through existing_monitoring_role_arn.

provider "aws" {
  alias  = "secondary"
  region = "<SECOND_REGION>"
}

module "app_db_prereqs_secondary" {
  source  = "superblocksteam/superblocks/aws//modules/app-db-prereqs"
  version = ">= 1.5.3, < 2.0.0"

  providers = {
    aws = aws.secondary
  }

  deployment_type              = "<fargate-or-eks>"
  region                       = "<SECOND_REGION>"
  existing_monitoring_role_arn = module.app_db_prereqs.enhanced_monitoring_role_arn

  agents = {
    # Configure the data planes in this region as shown above.
  }
}

The example above assumes both regional module calls share one Terraform root and state. If each region uses separate state, pass the owning stack’s output through terraform_remote_state or supply the concrete ARN (arn:aws:iam::<ACCOUNT_ID>:role/<iam_name_prefix>-enhanced-monitoring) as existing_monitoring_role_arn. The secondary prerequisite stack re-exports the supplied role through its own enhanced_monitoring_role_arn output. Use module.app_db_prereqs_secondary.enhanced_monitoring_role_arn as monitoring_role_arn in that region’s Fargate physical_module_inputs or EKS physicalModuleInputs. If that role was deleted or changed accidentally, first check for <iam_name_prefix>-enhanced-monitoring in IAM. Restore the original owning prerequisite stack and run terraform apply to recreate its trust policy and managed-policy attachment. Because the recreated role has the same ARN, existing regional consumers can resume using it. To move ownership deliberately, create a replacement role, update every regional prerequisite stack and physical database input to the replacement ARN, apply those changes, and only then remove the old role.

Immutable setup inputs

There is no automated migration path, so changing any of these values requires manual recovery.

Agent name

This is a unique value represented in the Terraform inputs as agents = { "<AGENT_NAME>" = { ... } }. The agent name must be passed as an input into Fargate or Helm. The name is used to derive these outputs:

The IAM role and policy names, one set per data plane
The AgentName tag that every resource must carry before the lifecycle worker can change it
The OpenTofu state prefix, default app-db/<AGENT_NAME>, which also scopes the worker’s S3 permissions

If the names become mismatched for any reason, you will see AccessDenied errors.

Data tag names

Database and role names are derived from a hash of the tag: sbndb_<profile-token>_<application-token> for the database, sbndb_<profile-token>_<application-token>_runtime for its role. <profile-token> is the first 16 hex characters of SHA-256(lowercase(tag)); <application-token> is a 24-hex hash of the application ID. The connector role’s permissions are scoped to that pattern, so renaming a tag orphans every existing database and role under the old name. Tag names must be non-empty and unique across all agents in the module invocation. Settle your tags before any database exists; see Plan your data planes.

VPC

Every IAM policy created for a data plane is scoped to its VPC. Changing it means none of the existing roles can act on resources in the new VPC.

Cluster autoscaling

Capacity is configured per data plane. Superblocks recommends the same always-on shape for every data tag, including edit and preview: two instances at 2-32 ACUs each. Choose it when you provision the data plane. After the data plane registers serverless scaling changes (ACU range and instance count), Superblocks automatically queues updates for existing clusters. See Apply configuration changes to existing clusters.

Setting	Recommended value
`instance_count`	`2`
`min_acu` (per instance)	`2`
`max_acu` (per instance)	`32`
Cost while idle	Two instances billed at the ACU floor (4 ACUs aggregate)
First query after idle	Served immediately

Omitting the deployment block gives you this same shape: the released Aurora module defaults to two instances at 2-32 ACUs each, for an aggregate idle floor of 4 ACUs. Set the block explicitly anyway so the capacity is visible in your configuration. With a nonzero min_acu, the cluster never pauses. The default min_acu is 2. Setting it to 0 lets an idle cluster pause, which costs less but adds a cold start to the next connection (not recommended). A cluster that has been paused for about 24 hours can take over a minute to resume.

Provisioning the cluster pool

Your data plane provisions the first Aurora cluster when an admin clicks Provision, and adds another whenever remaining pool capacity hits the pool settings from the data plane configuration in Setup: Step 1 (max_databases on Fargate; that cap plus minAvailableCapacityPercent on Helm). This usually takes 5 to 15 minutes, depending on AWS latency. It runs tofu apply with the configuration it already has, so nothing is re-entered in the admin panel. Each cluster added to the pool arrives with:

Aurora PostgreSQL cluster and its instances: named sb-{hash}. Physical modules enable IAM database authentication, keep the endpoint private, encrypt storage, and manage the master password in AWS Secrets Manager. The lifecycle worker reads that secret by ref, so there is no plaintext master credential in Superblocks systems.
CloudWatch log group: a per-cluster /aws/rds/cluster/<cluster-id>/postgresql group that retains exported PostgreSQL logs for 30 days
DB cluster parameter group: carries the logging parameters described under Observing
DB subnet group: scoped to the subnets you specified in physical_module_inputs
Security group and its ingress/egress rules: controls which sources (security groups or CIDRs) can reach the database on port 5432. The security group and each rule are separate AWS resources, and both carry the tags described under How everything is tagged

App databases themselves are logical databases inside these clusters, each with its own PostgreSQL role. They are not separate AWS resources, so they never show up in the RDS console as their own entries. The lifecycle worker role does the creating, under the tag requirements described under How everything is tagged. IAM policy conditions require publicly_accessible = false, storage encryption, and an AWS Secrets Manager master password, so a modified module cannot opt out of those. IAM database authentication is enabled by the physical modules (iam_database_authentication_enabled = true); there is no corresponding IAM condition. See Raw IAM policy JSON.

Pool options

Lowering max_databases spreads apps across more clusters, which shrinks the blast radius of a failover or an engine patch and raises your baseline cost; raising it does the reverse. Fargate takes these under pool; Helm takes them under databaseLifecycle.pool in lowerCamelCase.

Option	Default	Purpose
`max_databases` / `maxDatabases`	`100`	To cap the logical databases one cluster holds before the next app database waits on a new cluster
`min_available_capacity_percent` / `minAvailableCapacityPercent`	Fargate: not published. Helm: `20`	To enqueue a new cluster when remaining capacity falls to this percent of `max_databases`. Helm only. Set `0` to disable proactive enqueue

Physical database options

Fargate takes these under physical_module_inputs; Helm takes the same keys under databaseLifecycle.physicalModuleInputs. New clusters use these settings when they are provisioned. After the data plane registers changes to supported settings, Superblocks automatically queues updates for existing clusters. See Apply configuration changes to existing clusters.

Option	Default	Purpose
`allowed_cidr_blocks`	`[]`	To let CIDR ranges reach the database on port 5432
`backup_retention_period`	`7`	To retain automated backups for 1 to 35 days
`delete_automated_backups`	`false`	To discard automated backups when a cluster is destroyed
`deletion_protection`	`true`	To block accidental cluster deletion
`deployment`	Two instances at 2-32 ACUs each, never pauses	To set Aurora capacity through nested `serverless_v2` or `provisioned`. See Cluster autoscaling
`monitoring_interval`	`60`	To set the Enhanced Monitoring interval in seconds, or `0` to turn it off
`monitoring_role_arn`	None	To pass the shared Enhanced Monitoring role, required unless `monitoring_interval` is `0`
`skip_final_snapshot`	`false`	To skip the final snapshot when a cluster is destroyed
`source_security_group_ids`	`[]`	To let security groups reach the database on port 5432, typically your data plane’s
`subnet_ids`	Required	To become the DB subnet group. At least two, spanning at least two Availability Zones
`tags`	`{}`	To add inventory tags to every provisioned resource. Tags are merged with `superblocks:owned`, `aws-apn-id`, `AgentName`, `ManagedBy`, and `Vpc`
`vpc_id`	Required	To place clusters in one VPC. Must match this data plane’s `agents` entry

publicly_accessible is not an option. It is always false, enforced by IAM rather than module default. Additional options allocated_storage, instance_class, and multi_az exist for alternative database configurations within AWS.

Creating an app database

A builder with database creation permission asks Clark for a feature that needs persistent data. Superblocks queues one task to create an isolated logical database on a cluster that already has capacity under your pool settings; if none does, it provisions a new cluster first. Your data plane claims the task, runs tofu apply in your AWS account, and reports back when the database is ready. Superblocks only queues the work. Your data plane is the only thing that calls AWS. The result is a PostgreSQL database and a matching role inside an existing cluster, named sbndb_<profile-token>_<application-token> and sbndb_<profile-token>_<application-token>_runtime (see Data tag names for how the tokens are derived). Each app gets one database per data tag the data plane serves. The lifecycle worker creates both and grants the role rds_iam. The connector role stays out of it until the app runs a query.

Applying schema migrations

Clark writes the schema as .sql files in the application’s own code, so it is versioned alongside the app. Once a database reports ready, Superblocks queues a migration task and your data plane applies those files to that one database. No AWS resources change. Edit-time and deploy-time databases use the same path.

Connecting

ECS Fargate
EKS (Helm)

module "app_db" {
  # Wired from the prereq module so the two cannot diverge.
  agent_tags         = module.app_db_prereqs.agents["<AGENT_NAME>"].agent_tags
  connector_role_arn = module.app_db_prereqs.agents["<AGENT_NAME>"].connector_role_arn
}

superblocks:
  # Comma-separated, each data tag prefixed with profile:.
  agentTags: profile:<DATA_TAG_1>

postgres:
  appDbConnectorRoleArn: "<CONNECTOR_ROLE_ARN>"

  iamAllowedRoleArnPrefixes:
    - "<CONNECTOR_ROLE_ARN>"

When an app runs a query, the data plane authenticates with the connector role. Neither that role’s ARN nor the lifecycle worker’s identity appears inside PostgreSQL: the database only ever sees a PostgreSQL role name and an auth token, and IAM decides whether that token is valid. The sequence for a single query is:

Provisioning creates the app’s PostgreSQL role (sbndb_<profile-token>_<application-token>_runtime) and grants it rds_iam. That grant makes PostgreSQL delegate authentication for this role to IAM instead of checking a stored password. No password is ever generated for it.
The data plane checks the target against the connector role ARNs in its own configuration, and refuses the connection if they disagree.
The data plane assumes the connector role, attaching an inline session policy that allows exactly one action on exactly one resource: rds-db:connect on this cluster, as this one PostgreSQL role.
It signs an RDS IAM auth token for that PostgreSQL role with those session credentials, and connects using the token as the password, over TLS with full certificate and hostname verification.

The effective permission on any given connection is the intersection of two policies. The connector role’s own policy bounds it to sbndb_<profile-token>_*_runtime users for the declared data tags (see Raw IAM policy JSON), and the per-connection session policy narrows that to the single user for the single app being served. One app’s credentials cannot reach another app’s database, even though both use the same connector role.

Deploying

When a builder publishes an app, the deploy-time data tag gets its own database. If the app does not have one there yet, Superblocks queues a create task and then a migration task, producing the same database and role as at edit time under a different tag. The deploy does not proceed until both finish. No data is copied. The deploy-time database gets the schema and none of the development rows.

Observing

ECS Fargate
EKS (Helm)

module "app_db" {
  physical_module_inputs = {
    # Enhanced Monitoring. Set the interval to 0 and omit the role to opt out.
    monitoring_interval = 60
    monitoring_role_arn = module.app_db_prereqs.enhanced_monitoring_role_arn
  }
}

databaseLifecycle:
  physicalModuleInputs:
    # Enhanced Monitoring. Set the interval to 0 and omit the role to opt out.
    monitoring_interval: 60
    monitoring_role_arn: "<ENHANCED_MONITORING_ROLE_ARN>"

    # Helm only, both on by default. Fargate cannot disable them as of v1.5.2.
    # enabled_cloudwatch_logs_exports: []
    # performance_insights_enabled: false

The default configuration provides the following signals in your AWS account:

Standard RDS CloudWatch metrics
Enhanced Monitoring at 60-second resolution through the account- and region-level RDSOSMetrics CloudWatch Logs group, with one log stream per database instance. Its retention is independent of the per-cluster PostgreSQL log group’s 30-day setting
Database Insights Standard, with Performance Insights retained for 7 days
PostgreSQL logs exported to CloudWatch Logs with 30-day retention
PostgreSQL diagnostic logs for lock waits and deadlocks, temporary files larger than 64 MiB, checkpoints, and autovacuum operations running at least 5 seconds
Slow-query logging for every statement running at least 5 seconds and a 10% sample of statements running between 1 and 5 seconds. Statements under 1 second are not duration-logged. Bound parameter values are excluded, although the parameterized statement text is retained
pg_stat_statements tracking for top-level statements. Its storage is bounded and shared across the cluster, so older or less-used entries can be evicted; the module does not fix a universal entry limit

Settings declared in the physical module inputs or supplied by its defaults, including log retention and PostgreSQL parameters, are managed through OpenTofu, so a later lifecycle apply can revert manual console changes. Superblocks does not ingest these signals or monitor your databases on your behalf.

How everything is tagged

Every App Database AWS resource carries two kinds of tags. IAM scoping tags (required for the lifecycle worker to mutate the resource):

AgentName={agents-map-key}, the agent name for this data plane (Terraform agents map key, Fargate agent_name, or Helm superblocks.agentName)
ManagedBy=superblocks-app-database-lifecycle
Vpc={your-vpc-id}

The IAM policies only allow create/modify/delete on resources carrying all three. The worker stamps AgentName itself; physical modules merge ManagedBy; Vpc comes from your networking inputs. Ownership and partnership tags (required on every Superblocks-created resource, including runtime Aurora):

superblocks:owned=true
aws-apn-id=pc:ctelqp437y3cvjkv5rv0z2w4f

These do not change who pays the bill or which AWS account owns the resources, which remains your account. aws-apn-id is identical in every deployment rather than per-account. app-db-prereqs enforces both keys on setup resources. The physical OpenTofu modules stamp them on runtime Aurora, RDS, subnet groups, and security groups, overwriting conflicting caller values. The Fargate app-db module also merges the same pair into runtime module inputs. On EKS, databaseLifecycle.physicalModuleTags is for optional inventory tags only (cost center, team, and similar). Do not set ManagedBy, AgentName, Vpc, superblocks:owned, or aws-apn-id there. The lifecycle worker IAM policy also denies removing any of the five keys above (AgentName, ManagedBy, Vpc, superblocks:owned, and aws-apn-id), including via named Deny Sids (DenyRemoveProtectedTags / DenyDeleteProtectedTags / DenyUntagProtectedTags) so AccessDenied is attributable. EC2 DenyDeleteProtectedTags is further scoped with AgentName / ManagedBy / Vpc ResourceTags so attaching policies via existing_role_name cannot Deny DeleteTags on unrelated security groups. A Resource Group or the CLI lists everything the feature manages:

aws resourcegroupstaggingapi get-resources \
  --tag-filters Key=ManagedBy,Values=superblocks-app-database-lifecycle

# Or filter on ownership:
aws resourcegroupstaggingapi get-resources \
  --tag-filters Key=superblocks:owned,Values=true

S3 state bucket properties

The Terraform module creates the state bucket, so these properties only matter if your organization creates it by hand instead.

Required S3 state bucket properties

Property	Required value	Notes
Versioning	Enabled	Required for state recovery
Block public access	All four settings enabled	`block_public_acls`, `block_public_policy`, `ignore_public_acls`, `restrict_public_buckets`
Server-side encryption	SSE-S3 (default) or SSE-KMS	SSE-S3 uses AWS-managed keys and incurs no KMS charges. SSE-KMS only when `kms_key_arn` is provided; use the same key ARN supplied to the module
S3 bucket key	Disabled	The module sets `bucket_key_enabled = false`. This is separate from `kms_key_arn`; you can use SSE-KMS with a customer-managed key and still have bucket keys off.
Non-current version expiration	90 days	Keeps state recoverable without unbounded storage growth
Abort incomplete multipart uploads	7 days
Bucket policy	None	Access is controlled via the IAM policies in Raw IAM policy JSON; no explicit bucket policy is required

Raw IAM policy JSON

The Terraform module creates the following IAM resources per data plane. If your organization requires policies to be pre-approved or manually provisioned before Terraform can attach them, use the JSON below. iam_name_prefix prefixes the IAM role and policy names below, and s3_name_prefix prefixes the state bucket name. Both default to sb-app-db. Placeholders to substitute before use:

Placeholder	Example value	Description
`<REGION>`	`us-east-1`	AWS region
`<ACCOUNT_ID>`	`123456789012`	12-digit AWS account ID
`<VPC_ID>`	`vpc-0123456789abcdef0`	VPC ID declared for this data plane
`<SUBNET_ID_1>`, `<SUBNET_ID_2>`, …	`subnet-0123456789abcdef0`	Private subnet IDs for the Aurora subnet group
`<SECURITY_GROUP_ID>`	`sg-0123456789abcdef0`	Security group allowed to reach Aurora on port 5432
`<BUCKET_NAME>`	`sb-app-db-us-east-1-123456789012`	S3 state bucket name
`<KEY_PREFIX>`	`app-db/<AGENT_NAME>`	OpenTofu state prefix IAM-scoped to this data plane. Equals `module.app_db_prereqs.agents["<AGENT_NAME>"].key_prefix` (override via `agents[].key_prefix`). See Agent name.
`<AGENT_NAME>`	No default (max 15 characters, lowercase alphanumeric, unique per AWS account)	Agent name for this data plane. Used in IAM role and policy names.
`<LIFECYCLE_WORKER_ROLE_ARN>`	`arn:aws:iam::123456789012:role/sb-app-db-<AGENT_NAME>-lifecycle-worker-<REGION>`	ARN of the lifecycle worker role
`<CONNECTOR_ROLE_ARN>`	`arn:aws:iam::123456789012:role/superblocks-app-db-connector-<AGENT_NAME>`	ARN of the connector role (fixed `superblocks-app-db-connector-<AGENT_NAME>` name; not affected by `iam_name_prefix`)
`<OIDC_PROVIDER_ARN>`	`arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE`	EKS OIDC provider ARN (EKS only)
`<OIDC_PROVIDER_URL>`	`oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE`	OIDC URL (the ARN above with `arn:aws:iam::<ACCOUNT_ID>:oidc-provider/` stripped)
`<ENHANCED_MONITORING_ROLE_ARN>`	`arn:aws:iam::123456789012:role/sb-app-db-enhanced-monitoring`	ARN of the shared Enhanced Monitoring role
`<KMS_KEY_ARN>`	`arn:aws:kms:us-east-1:123456789012:key/mrk-example`	Customer-managed KMS key ARN. Used only when `kms_key_arn` is set on `app-db-prereqs` (SSE-KMS). Omit `StateBucketKms` entirely for the SSE-S3 default.

When creating these manually, create the lifecycle worker role first (it has no dependencies), then the connector role (its trust policy references the lifecycle worker role ARN), then create and attach all policies.

Lifecycle worker role: trust policy (ECS Fargate)

Allows the ECS task service principal to assume the role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      }
    }
  ]
}

Lifecycle worker role: trust policy (EKS with IRSA)

Allows the data plane pod’s service account to assume the role via OIDC web identity. <OIDC_PROVIDER_URL> is the OIDC provider URL without the ARN prefix (everything after oidc-provider/). The sub condition scopes trust to the specific Kubernetes service account. Adjust namespace and service_account_name if you deviate from the Superblocks defaults.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Principal": {
        "Federated": "<OIDC_PROVIDER_ARN>"
      },
      "Condition": {
        "StringEquals": {
          "<OIDC_PROVIDER_URL>:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "<OIDC_PROVIDER_URL>:sub": "system:serviceaccount:superblocks:superblocks-agent"
        }
      }
    }
  ]
}

Policy 1: Assume connector (sb-app-db-<AGENT_NAME>-assume-connector)

Allows the lifecycle worker to assume its connector role for RDS IAM authentication. Attached to the lifecycle worker role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AssumeAppDatabaseConnector",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": ["<CONNECTOR_ROLE_ARN>"]
    }
  ]
}

Policy 2: State backend (sb-app-db-<AGENT_NAME>-state-bucket-<REGION>)

Allows the lifecycle worker to read and write OpenTofu state in the shared S3 bucket under that agent’s key_prefix only (default app-db/<AGENT_NAME>; override via agents["<AGENT_NAME>"].key_prefix). Replace <KEY_PREFIX> with the same string you wire into the data plane (see Agent name).GetBucketLocation / GetBucketVersioning live in a separate statement from ListBucket because those metadata APIs do not send s3:prefix and would fail closed if they shared the list condition.The default bucket uses SSE-S3. The released module emits no StateBucketKms statement in that case. Do not add a Resource: "*" KMS grant to match older examples; that widens decrypt for brownfield roles that already have broader S3 permissions.StateBucketKms is present only when you set kms_key_arn (SSE-KMS). It names that key ARN and has no CalledVia condition:

{
  "Sid": "StateBucketKms",
  "Effect": "Allow",
  "Action": [
    "kms:Decrypt",
    "kms:DescribeKey",
    "kms:Encrypt",
    "kms:GenerateDataKey",
    "kms:ReEncryptFrom",
    "kms:ReEncryptTo"
  ],
  "Resource": "<KMS_KEY_ARN>"
}

The default SSE-S3 policy is the three S3 statements below.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "StateBucketMetadata",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:GetBucketVersioning"
      ],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>"
    },
    {
      "Sid": "StateBucketList",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>",
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "<KEY_PREFIX>/",
            "<KEY_PREFIX>/*"
          ]
        }
      }
    },
    {
      "Sid": "StateBucketObjectReadWrite",
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>/<KEY_PREFIX>/*"
    }
  ]
}

Policy 3: RDS provisioning (sb-app-db-<AGENT_NAME>-rds-provisioning-<REGION>)

Allows the lifecycle worker to describe RDS and Aurora resources globally (required by AWS, because describe APIs do not support resource-level restrictions) and to create new RDS and Aurora resources scoped to the sb-* namespace and the declared VPC. All create actions enforce tagging at request time, publicly_accessible = false, and manage_master_user_password = true. The RdsCreateDbInstance and RdsCreateAuroraClusterInstance statements both cover rds:CreateDBInstance but are cleanly discriminated: standalone RDS creates pass rds:ManageMasterUserPassword = true and Aurora member creates do not, so each request matches exactly one statement. iam:CreateServiceLinkedRole is scoped to rds.amazonaws.com; it runs once, and only if your account does not already have the RDS service-linked role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RdsDescribe",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBClusterParameterGroups",
        "rds:DescribeDBClusterParameters",
        "rds:DescribeDBClusterSnapshots",
        "rds:DescribeDBClusters",
        "rds:DescribeDBEngineVersions",
        "rds:DescribeDBInstances",
        "rds:DescribeDBParameterGroups",
        "rds:DescribeDBParameters",
        "rds:DescribeDBSnapshots",
        "rds:DescribeDBSubnetGroups",
        "rds:DescribeGlobalClusters",
        "rds:DescribePendingMaintenanceActions",
        "rds:ListTagsForResource"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CreateRdsServiceLinkedRole",
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "iam:AWSServiceName": "rds.amazonaws.com"
        }
      }
    },
    {
      "Sid": "RdsCreateDbInstance",
      "Effect": "Allow",
      "Action": "rds:CreateDBInstance",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:*"
      ],
      "Condition": {
        "Bool": {
          "rds:ManageMasterUserPassword": "true",
          "rds:PubliclyAccessible": "false",
          "rds:StorageEncrypted": "true"
        },
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "rds:DatabaseEngine": "postgres"
        }
      }
    },
    {
      "Sid": "RdsCreateAuroraCluster",
      "Effect": "Allow",
      "Action": "rds:CreateDBCluster",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "Bool": {
          "rds:ManageMasterUserPassword": "true",
          "rds:StorageEncrypted": "true"
        },
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "rds:DatabaseEngine": "aurora-postgresql"
        }
      }
    },
    {
      "Sid": "RdsCreateAuroraClusterInstance",
      "Effect": "Allow",
      "Action": "rds:CreateDBInstance",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "Bool": {
          "rds:PubliclyAccessible": "false"
        },
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "rds:DatabaseEngine": "aurora-postgresql"
        }
      }
    },
    {
      "Sid": "RdsCreateParameterGroups",
      "Effect": "Allow",
      "Action": [
        "rds:CreateDBClusterParameterGroup",
        "rds:CreateDBParameterGroup"
      ],
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:sb-*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsCreateDbSubnetGroup",
      "Effect": "Allow",
      "Action": "rds:CreateDBSubnetGroup",
      "Resource": "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsTagOnCreate",
      "Effect": "Allow",
      "Action": "rds:AddTagsToResource",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        },
        "StringEqualsIfExists": {
          "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f",
          "aws:RequestTag/superblocks:owned": "true"
        }
      }
    },
    {
      "Sid": "RdsTagAppSnapshotOnCreate",
      "Effect": "Allow",
      "Action": "rds:AddTagsToResource",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:snapshot:sb-*"
      ],
      "Condition": {
        "StringEqualsIfExists": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f",
          "aws:RequestTag/superblocks:owned": "true"
        }
      }
    },
    {
      "Sid": "RdsEncryptedStorageKmsViaRds",
      "Effect": "Allow",
      "Action": [
        "kms:CreateGrant",
        "kms:Decrypt",
        "kms:DescribeKey",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:CalledVia": "rds.amazonaws.com"
        }
      }
    }
  ]
}

Policy 4: RDS mutation (sb-app-db-<AGENT_NAME>-rds-mutation-<REGION>)

Allows the lifecycle worker to modify, delete, snapshot, and retag RDS and Aurora resources it created. The target must already carry the AgentName, ManagedBy, and Vpc tags, so the lifecycle worker cannot modify any RDS resource it did not create. RdsRemoveTagsExceptProtectedTags only Allows removing non-protected tags. DenyRemoveProtectedTags is an explicit Deny that blocks removing AgentName, ManagedBy, Vpc, superblocks:owned, or aws-apn-id, so AccessDenied is attributable to that Sid.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RdsMutate",
      "Effect": "Allow",
      "Action": [
        "rds:DeleteDBCluster",
        "rds:DeleteDBClusterParameterGroup",
        "rds:DeleteDBInstance",
        "rds:DeleteDBParameterGroup",
        "rds:DeleteDBSubnetGroup",
        "rds:ModifyDBCluster",
        "rds:ModifyDBClusterParameterGroup",
        "rds:ModifyDBInstance",
        "rds:ModifyDBParameterGroup",
        "rds:ModifyDBSubnetGroup",
        "rds:RebootDBCluster",
        "rds:RebootDBInstance",
        "rds:ResetDBClusterParameterGroup",
        "rds:ResetDBParameterGroup"
      ],
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "BoolIfExists": {
          "rds:ManageMasterUserPassword": "true"
        },
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsDeleteAuroraClusterFinalSnapshot",
      "Effect": "Allow",
      "Action": "rds:DeleteDBCluster",
      "Resource": "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-snapshot:sb-*",
      "Condition": {
        "StringEqualsIfExists": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsCreateSnapshotFromManagedCluster",
      "Effect": "Allow",
      "Action": "rds:CreateDBClusterSnapshot",
      "Resource": "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsCreateAppClusterSnapshot",
      "Effect": "Allow",
      "Action": "rds:CreateDBClusterSnapshot",
      "Resource": "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-snapshot:sb-*",
      "Condition": {
        "StringEqualsIfExists": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsCreateSnapshotFromManagedInstance",
      "Effect": "Allow",
      "Action": "rds:CreateDBSnapshot",
      "Resource": "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsCreateAppSnapshot",
      "Effect": "Allow",
      "Action": "rds:CreateDBSnapshot",
      "Resource": "arn:aws:rds:<REGION>:<ACCOUNT_ID>:snapshot:sb-*",
      "Condition": {
        "StringEqualsIfExists": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "RdsAddTagsToManagedResources",
      "Effect": "Allow",
      "Action": "rds:AddTagsToResource",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        },
        "StringEqualsIfExists": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f",
          "aws:RequestTag/superblocks:owned": "true"
        }
      }
    },
    {
      "Sid": "RdsRemoveTagsExceptProtectedTags",
      "Effect": "Allow",
      "Action": "rds:RemoveTagsFromResource",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        },
        "ForAllValues:StringNotEquals": {
          "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"]
        }
      }
    },
    {
      "Sid": "DenyRemoveProtectedTags",
      "Effect": "Deny",
      "Action": "rds:RemoveTagsFromResource",
      "Resource": [
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:cluster-snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:db:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:pg:*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:snapshot:sb-*",
        "arn:aws:rds:<REGION>:<ACCOUNT_ID>:subgrp:sb-*"
      ],
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"]
        }
      }
    }
  ]
}

Policy 5: EC2 networking (sb-app-db-<AGENT_NAME>-ec2-provisioning-<REGION>)

Allows the lifecycle worker to describe VPC and subnet topology (globally, as required by AWS) and to create and manage security groups scoped to the declared VPC. The Ec2CreateSecurityGroupVpcScope statement additionally restricts CreateSecurityGroup to the specific VPC resource via ec2:VpcID, so the lifecycle worker cannot create security groups in any other VPC. Ec2CreateTagsOnCreateSecurityGroup authorizes create-time tagging for CreateSecurityGroup and for AuthorizeSecurityGroupIngress / AuthorizeSecurityGroupEgress, so ownership tags can land on both the security group and its individual rules when they are created. Ec2DeleteTagsExceptProtectedTags only Allows removing non-protected tags from managed security groups and rules when aws:TagKeys is present; DenyDeleteProtectedTags Denies removing the scoping and ownership keys; DenyDeleteTagsWhenTagKeysAbsent Denies the delete-all request that omits Tags / aws:TagKeys.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Ec2VpcDescribe",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeAccountAttributes",
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeRouteTables",
        "ec2:DescribeSecurityGroupRules",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSubnets",
        "ec2:DescribeTags",
        "ec2:DescribeVpcAttribute",
        "ec2:DescribeVpcs"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Ec2CreateSecurityGroupResource",
      "Effect": "Allow",
      "Action": ["ec2:CreateSecurityGroup"],
      "Resource": "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group/*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "Ec2CreateSecurityGroupVpcScope",
      "Effect": "Allow",
      "Action": ["ec2:CreateSecurityGroup"],
      "Resource": "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:vpc/<VPC_ID>",
      "Condition": {
        "StringEquals": {
          "ec2:VpcID": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "Ec2SecurityGroupMutate",
      "Effect": "Allow",
      "Action": [
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:DeleteSecurityGroup",
        "ec2:ModifySecurityGroupRules",
        "ec2:RevokeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupIngress"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "Ec2CreateTagsOnCreateSecurityGroup",
      "Effect": "Allow",
      "Action": ["ec2:CreateTags"],
      "Resource": [
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group/*",
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group-rule/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "ec2:CreateAction": [
            "AuthorizeSecurityGroupEgress",
            "AuthorizeSecurityGroupIngress",
            "CreateSecurityGroup"
          ]
        },
        "StringEqualsIfExists": {
          "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f",
          "aws:RequestTag/superblocks:owned": "true"
        }
      }
    },
    {
      "Sid": "Ec2CreateTagsOnManagedResources",
      "Effect": "Allow",
      "Action": ["ec2:CreateTags"],
      "Resource": [
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group/*",
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group-rule/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        },
        "StringEqualsIfExists": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>",
          "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f",
          "aws:RequestTag/superblocks:owned": "true"
        }
      }
    },
    {
      "Sid": "Ec2DeleteTagsExceptProtectedTags",
      "Effect": "Allow",
      "Action": ["ec2:DeleteTags"],
      "Resource": [
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group/*",
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group-rule/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        },
        "Null": {
          "aws:TagKeys": "false"
        },
        "ForAllValues:StringNotEquals": {
          "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"]
        }
      }
    },
    {
      "Sid": "DenyDeleteProtectedTags",
      "Effect": "Deny",
      "Action": ["ec2:DeleteTags"],
      "Resource": [
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group/*",
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group-rule/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        },
        "ForAnyValue:StringEquals": {
          "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"]
        }
      }
    },
    {
      "Sid": "DenyDeleteTagsWhenTagKeysAbsent",
      "Effect": "Deny",
      "Action": ["ec2:DeleteTags"],
      "Resource": [
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group/*",
        "arn:aws:ec2:<REGION>:<ACCOUNT_ID>:security-group-rule/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        },
        "Null": {
          "aws:TagKeys": "true"
        }
      }
    }
  ]
}

Policy 6: Secrets Manager (sb-app-db-<AGENT_NAME>-secrets-<REGION>)

Allows the lifecycle worker to read RDS-managed master secrets for databases it owns. Secret creation is only permitted via aws:CalledVia: rds.amazonaws.com, so the lifecycle worker cannot directly create Secrets Manager secrets; only RDS can, on its behalf. The worker reads these secrets by ref when provisioning logical databases, so there is no plaintext master credential in Superblocks systems.The last statement (DecryptRdsManagedSecretKmsKey) handles KMS decryption for the RDS-managed master secret. Without a customer KMS key (rds_secret_kms_key_arn not set), Resource is "*" and access is constrained via kms:ViaService and kms:EncryptionContext as shown below. With a customer KMS key, replace "Resource": "*" with the specific key ARN.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CreateRdsManagedMasterSecrets",
      "Effect": "Allow",
      "Action": "secretsmanager:CreateSecret",
      "Resource": [
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!cluster-*",
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!db-*"
      ],
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:CalledVia": "rds.amazonaws.com"
        },
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "TagRdsManagedMasterSecretsViaRds",
      "Effect": "Allow",
      "Action": "secretsmanager:TagResource",
      "Resource": [
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!cluster-*",
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!db-*"
      ],
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:CalledVia": "rds.amazonaws.com"
        },
        "StringEquals": {
          "aws:RequestTag/AgentName": "<AGENT_NAME>",
          "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:RequestTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "DescribeRdsManagedSecretKmsKeyViaRds",
      "Effect": "Allow",
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:CalledVia": "rds.amazonaws.com"
        }
      }
    },
    {
      "Sid": "ReadTaggedRdsManagedMasterSecrets",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:DescribeSecret",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!cluster-*",
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!db-*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/AgentName": "<AGENT_NAME>",
          "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle",
          "aws:ResourceTag/Vpc": "<VPC_ID>"
        }
      }
    },
    {
      "Sid": "DecryptRdsManagedSecretKmsKey",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:DescribeKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "secretsmanager.<REGION>.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:SecretARN": [
            "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!cluster-*",
            "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:rds!db-*"
          ]
        }
      }
    }
  ]
}

Connector role: trust policy

Allows only the lifecycle worker role for this data plane to assume the connector role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowOnlyTrustedOpa",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Principal": {
        "AWS": ["<LIFECYCLE_WORKER_ROLE_ARN>"]
      }
    }
  ]
}

Connector role: policy (superblocks-app-db-connector-<AGENT_NAME>)

Grants rds-db:connect for each declared data tag, scoped to DB users matching sbndb_<profile-token>_*_runtime on both RDS instances and Aurora clusters. <profile-token> is the first 16 hex characters of SHA-256(lowercase(tag)), which you can compute with printf '%s' '<DATA_TAG>' | shasum -a 256 | cut -c1-16. Add or remove statements to match your declared agent_tags. The example below shows two data tags (<PROFILE_TOKEN_1> and <PROFILE_TOKEN_2>).This is the outer bound, not the effective permission on a connection. See Connecting.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ConnectTag1",
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": [
        "arn:aws:rds-db:<REGION>:<ACCOUNT_ID>:dbuser:cluster-*/sbndb_<PROFILE_TOKEN_1>_*_runtime",
        "arn:aws:rds-db:<REGION>:<ACCOUNT_ID>:dbuser:db-*/sbndb_<PROFILE_TOKEN_1>_*_runtime"
      ]
    },
    {
      "Sid": "ConnectTag2",
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": [
        "arn:aws:rds-db:<REGION>:<ACCOUNT_ID>:dbuser:cluster-*/sbndb_<PROFILE_TOKEN_2>_*_runtime",
        "arn:aws:rds-db:<REGION>:<ACCOUNT_ID>:dbuser:db-*/sbndb_<PROFILE_TOKEN_2>_*_runtime"
      ]
    }
  ]
}

Policy 7: Observability (sb-app-db-<AGENT_NAME>-observability-<REGION>)

Allows the lifecycle worker to manage CloudWatch log groups for Aurora clusters and instances it provisions, and to pass the shared Enhanced Monitoring role to RDS.logs:DescribeLogGroups must be scoped to "Resource": "*" because AWS does not support resource-level restrictions on describe log group APIs.logs:UntagResource is split into an Allow that excludes protected keys (CloudWatchUntagExceptProtectedTags) and an explicit Deny (DenyUntagProtectedTags), matching the RDS/EC2 protected-tag pattern. logs:TagResource is similarly split (CloudWatchTagResourceWithCanonicalOwnership) so ownership request-tag values cannot be overwritten.iam:PassRole is conditioned on iam:PassedToService: rds.amazonaws.com, which is the service principal that RDS uses when calling CreateDBInstance. It is not monitoring.rds.amazonaws.com, which is what the monitoring agent assumes later.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchLogGroupsForAppDatabases",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:DeleteLogGroup",
        "logs:ListTagsForResource",
        "logs:PutRetentionPolicy"
      ],
      "Resource": [
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/cluster/sb-*",
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/instance/sb-*"
      ]
    },
    {
      "Sid": "CloudWatchTagResourceWithCanonicalOwnership",
      "Effect": "Allow",
      "Action": "logs:TagResource",
      "Resource": [
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/cluster/sb-*",
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/instance/sb-*"
      ],
      "Condition": {
        "StringEqualsIfExists": {
          "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f",
          "aws:RequestTag/superblocks:owned": "true"
        }
      }
    },
    {
      "Sid": "CloudWatchUntagExceptProtectedTags",
      "Effect": "Allow",
      "Action": "logs:UntagResource",
      "Resource": [
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/cluster/sb-*",
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/instance/sb-*"
      ],
      "Condition": {
        "ForAllValues:StringNotEquals": {
          "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"]
        }
      }
    },
    {
      "Sid": "DenyUntagProtectedTags",
      "Effect": "Deny",
      "Action": "logs:UntagResource",
      "Resource": [
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/cluster/sb-*",
        "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/rds/instance/sb-*"
      ],
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"]
        }
      }
    },
    {
      "Sid": "DescribeLogGroupsIsNotResourceScopable",
      "Effect": "Allow",
      "Action": "logs:DescribeLogGroups",
      "Resource": "*"
    },
    {
      "Sid": "PassEnhancedMonitoringRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "<ENHANCED_MONITORING_ROLE_ARN>",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "rds.amazonaws.com"
        }
      }
    }
  ]
}

Enhanced Monitoring role: trust and permissions

app_db_prereqs creates one account-level role named sb-app-db-enhanced-monitoring (or <iam_name_prefix>-enhanced-monitoring) with the following trust policy. Additional regional prerequisite stacks reuse this same role through existing_monitoring_role_arn. If your organization must create IAM roles out of band, create the role with this policy and pass its ARN as existing_monitoring_role_arn to every prerequisite invocation.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRdsEnhancedMonitoringForAppDatabases",
      "Effect": "Allow",
      "Principal": {
        "Service": "monitoring.rds.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": [
            "arn:aws:rds:*:<ACCOUNT_ID>:cluster:sb-*",
            "arn:aws:rds:*:<ACCOUNT_ID>:db:sb-*"
          ]
        },
        "StringEquals": {
          "aws:SourceAccount": "<ACCOUNT_ID>"
        }
      }
    }
  ]
}

The module attaches the AWS-managed arn:aws:iam::aws:policy/service-role/AmazonRDSEnhancedMonitoringRole policy to this role. If you create the role out of band, attach the same policy. The trust policy uses monitoring.rds.amazonaws.com, while the lifecycle worker’s iam:PassRole condition above intentionally uses rds.amazonaws.com; these principals serve different parts of the Enhanced Monitoring flow.

Org administration

Governance

Billing

Superblocks on AWS

Superblocks Database Reference

One-time setup

Resources created

Module options

Per-data-plane options

Multiple data planes in one account and region

Additional AWS regions

Immutable setup inputs

Agent name

Data tag names

VPC

Cluster autoscaling

Provisioning the cluster pool

Pool options

Physical database options

Creating an app database

Applying schema migrations

Connecting

Deploying

Observing

How everything is tagged

S3 state bucket properties

Raw IAM policy JSON

​One-time setup

​Resources created

​Module options

​Per-data-plane options

​Multiple data planes in one account and region

​Additional AWS regions

​Immutable setup inputs

​Agent name

​Data tag names

​VPC

​Cluster autoscaling

​Provisioning the cluster pool

​Pool options

​Physical database options

​Creating an app database

​Applying schema migrations

​Connecting

​Deploying

​Observing

​How everything is tagged

​S3 state bucket properties

​Raw IAM policy JSON

One-time setup

Resources created

Module options

Per-data-plane options

Multiple data planes in one account and region

Additional AWS regions

Immutable setup inputs

Agent name

Data tag names

VPC

Cluster autoscaling

Provisioning the cluster pool

Pool options

Physical database options

Creating an app database

Applying schema migrations

Connecting

Deploying

Observing

How everything is tagged

S3 state bucket properties

Raw IAM policy JSON