Skip to content

jaingxyz/aws-data-skills / skills/streaming-into-data-lake

streaming-into-data-lake

Verified

Stream rows continuously into Apache Iceberg tables on S3 Tables (or standard Iceberg on a general purpose bucket) using Amazon Data Firehose with IcebergDestinationConfiguration. Covers the Firehose stream, the optional record-shaping Lambda (ProcessingConfiguration), the Lake Formation grants required for Firehose to write through Glue, and the three-phase CloudFormation deploy that gates the stream on grants existing. Triggers on: stream into data lake, Firehose to S3 Tables, Firehose to Iceberg, real-time ingestion to Iceberg, Firehose IcebergDestinationConfiguration, stream Kinesis to Iceberg, near real-time CDC to data lake, continuous append to Iceberg. Do NOT use for: batch file imports (use ingesting-into-data-lake), creating the destination Iceberg table itself (use creating-data-lake-table), the one-time Lake Formation onboarding (use setting-up-lake-formation), finding tables by fuzzy name (use finding-data-lake-assets), running queries (use querying-data-lake), Glue connections (Firehose does not use them; do not invoke connecting-to-data-source), Kinesis to Lambda to Redshift Data API direct writes (not Iceberg; recommend a different workflow), or producer-side Kafka or MSK setup.

references/three-phase-deploy.md

View on GitHub
# Two-Phase CloudFormation Deploy (collapsed from three)

Defining the Firehose stream, the Firehose IAM role, and the Lake Formation grants in a single CloudFormation template creates a race. CloudFormation evaluates the Firehose role's effective permissions at stream-create time, before the Lake Formation grants apply. The stream creation fails with `AccessDeniedException` even though every grant in the template is correct.

The fix is to gate the Firehose stream resource on a CloudFormation `Condition` and deploy in **two effective phases** controlled by `EnableFirehose` (always `true` after first deploy) and `EnableFirehoseStream` (toggled from `false` to `true` once grants exist).

> **Note on the historical 3-phase shape.** An earlier version of this skill prescribed three phases: `EnableFirehose=false / Stream=false` (base), `EnableFirehose=true / Stream=false` (role + grants), then `Stream=true`. That collapsed in the companion repo to two effective phases because Phase A already creates the namespace and bucket; a separate "before role exists" pre-phase is redundant and re-running it tears down the error bucket / role / log group on subsequent runs (CFN parameter-inheritance footgun, below). Keep `EnableFirehose=true` from first deploy onward and only toggle `EnableFirehoseStream`.

## Template structure

```yaml
Parameters:
  EnableFirehose:
    Type: String
    Default: "false"
    AllowedValues: ["true", "false"]
    Description: Phase 2 onward. Creates the Firehose IAM role and grants.
  EnableFirehoseStream:
    Type: String
    Default: "false"
    AllowedValues: ["true", "false"]
    Description: Phase 3 only. Creates the delivery stream.

Conditions:
  CreateFirehoseRole: !Equals [!Ref EnableFirehose, "true"]
  CreateFirehoseStream: !And
    - !Equals [!Ref EnableFirehose, "true"]
    - !Equals [!Ref EnableFirehoseStream, "true"]

Resources:
  FirehoseRole:
    Type: AWS::IAM::Role
    Condition: CreateFirehoseRole
    # ...

  LFGrantOnTable:
    Type: AWS::LakeFormation::PrincipalPermissions
    Condition: CreateFirehoseRole
    # ...

  DeliveryStream:
    Type: AWS::KinesisFirehose::DeliveryStream
    Condition: CreateFirehoseStream
    # ...
```

## Deploy sequence

```bash
# Phase A: bucket + namespace + Firehose IAM role + transform Lambda + error
# bucket. Stream is held back. After CFN finishes, apply Lake Formation
# grants to the role using the lf_grant helper (see lake-formation-grants.md).
aws cloudformation deploy \
  --stack-name <stack> \
  --template-file template.yaml \
  --parameter-overrides \
    EnableFirehose=true \
    EnableFirehoseStream=false \
  --capabilities CAPABILITY_NAMED_IAM

# Apply LF grants here (out-of-CFN; see lake-formation-grants.md for the
# lf_grant helper). The grants need a real IAM principal to exist (which
# Phase A just created), and CFN cannot represent the loud-failure
# semantics the lf_grant helper enforces.

# Phase B: turn on the Firehose delivery stream. With grants now in place
# and propagated, CFN's stream-create call passes.
aws cloudformation deploy \
  --stack-name <stack> \
  --template-file template.yaml \
  --parameter-overrides \
    EnableFirehose=true \
    EnableFirehoseStream=true \
  --capabilities CAPABILITY_NAMED_IAM
```

Wait at least 30 seconds between Phase A grant application and Phase B for Lake Formation grant propagation.

## The parameter-inheritance footgun

`aws cloudformation deploy --parameter-overrides` does NOT inherit values from the previous deploy. Any parameter omitted from the CLI invocation reverts to its template default. With `Default: "false"` on the gate parameters, Phase 3 deploys that omit `EnableFirehose=true` will set it back to `false`, evaluate `CreateFirehoseRole` as false, and tear down the Firehose role and Lake Formation grants the previous phase created.

You MUST pass every gate parameter explicitly on every `aws cloudformation deploy` call after Phase 1, even ones whose value did not change. Wrap the deploy in a shell script that always exports both flags so this cannot be forgotten:

```bash
deploy_phase() {
  local enable_firehose="$1"
  local enable_stream="$2"
  aws cloudformation deploy \
    --stack-name "${STACK_NAME}" \
    --template-file template.yaml \
    --parameter-overrides \
      "EnableFirehose=${enable_firehose}" \
      "EnableFirehoseStream=${enable_stream}" \
    --capabilities CAPABILITY_NAMED_IAM
}
```

`--no-fail-on-empty-changeset` is safe to add. It does not affect parameter inheritance.

## Why this is not solvable with DependsOn

`DependsOn` makes CloudFormation wait until the listed resource finishes creating before starting the next. It does not wait for IAM policy or Lake Formation grant propagation, which is asynchronous and not visible to CloudFormation. Even with `DependsOn: [FirehoseRole, LFGrantOnTable]` on the delivery stream, the create-stream call from CloudFormation can race ahead of grant propagation.

The three-phase pattern works because each phase ends with a stable stack state, and the gap between phases (the time the operator takes to invoke the next `deploy`) gives Lake Formation time to settle.

## Drift after Phase 3

After Phase 3 succeeds, the stack is in its target state with both flags `true`. Subsequent deploys to fix unrelated resources MUST keep both flags `true`. Add a guardrail comment in the deploy script.

## Teardown

Reverse the order. Set `EnableFirehoseStream=false` first (Phase 3 reverse), wait, then `EnableFirehose=false` (Phase 2 reverse), then delete the stack. Tearing down all at once is safe but produces noisy CloudFormation events as the Firehose stream tries to write while its IAM role is being destroyed.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall