Skip to content

jaingxyz/aws-data-skills / skills/lakehouse-redshift

lakehouse-redshift

Verified

FileKindSize
SKILL.mdskill md25.3 KB
reference/cfn-gotchas.mdmarkdown6.9 KB
reference/iam-snippets.mdmarkdown7.6 KB

reference/cfn-gotchas.md

View on GitHub
# CloudFormation gotchas specific to S3 Tables

These are the things that have eaten the most time when authoring CFN for an S3 Tables + Glue + Lake Formation + Redshift Serverless stack. Keep them in your head while writing the template.

## 1. `!Ref AWS::S3Tables::TableBucket` returns the ARN, not the name

This is the single highest-time-wasted issue in this stack. `!Ref` on an `AWS::S3Tables::TableBucket` returns the full ARN:

```
arn:aws:s3tables:<region>:<account-id>:bucket/<name>
```

If you write `${TableBucket}` in a `!Sub` expecting the name, every downstream interpolation breaks. The bucket-nested catalog ARN ends up looking like:

```
arn:aws:glue:...:catalog/s3tablescatalog/arn:aws:s3tables:...
```

which fails CloudFormation validation in opaque ways because the regex for catalog ARNs allows up to two path components and this has many.

### The fix

Extract the bare name from the ARN:

```yaml
!Select [1, !Split ["/", !GetAtt TableBucket.TableBucketARN]]
```

This pattern is needed in 4+ places in a non-trivial stack. To avoid repetition, declare it once as a `!Sub` substitution variable:

```yaml
GlueCatalogArn:
  Description: Bucket-nested Glue catalog ARN
  Value: !Sub
    - "arn:aws:glue:${AWS::Region}:${AWS::AccountId}:catalog/s3tablescatalog/${BucketName}"
    - BucketName: !Select [1, !Split ["/", !GetAtt TableBucket.TableBucketARN]]
  Export:
    Name: !Sub "${ProjectName}-iceberg-catalog-arn"
```

If you find yourself writing the `!Select`/`!Split` more than twice, consider exposing the bucket name as an Output and consuming it via `!ImportValue` in a downstream stack, or compute it once in a script and pass it as a parameter to the next phase.

## 2. `AWS::S3Tables::Table` resource handler races namespace propagation

The S3 Tables namespace API returns success on `CreateNamespace` immediately, but the namespace is not readable to subsequent `CreateTable` calls for **5+ minutes**. CloudFormation's resource handler considers `AWS::S3Tables::Namespace` `CREATE_COMPLETE` within a few hundred milliseconds. If `AWS::S3Tables::Table` follows it in the same stack, the table create call returns `404 NotFound: The specified namespace does not exist.`

Adding `DependsOn: TableNamespace` does not help. It is already implicit via `!Ref`, and the lag is not in the dependency graph - it is in eventual consistency on the S3 Tables side.

A Lambda-backed custom resource with retries also fails unless you raise the Lambda timeout above 5 minutes and the retry budget covers the worst case. Doable, but adds a lot of complexity for a one-time create.

### The recommendation

Move table creation OUT of CFN. Create the bucket and namespace in CFN; create the table in a deploy script with bash-level retries:

```bash
metadata_file=$(mktemp)
cat > "${metadata_file}" <<'JSON'
{
  "iceberg": {
    "schema": {
      "fields": [
        {"name": "col_a", "type": "string",    "required": true},
        {"name": "col_b", "type": "timestamp", "required": true}
      ]
    }
  }
}
JSON

success=0
for _ in $(seq 1 60); do
    if aws s3tables create-table \
            --table-bucket-arn "${BUCKET_ARN}" \
            --namespace "${NAMESPACE}" \
            --name "${TABLE_NAME}" \
            --format ICEBERG \
            --metadata "file://${metadata_file}" \
            --region "${AWS_REGION}" >/dev/null 2>&1; then
        success=1
        break
    fi
    printf '.' >&2
    sleep 5
done
[ "${success}" = "1" ] || { echo "create-table failed after 5 minutes"; exit 1; }
```

60 iterations of 5 seconds = 5 minutes of cushion. In practice the call succeeds within ~30s once the namespace propagates, but the cushion prevents flakes on a cold bucket.

Run the create idempotently by checking with `get-table` first:

```bash
if aws s3tables get-table \
        --table-bucket-arn "${BUCKET_ARN}" \
        --namespace "${NAMESPACE}" \
        --name "${TABLE_NAME}" \
        --region "${AWS_REGION}" >/dev/null 2>&1; then
    echo "Table already exists"
else
    # create with retry loop above
fi
```

## 3. S3 Tables bucket name reservation cooldown

After deleting an `AWS::S3Tables::TableBucket`, the bucket name is reserved within the account/region for several minutes. Re-deploying the same stack within that window fails with:

```
The bucket is in a transitional state because of a previous deletion attempt.
```

This is similar to S3 bucket name cooldown but the window is longer.

### The fix

Add a `BucketSuffix` parameter so iterators can pass `v2`, `v3`, etc. without waiting:

```yaml
Parameters:
  BucketSuffix:
    Type: String
    Default: ""
    Description: >
      Optional suffix appended to the S3 Tables bucket name. S3 Tables
      bucket names are globally reserved within an account/region for
      ~minutes after deletion; pass a fresh suffix to work around the
      cooldown when iterating.
    AllowedPattern: "^[a-z0-9-]{0,16}$"

Conditions:
  HasBucketSuffix: !Not [!Equals [!Ref BucketSuffix, ""]]

Resources:
  TableBucket:
    Type: AWS::S3Tables::TableBucket
    Properties:
      TableBucketName: !If
        - HasBucketSuffix
        - !Sub "${ProjectName}-iceberg-${BucketSuffix}"
        - !Sub "${ProjectName}-iceberg"
```

## 4. `aws cloudformation deploy` parameter inheritance

`aws cloudformation deploy` reuses the stack's previous parameter value for any flag NOT in `--parameter-overrides`. This breaks multi-phase deploys when later phases assume a specific value for a flag that is left unspecified.

Two safe patterns:
- Pin every flag explicitly in every phase, even when its value is "the same as before."
- Design the phases so that re-running them does not toggle destructive flags.

The second is more robust. For an S3 Tables + Firehose stack, it means: do not have a Phase 1 that sets `EnableFirehose=false` and a Phase 2 that sets `EnableFirehose=true` if the resources gated on `EnableFirehose=true` include a stateful bucket (the error bucket). Re-running Phase 1 tears down the bucket, fails on bucket name cooldown, and bricks the stack. Instead collapse to a single phase that always has `EnableFirehose=true` and only toggles the actual delivery-stream flag.

## 5. `--no-fail-on-empty-changeset`

`aws cloudformation deploy` exits non-zero if the change set is empty (i.e., re-running the same template with no changes). Idempotent deploy scripts should pass `--no-fail-on-empty-changeset` so re-runs are safe:

```bash
aws cloudformation deploy \
    --stack-name "${STACK_NAME}" \
    --template-file "${TEMPLATE}" \
    --parameter-overrides ... \
    --capabilities CAPABILITY_NAMED_IAM \
    --region "${AWS_REGION}" \
    --no-fail-on-empty-changeset
```

## 6. No `DeletionPolicy` on demo-grade Redshift resources

For demo stacks meant to be torn down with a script, omit `DeletionPolicy` on the Redshift Serverless namespace and workgroup so the teardown is clean. For production, add `DeletionPolicy: Snapshot` on the namespace so accidental stack delete preserves the data. Same logic applies to the S3 Tables bucket: a demo bucket can drop, a production lakehouse cannot.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall