00 Setup — instructor notes

Budget 30 to 45 minutes, and treat it as a gate rather than a warm-up. Every failure in this module is cheap here and expensive later: a missing rds:CreateDBParameterGroup surfaces as a half-built stack in module 01, and an old pg_dump surfaces inside module 04's cutover window.

Before the session

• Send the learner setup module out at least a day ahead. Installing WSL can require a Windows restart, and a corporate AWS permission request cannot be resolved in the room.
• Ask every participant to run the two AWS probes and report the result before the session: aws rds describe-db-parameter-groups --max-items 1 and aws ec2 describe-security-groups --max-items 1. This is the single highest-value piece of pre-work; a participant who fails both cannot do modules 01 through 03 at all.
• Ask for clickhousectl cloud org list too, and treat an empty result or FORBIDDEN the same way as a failed AWS probe. Module 03 creates the Managed Postgres instance with this CLI, so a key that authenticates but cannot create services strands the participant at the start of the longest module. It is the ClickHouse-side twin of the AWS permission request, and it has the same lead time in a centrally administered organization.
• Pin one region for the room and say it out loud. ClickHouse Managed Postgres is in beta with a narrower region list than RDS, and a cross-region pair changes every replication-lag number module 03 asks participants to read.
• Confirm the AWS cost figure in the learner page still matches current pricing for the region you picked, and tell participants the number before they apply anything.
• Have a shared AWS account with a known-good role ready as a fallback, with a name_prefix per participant so one account can host several stacks.

Talk track

Two points are worth making here rather than in module 03, because they are what the setup is for:

• The three RDS logical-replication prerequisites are a set. The parameter group plus reboot, backup_retention_period >= 1, and the rds_replication grant. Say explicitly that missing the reboot fails loudly and missing either of the others fails silently: a publication that works, a subscription that reports no error, and rows that never arrive.
• subscriber_cidrs has no default on purpose. The subscriber dials out to the participant's RDS instance, so the allowlist is the one piece of the Terraform nobody can fill in for them. Preview that they will come back and widen it in module 03.

Common failures

• AWS permissions. AccessDenied on the parameter group or the security-group rule. Move the participant to the fallback account rather than debugging IAM in the room.
• pg_dump older than the server. On Ubuntu, the PGDG pin was skipped or apt-get install picked the distro's postgresql-client. On macOS, a postgresql@14 formula shadows Homebrew's libpq. Check pg_dump --version in the room, per participant; do not accept psql --version.
• Windows work done in PowerShell. Terraform and the AWS CLI must be the Ubuntu copies. A Windows terraform.exe cannot see the Linux checkout or the Linux credentials file, and the failure appears as a confusing state or credentials error much later.
• The clone landed under /mnt/c. Have them check that pwd begins with /home/ and re-clone if not. Cheaper now than after a seed has run.
• terraform apply run early. Module 00 ends at terraform validate. An early apply starts the bill and skips the reboot beat module 01 teaches.
• clickhousectl authenticates but cannot create. cloud auth status shows saved credentials while cloud org list returns empty or FORBIDDEN, because the API key's role is too narrow. The check that matters is the second one; the first passes with a key that cannot do the job. There is no room-side fix — the participant needs a new key from whoever administers the organization, which is why it is pre-work.

Credentials hygiene

Never ask a participant to paste AWS keys, the generated RDS admin password, or a ClickHouse Cloud API secret into chat, slides, a shared terminal, or a committed file. terraform.tfvars and terraform.tfstate both stay local; the state file contains the generated admin password. If you demo on your own screen, use a throwaway account and rotate afterwards.

End checkpoint

Do not start module 01 until every participant can show, in the shell they will use for the rest of the workshop:

• pg_dump --version at 17 or newer;
• terraform validate reporting the configuration valid, with a terraform.tfvars containing their region and their own address;
• both AWS probes printing ok; and
• on Windows, Ubuntu at VERSION 2 and a checkout path beginning /home/.

A participant still failing the AWS probes goes to the fallback account now. Pairing is the second-best option and costs them the cutover exercise, which is the workshop's core.