AWS infrastructure for the fnx tenant: Terraform root modules composed into stacks with
Atmos, deployed by Atmos workflows locally and Atmos Native CI in GitHub
Actions. Operating it (bootstrap, deploy, state, DR) is in docs/OPERATIONS.md.
The repository follows Cloud Posse: when a
Cloud Posse component or module already
models something, copy its variable names, types and defaults; use typed objects, never
map(any); document every deviation in a comment beside the code, naming the upstream source.
atmos.yaml Atmos config: version constraint, paths, name_template, Native CI, scaffolds
components/terraform/ 60 root modules (44 hand-written, 16 vendored; + _library/ shared modules and account-map/, Cloud Posse's vendored iam-roles module, which the vendored account-map-bypass providers mixin bypasses); each has a README
stacks/orgs/fnx/ org defaults (_defaults.yaml: tags, Terraform version, S3 backend) and the stacks
stacks/catalog/ abstract component defaults; templates/ holds opt-in stack templates
stacks/mixins/ tenant, stage and region mixins
workflows/ Atmos workflows (atmos list workflows); scripts/ holds the checks they run
scripts/ helpers: plan-sweep.sh (atmos sweep), lint checks, stack scaffold reader, certificates/
scaffolds/ templates for `atmos scaffold generate`
templates/, examples/ stack samples (templates/stacks), the OIDC hub/spoke example
.github/workflows/ CI/CD (below)
make help lists Makefile shortcuts around the same Atmos commands.
Names come from name_template in atmos.yaml: <tenant>-<environment>-<stage>[-<name>], Cloud
Posse's null-label id order. environment is the region code (ue1, set by
stacks/mixins/region/*), stage the account tier, and the optional settings.context.name a lane
within a stage (fixtures, emulator lanes, the templates/stacks samples). A lane deploys beside its
stage stack in the same account and region: its names carry the lane (below), and
check-lane-names.py (validate-all) fails two stacks or instances of one account and region that create the same name (and IAM/S3 names across the regions of one account). The
templates/stacks samples are such lanes: scripts/check-stack-samples.sh copies them in and runs
the stack checks (lint) and the plan sweep (atmos sweep --samples) over them. Only files under stacks/orgs/ are stack manifests;
each real stack is one file, <stage>/<region>.yaml, that imports its catalog instances and keeps
its per-stack values, grouped by domain (globals, networking, security, compute, services). EU personal data lives only in EU
stacks, tagged Compliance: "pci-sox-gdpr" (US prod is "pci-sox"): check-data-residency.py
(lint) fails a gdpr-tagged or eu- stack that lacks the tag, names a non-eu- region, turns on
Route 53 query logging (written only to us-east-1) or depends on a non-gdpr stack, and any other
stack that depends on a GDPR-scoped one or names an eu- ARN in its vars.
| Stack | Manifest (stacks/orgs/fnx/...) |
Purpose |
|---|---|---|
fnx-ue1-dev |
dev/us-east-1.yaml |
dev |
fnx-ue1-staging |
staging/us-east-1.yaml |
staging |
fnx-ue1-prod |
prod/us-east-1.yaml |
production |
fnx-ue2-prod |
prod/us-east-2.yaml |
production DR warm standby, same account; runs a subset of fnx-ue1-prod (Disaster recovery) |
fnx-ew1-prod |
prod/eu-west-1.yaml |
EU production (GDPR), its own account (prod-eu), state in fnx-ew1-root's backend; today the account and identity layer (iam/main, iam/ci), kms/main (replica in eu-central-1), the account's singletons (cloudtrail, the multi-region trail; aws-config, the global-resource recorder; cost-optimization/main, the budget) and networking: vpc/main (10.30.0.0/16; 10.31.0.0/16 reserved for an EU data VPC, 10.32.0.0/16 for fnx-ec1-prod) and network/main, the EU apex zone (its own domain, never under the US one); the regional security services as in fnx-ue1-prod (security-monitoring/main on its own trail, apigateway-account/main, backup/main copying to eu-central-1 only, acm/main for the EU apex, secretsmanager/app and /infra, replicated to eu-central-1); compute: eks/main (ew1-main), ec2/bastion, github-runners/main, external-secrets/main, eks-addons/main and eks-backend-services/main; services: rds/main, elasticache/main (a Global Datastore primary), cognito/main (the EU pool), apigateway/main (api.<EU apex>, the PRIMARY of its failover pair) and monitoring/main |
fnx-ec1-prod |
prod/eu-central-1.yaml |
EU production DR warm standby of fnx-ew1-prod (GDPR), same account (prod-eu), state in fnx-ew1-root's backend; runs what fnx-ue2-prod runs for fnx-ue1-prod, EU to EU, on fnx-ew1-prod kms/main's replica (ec1-main): iam/ci (trusting fnx-ew1-prod's OIDC provider), vpc/main (10.32.0.0/16), the regional security services (aws-config without global resources, security-monitoring/main, apigateway-account/main), backup/main (this region's vault), acm/main (api.<EU apex>); compute at its warm floor (eks/main ec1-main, ec2/bastion, github-runners/main, external-secrets/main, eks-addons/main; eks-backend-services/main disabled until failover); services: rds/main (a read replica of fnx-ew1-prod's), elasticache/main (its Global Datastore secondary), cognito/main (its own pool, with lambda/cognito-user-migration from fnx-ew1-prod's), apigateway/main (the SECONDARY of api.<EU apex>) and monitoring/main (Disaster recovery) |
fnx-ue1-root |
root/us-east-1.yaml |
management account: the US stacks' state backend (backend/main), the account's multi-region trail (cloudtrail, vendored aws-cloudtrail) and Config recorder (aws-config, its global-resource collector); not deployed by CI; plan-swept |
fnx-ew1-root |
root/eu-west-1.yaml |
management account: the EU stacks' state backend (backend/main, eu-west-1, replica eu-central-1) and the account's eu-west-1 settings (aws-account-settings, deploy-full-stack's iam layer) and Config recorder (aws-config, regional types only, fnx-ue1-root's recorder role, authorizing the EU aggregator); not deployed by CI; plan-swept |
fnx-ue2-root |
root/us-east-2.yaml |
management account in the US DR region (E5c): its us-east-2 Config recorder (aws-config, regional types only, fnx-ue1-root's recorder role, authorizing the US aggregator); the org security services' delegation in later E5c slices; state in fnx-ue1-root's backend (root_write); not run by CI |
fnx-ec1-root |
root/eu-central-1.yaml |
management account in the EU DR region (GDPR, E5c), state in fnx-ew1-root's backend (root_write): its eu-central-1 Config recorder (aws-config/main-core-region-eu: regional types only, fnx-ue1-root's recorder role, delivering to the EU archive and authorizing only the EU aggregator); the org security services' delegation in later E5c slices; not run by CI |
fnx-gbl-root |
root/global-region.yaml |
management account, global (gbl, Cloud Posse's global-region mixin): the accounts layer, deployed by atmos workflow deploy -f deploy-accounts after the backend cold start (docs/OPERATIONS.md, Bootstrap order): the Organization (aws-organization), its OUs (aws-organizational-unit/core, /plat, /eu under plat) and the management account's aws-account-settings; the member accounts (aws-account/*, until their real root-user emails) and SCPs (aws-scp/*, until E4's Identity Center roles) are disabled; not run by CI |
fnx-ue1-security |
security/us-east-1.yaml |
core security account (delegated admin of the org security services); aws-account-settings (E3e), the account's trail (cloudtrail) and Config recorder (aws-config), which also holds the US Config aggregator over every account but prod-eu (E5b), over the US regions only (owner 2026-11-13); the delegated-admin services in Wave E5c; not run by CI |
fnx-ue1-audit |
audit/us-east-1.yaml |
core audit account (log archive): aws-account-settings (E3e), the US log archive (E5a: cloudtrail-bucket, config-bucket and its kms/config-bucket key), for every account but prod-eu, and the account's own trail (cloudtrail) and Config recorder (aws-config, E5b); not run by CI |
fnx-ew1-audit |
audit/eu-west-1.yaml |
the audit account's EU stack (GDPR), state in fnx-ew1-root's backend: its eu-west-1 aws-account-settings and the EU log archive (the same three instances), for prod-eu (and, for AWS Config, the shared accounts' eu-west-1 recorders), and its own eu-west-1 Config recorder (aws-config, regional types only, fnx-ue1-audit's recorder role, authorizing the EU aggregator); not run by CI |
fnx-ew1-security |
security/eu-west-1.yaml |
the security account's EU stack (GDPR), state in fnx-ew1-root's backend: its eu-west-1 aws-account-settings and its own eu-west-1 Config recorder (aws-config, its own global-resource collector and role), which holds the EU Config aggregator, over the EU regions only, of prod-eu and the shared accounts' EU recorders (E5c); the EU delegated-admin services in Wave E5c; not run by CI |
fnx-ue2-security |
security/us-east-2.yaml |
the security account in the US DR region (E5c): its us-east-2 aws-account-settings and Config recorder (aws-config, regional types only, fnx-ue1-security's recorder role); the delegated-admin services in later E5c slices; not run by CI |
fnx-ec1-security |
security/eu-central-1.yaml |
the security account in the EU DR region (GDPR, E5c), state in fnx-ew1-root's backend: its eu-central-1 aws-account-settings and Config recorder (aws-config/main-core-region-eu: regional types only, fnx-ue1-security's recorder role, delivering to the EU archive and authorizing only the EU aggregator); the EU delegated-admin services in later E5c slices; not run by CI |
fnx-ue1-network |
network/us-east-1.yaml |
core network account (primary DNS zones, E6b; Transit Gateway hub later); aws-account-settings (E3e), the account's trail (cloudtrail) and Config recorder (aws-config, E5b), primary DNS instances disabled until a real apex; not run by CI |
fnx-ue1-identity |
identity/us-east-1.yaml |
core identity account (the teams people and automation assume roles from); aws-account-settings (E3e), the account's trail (cloudtrail) and Config recorder (aws-config, E5b); not run by CI |
fnx-ue1-artifacts |
artifacts/us-east-1.yaml |
core artifacts account (shared build artifacts); aws-account-settings (E3e), the account's trail (cloudtrail) and Config recorder (aws-config, E5b); not run by CI |
fnx-ue1-local-sandbox |
local/us-east-1/sandbox.yaml |
Floci emulator lane, no AWS account needed |
fnx-ue1-local-localemu |
local/us-east-1/localemu.yaml |
LocalEmu lane, for what Floci cannot provision (e.g. rds) |
fnx-ue1-fixtures-<name> |
fixtures/us-east-1/<name>.yaml |
one per stacks/catalog/templates/ file, checked by CI, never deployed (details) |
An instance name need not match its module: metadata.component decides. network/main and
network/services are dns instances; network/vpc-peering is the network module.
- Atmos >= 1.229.0 (fatal constraint in
atmos.yaml). Atmos installs Terraform and the lint/scan tools from thedependencies.toolspins (stacks/orgs/fnx/_defaults.yamland each workflow; bumping them). - Emulator lanes: Docker for the sandbox (Floci); Python 3.13 exactly for LocalEmu (a pip package, no Docker). AWS credentials only for plans/applies against real accounts.
- The stacks still hold placeholder account IDs, domains and alert addresses: see first-deploy inputs.
atmos list stacks # also: list components, list workflows
atmos describe component vpc/main -s fnx-ue1-dev --process-functions=false
atmos validate stacks # offline
atmos workflow tflint-init -f lint # once
atmos workflow lint -f lint # fmt, yamllint, TFLint and the lint-side repo checks
atmos workflow security-scan -f lint # Trivy + Checkov gate (any HIGH/CRITICAL not suppressed inline)
atmos workflow validate-all -f validate-enhanced # schema, stacks, dependency/layer/domain checks, fmt, terraform validate
atmos sweep -s fnx-ue1-dev # plan with resolved variables, no AWS account needed (--help)
atmos workflow providers-lock -f providers # after a required_providers change: rewrite the committed locks
atmos workflow sandbox -f sandbox # apply against Floci, then destroy (Docker only)
atmos workflow localemu -f localemu # the same against LocalEmu (Python 3.13)
atmos terraform plan vpc/main -s fnx-ue1-dev # needs AWS credentialsterraform validate never evaluates variable validation blocks; atmos sweep and the emulator
lanes do. Run the emulator lanes through their workflows: by hand, sandbox commands need
--identity local-aws, and LocalEmu commands need --identity local-emu plus
LOCALEMU_ACCESS_KEY_ID, LOCALEMU_SECRET_ACCESS_KEY and AWS_ENDPOINT_URL, or the apply reaches
real AWS (workflows/localemu.yaml).
Add a component: atmos scaffold generate component . --force (run from the repo root; it
also writes the catalog entry). atmos scaffold generate catalog-entry . --force adds catalog
defaults for an existing component.
Add a stack: atmos scaffold generate stack . --force (run from the repo root) writes a stage
stack and wires it into the state backend; see
Adding a stack.
Add an instance: write it as stacks/catalog/<c>/<i>[-<flavor>].yaml, with
metadata.component (and inherits for the catalog base), import it from the stack file, which
keeps only the stack's own values for it, then list every instance it reads
in dependencies.components and make sure a layer in workflows/deploy-full-stack.yaml deploys
it after them. validate-all fails otherwise. A new stack also needs its CI roles in the state
backend's trust: see State backend. A prod primary also sets
settings.dr.region, its DR standby's region: the prod catalog files fail to render without it
(see Disaster recovery).
- Cross-component values use YAML functions (
!terraform.state vpc/main .vpc_id), never${...}. Every instance read must be in the reader'sdependencies.components, and every output read and var set must be declared by its module (workflows/scripts/common/check-dependencies.py). - Disable an instance with
metadata.enabled: false, never by deleting it. - Component names are singular without hyphens (
securitygroup); snake_case everywhere; boolean variables start withis_,has_orenable_. - Tags (
Tenant,Account,Environment,Stage,ManagedBy) come fromstacks/orgs/fnx/_defaults.yaml, built fromsettings.context, and are applied once throughdefault_tagsin eachprovider.tf, not per resource.Environmentissettings.prefix: the region code, plus-<name>on a lane (ue1,ue1-serverless). Components start their names with it, and a stack template that repeats such a name writes{{ .settings.prefix }}-<x>. - Names that are global without an account id (S3 buckets without an account suffix, Cognito
domains) start with the full id, the stack name
<tenant>-<environment>-<stage>[-<name>]({{ .atmos_stack }}in a template), so a lane gets its own. Account-suffixed names (<Environment>-<name>-<account_id>: thes3default, VPC flow logs, CloudTrail, AWS Config, ALB logs) are unique per account and region, because each stage has its own account (the Cloud Posse model). A value that means the tier (API Gatewaystage_name,ENVIRONMENTvariables, Kubernetesenvironmentlabels) readssettings.context.stage, neverenvironment. settings.list_merge_strategy: replace: a list in a more specific file replaces the inherited one.- Each component has
variables.tf(with validation blocks),outputs.tf(sensitive = truewhere needed),versions.tf(>= 1.16.0, < 2.0.0),provider.tfand aREADME.mdcovering purpose, wiring and gotchas only;variables.tfandoutputs.tfare the interface reference. - Encrypt at rest and in transit; least-privilege IAM; secrets in Secrets Manager, never committed.
Inbound access never allows
0.0.0.0/0or::/0; egress is unrestricted.
Jobs run in the ghcr.io/cloudposse/atmos container and use GitHub OIDC. AWS jobs are skipped
until the repository variable AWS_PLAN_ROLE_ARN is set.
| Workflow | Trigger | What it does |
|---|---|---|
terraform-ci.yml |
PR, merge queue, push to master | PR/merge queue: lint + validate-all, actionlint (when .github/workflows/ changes), plan sweep (atmos sweep --all, split by sweep-shards.py into parallel legs), Trivy/Checkov gate (any HIGH/CRITICAL not suppressed inline or, in vendored code, by scripts/check-checkov-allowlist.py; no baselines); PR only: plan of affected non-prod instances, each with its stack's read-only iam/ci plan role (PR comment), except the in-cluster components (a notice: in-vpc.yml plans them on master only). terraform test for components with tests/: affected ones on PRs, all on merge queue and push. Push to master otherwise runs only the prod plan. A changes job skips the jobs whose paths did not change; CI gate, the check master's protection requires, runs on every PR and fails if any job, the emulator lane included, failed |
emulator.yml |
called by terraform-ci.yml, manual |
LocalEmu lane: applies and destroys real resources |
terraform-cd.yml |
push to master, manual | Per stack (dev, staging, prod): deploys what changed since its deployed/<stack> tag with that stack's iam/ci apply role, then moves the tag; the in-cluster components deploy on the stack's in-VPC runners (in-vpc.yml). Stops at the first failed stack; a prod delete or replace needs an Allow-Destroy: trailer (details). No manual approval (details) |
drift-detection.yml |
hourly, manual | Read-only plan of every stack, the in-cluster components on the in-VPC runners; drift fails the job |
in-vpc.yml |
called by the three above | Starts an ephemeral self-hosted runner in the stack's VPC and runs the in-cluster components there, on the default branch only, with the stack's apply role (a PR gets a notice instead of their plan); the runners themselves refuse fork code |
security-scan.yml |
nightly, manual | Report-only Trivy + Checkov |
disaster-recovery.yml |
manual | Read-only DR checks (dr-status, recover-state, recover-database) |
release.yml |
push to master, manual | release-please: keeps the release PR (next semver, CHANGELOG.md) open; merging it tags vX.Y.Z (releases). Skipped until the release GitHub App is configured |
MIT, see LICENSE.