AWS target reference¶
What cloudseed setup aws builds, every variable you can set with --var, and every output. In the terminal: cloudseed help aws or cloudseed explain target aws.
Generated from the code
This page is generated by scripts/gen-docs.py from terraform/aws/variables.tf, terraform/aws/outputs.tf, the setup questions and skills/cloudseed-aws/SKILL.md, so it always matches the CLI you install (this build: cloudseed 0.2.3).
What it builds¶
cloudseed setup aws --env <env> builds, in one region:
- VPC (
<cidr>, default first free10.N.0.0/16), DNS on, default security group stripped of all rules. - Subnets per AZ (default 2 AZs):
public(bastion, NAT; taggedkubernetes.io/role/elbfor internet-facing load balancers),private(workloads, egress via NAT; taggedkubernetes.io/role/internal-elbfor internal ones),data(no internet route at all, no load balancer tag). The layout is pinned bysubnet_stride(the AZ count of the first deployment), soaz_countcan change later: new AZs get new subnets and nothing is re-addressed. - NAT: single gateway by default (
single_nat_gateway=true); setfalsefor one per AZ. - VPC flow logs → KMS-encrypted CloudWatch log group (30-day retention by default).
- Bastion: Amazon Linux 2023,
t3.micro, IMDSv2 required, encrypted gp3 root, Elastic IP, SSH (22) only fromallowed_ssh_cidrs, egress limited to 443/80/NTP and SSH into the VPC. Instance profile hasAmazonSSMManagedInstanceCore, so Session Manager works as a no-inbound alternative; with EKS it may also runaws eks update-kubeconfig(eks:DescribeClusteron the environment's cluster), and provisioning installs kubectl of the cluster's minor version (sha256-verified): on the bastion runaws eks update-kubeconfig --name <cluster> --region <region>, then kubectl. In FIPS mode its login shells exportAWS_USE_FIPS_ENDPOINT=true. User:ec2-user. - Workload security group (
<name>-<env>-private-workloads): SSH only from the bastion SG. Attach it to private instances. - KMS CMK with rotation for the flow/CloudWatch logs, CloudTrail and the bastion/VPN disks.
- Account-wide baseline (
enable_account_baseline=true, ONE env per account): S3 account public-access block, IAM password policy, multi-region CloudTrail (log validation, KMS, S3 with TLS-only policy, CloudWatch Logs); EBS encryption by default is switched on in its region with it. - Regional baseline (
enable_regional_baseline, null = followsenable_account_baseline; ONE env per account AND region): EBS encryption by default (AWS-managedaws/ebskey, so node groups, Karpenter and the EBS CSI driver can use it), GuardDuty, IAM Access Analyzer, and optional Security Hub FSBP (enable_security_hub=true), which also turns on AWS Config recording (delivered to the baseline log bucket - also without CloudTrail -, billed per recorded item;enable_aws_config=falsewhere Config already records in the region, e.g. Control Tower). - Remote state (when chosen): S3 bucket, versioned, SSE-KMS, public access blocked, TLS-only, native lockfile locking (no DynamoDB).
- EKS (optional,
enable_kubernetes=true, needsaz_count >= 2): private cluster in the private subnets (private API endpoint unlesskubernetes_public_endpoint=true), managed node group (AL2023; Bottlerocket FIPS AMIs in FIPS mode), KMS secret encryption, control-plane logs, core add-ons, an access entry for the bastion role only (VPN users reach the API with their own IAM identity: they need their own access entry), and IRSA roles for the EBS CSI driver, AWS Load Balancer Controller, cluster-autoscaler, external-secrets and external-dns. external-secrets may read only Secrets Manager secrets / SSM parameters underexternal_secrets_prefixes(default<name>-<env>/, e.g. secretacme-dev/db, parameter/acme-dev/db;["*"]= the whole account). Velero (bucket + role) and Karpenter (node role, instance profile, access entry, interruption queue, discovery tags; least-privilege controller policy) are added bycloudseed platform install velero|karpenter. After creation the node group is resized through the EKS API (cloudseed node add|remove|scale). - VPN host (optional,
enable_vpn=true): Ubuntu 24.04 in the public subnet running OpenVPN (default) or a Tailscale subnet router (vpn_type=tailscale, needsTS_AUTHKEY). - FIPS 140 (optional,
fips_mode=true, new environments only): FIPS endpoints for the provider and the S3 backend (so us-east-1/2, us-west-1/2 or GovCloud only), Bottlerocket FIPS nodes,fips-mode-setupon the AL2023 bastion; the Ubuntu VPN host needsUBUNTU_PRO_TOKEN(Ubuntu Pro fips-updates). SSH keys are RSA-4096 (EC2 refuses ECDSA; a key you bring must be RSA-4096). Tailscale, kubeadm and ed25519 keys are refused.
Stack variables¶
Override any of these with --var name=value on cloudseed setup aws (JSON for lists and maps; --var name=null drops a saved override). Values are read by the variable's declared type.
| Variable | Default | Description |
|---|---|---|
az_count | 2 | Number of availability zones to spread subnets across. |
subnet_newbits | 4 | Extra bits added to vpc_cidr to carve subnets (4 => /20s from a /16; at most 12, as AWS's smallest subnet is a /28). |
single_nat_gateway | true | Use one NAT gateway for all private subnets (cheaper) instead of one per AZ (more resilient). |
create_data_subnets | true | Create an isolated data tier (no internet route at all). |
enable_flow_logs | true | Send VPC flow logs to an encrypted CloudWatch log group. |
flow_log_retention_days | 30 | Retention (days) for VPC flow logs; one of the values CloudWatch Logs accepts (1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653; 0 = never expire). |
bastion_instance_type | "t3.micro" | Instance type for the bastion (e.g. t3.micro, t4g.micro). |
bastion_root_volume_size | 10 | Root volume size (GiB) for the bastion; at least 8 (the Amazon Linux 2023 image). |
enable_account_baseline | true | Manage the account-wide security settings: S3 account public-access block, IAM password policy, multi-region CloudTrail (EBS encryption by default is switched on in this region with it). Enable in only ONE environment per AWS account. |
enable_regional_baseline | null | Manage this region's security settings: EBS encryption by default, GuardDuty, IAM Access Analyzer, Security Hub/AWS Config when enabled. Enable in ONE environment per AWS account AND region (a second environment in another region keeps it on). null = same as enable_account_baseline. |
enable_cloudtrail | true | Create a multi-region, KMS-encrypted CloudTrail with log validation. |
enable_guardduty | true | Enable GuardDuty threat detection in this region (regional baseline). A detector that already exists is never adopted, so this environment's destroy never switches it off: set false to leave it alone. cloudseed setup and apply look for one before changing anything (with the aws CLI installed; otherwise the apply stops at it): while this is only on by default they leave it alone and save enable_guardduty=false; set true explicitly, they stop and name this variable. |
enable_access_analyzer | true | Create an account-level IAM Access Analyzer in this region (regional baseline). AWS allows only one per account and region (not adjustable): set false when one already exists. |
enable_security_hub | false | Enable Security Hub with the AWS Foundational Security Best Practices standard in this region (part of the regional baseline). Its controls need AWS Config recording, which is turned on with it (see enable_aws_config). |
enable_aws_config | null | Record resource configurations with AWS Config (regional baseline; delivered to the baseline's log bucket; billed per recorded item). null = on together with enable_security_hub. Set false when Config already records in this region (Control Tower, Organizations): a region holds only one recorder. |
log_retention_days | 365 | Retention (days) for CloudTrail logs (S3 lifecycle), EKS control-plane logs and the CloudTrail log group. CloudWatch keeps at most 3653 days; up to that, use a value CloudWatch Logs accepts (1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653). |
kms_deletion_window_in_days | 7 | Waiting period (7-30 days) before a destroyed KMS key is actually deleted. |
enable_kubernetes | false | Create a private EKS cluster in the private subnets. |
kubernetes_version | null | EKS Kubernetes version as MAJOR.MINOR, e.g. 1.33 (null = EKS's current default). EKS refuses versions it no longer supports. |
kubernetes_node_size | "t3.medium" | Instance type of the EKS worker nodes (Graviton types such as t4g/m7g get the arm64 image). |
kubernetes_node_count | 2 | Initial number of EKS worker nodes (at least 1: CoreDNS and the EBS CSI driver need a node), between kubernetes_node_min and kubernetes_node_max. |
kubernetes_node_min | 1 | Smallest size of the EKS node group (the autoscaler never goes below it). |
kubernetes_node_max | 4 | Largest size of the EKS node group. |
kubernetes_public_endpoint | false | Also expose the API endpoint publicly, restricted to allowed_ssh_cidrs. Default: private only (reach it via bastion/VPN). |
external_secrets_prefixes | null | Secrets Manager names / SSM parameter paths the external-secrets controller may read, as prefixes. null = <name>-<environment>/ (e.g. secret acme-dev/db, parameter /acme-dev/db). Use * for every secret in the account. |
fips_mode | false | FIPS 140 mode for the whole environment: FIPS service endpoints, FIPS node images (Bottlerocket FIPS on EKS), FIPS crypto on the bastion/VPN hosts (kernel fips=1, FIPS-only SSH algorithms), RSA-4096 SSH keys (ed25519 is not FIPS-approved; EC2/Azure refuse ECDSA). |
enable_vpn | false | Create a VPN host (OpenVPN or Tailscale subnet router) in the public subnet. |
vpn_type | "openvpn" | VPN flavour: openvpn (self-contained, client certificates) or tailscale (subnet router, needs TS_AUTHKEY). |
vpn_instance_type | "t3.micro" | Instance type of the VPN host. |
vpn_port | 1194 | UDP port the OpenVPN server listens on (1-65535; unused with vpn_type=tailscale, which uses 41641). |
Setup inputs¶
Asked by setup (or given as flags / --var KEY=VALUE); they are not Terraform variables but shape what is rendered.
| Input | Default | Flag / environment | Description |
|---|---|---|---|
profile | - | --profile, AWS_PROFILE | AWS CLI profile to use (blank = default credential chain) |
Set by cloudseed¶
These stack variables are refused in --var: cloudseed sets them itself. Use the flag shown instead.
| Variable | How to set it |
|---|---|
name | --name (default: cloudseed) |
environment | --env (default: dev) |
vpc_cidr | --cidr (default: the first free 10.N.0.0/16 across your environments) |
subnet_stride | --var az_count (the subnet layout is pinned to the AZ count of the first deployment; AZs added later get new subnets and no existing subnet moves) |
allowed_ssh_cidrs | --allow-ip or cloudseed update-ip (default: your public IP) |
ssh_public_key | the environment's generated key, or --ssh-public-key |
tags | Project/Environment/Owner/ManagedBy/CloudseedEnv/CloudseedEnvId + --tag KEY=VALUE |
platform_prereqs | managed by cloudseed platform install <item> (never set it by hand) |
Outputs¶
Read them with cloudseed output aws --env <env> (add --json for scripts).
| Output | Description |
|---|---|
account_id | AWS account the environment lives in. |
region | Region of the stack. |
vpc_id | VPC ID. |
vpc_cidr | VPC CIDR block. |
public_subnet_ids | Public subnets (bastion, NAT, load balancers). |
private_subnet_ids | Private subnets for workloads (egress via NAT). |
data_subnet_ids | Isolated data-tier subnets (no internet route). |
nat_public_ips | Public IPs your private workloads egress from (allow-list these upstream). |
bastion_public_ip | Elastic IP of the bastion. |
bastion_instance_id | EC2 instance ID of the bastion. |
bastion_security_group_id | Security group of the bastion. |
workload_security_group_id | Attach this SG to private workloads; it allows SSH only from the bastion. |
kms_key_arn | Customer-managed KMS key for logs, CloudTrail, EKS secrets and the bastion/VPN disks. |
cloudtrail_bucket | S3 bucket receiving CloudTrail logs and AWS Config snapshots (null when this environment manages neither). |
ssh_user | Login user on the bastion. |
kubernetes_cluster_name | EKS cluster name (null when Kubernetes is disabled). |
kubernetes_node_group_name | EKS managed node group; resize it through the EKS API, Terraform only sets its initial size (null when disabled). |
kubernetes_endpoint | EKS API endpoint (private unless kubernetes_public_endpoint = true). |
kubernetes_node_role_arn | IAM role of the worker nodes. |
kubernetes_oidc_issuer | OIDC issuer URL for IAM Roles for Service Accounts. |
vpn_public_ip | Public IP of the VPN host (null when VPN is disabled). |
vpn_instance_id | EC2 instance ID of the VPN host (null when the VPN is disabled). |
vpn_type | VPN flavour on the VPN host: openvpn or tailscale (null when the VPN is disabled). |
vpn_port | UDP port the VPN host listens on: vpn_port for OpenVPN, 41641 for Tailscale (null when the VPN is disabled). |
kubernetes_irsa_role_arns | IRSA roles created for platform controllers: ebs-csi, lb-controller, autoscaler, external-secrets. |
kubernetes_oidc_provider_arn | IAM OIDC provider ARN of the EKS cluster, for IRSA trust policies (null when disabled). |
kubernetes_velero_bucket | S3 bucket for Velero backups (created when the velero platform item is installed). |
kubernetes_karpenter_queue | SQS interruption queue name for Karpenter (null until the karpenter platform item is installed). |
kubernetes_karpenter_node_role | IAM role name for Karpenter-launched nodes (null until the karpenter platform item is installed). |
kubernetes_cluster_security_group_id | EKS-managed cluster security group ID (null when Kubernetes is disabled). |
fips_mode | Whether the environment was built in FIPS 140 mode. |
Gotchas¶
- GuardDuty and Security Hub are per-region singletons and are never adopted; IAM Access Analyzer allows one account analyzer per region (not adjustable). When one already exists (not this environment's) and the environment only has it on by default (GuardDuty, Access Analyzer), setup leaves it alone: it saves
enable_guardduty=false/enable_access_analyzer=falsewith the environment, says so, and plans again. Only when the variable was set true explicitly (Security Hub is always explicit) does setup stop before changing anything and name the fix ---var enable_guardduty=false/--var enable_security_hub=false/--var enable_access_analyzer=false. - Other "already exists" resources are adopted only when their tags (
CloudseedEnv+Owner) say they are this environment's; another environment's are refused, and an unreadable owner needs the user's yes (orCLOUDSEED_ADOPT=1). Adopted resources are deleted bycloudseed destroy. After an adoption the new plan is shown for approval again. - A second environment in the same account AND region uses
--var enable_account_baseline=false(the regional half follows it). An environment alone in another region of the same account uses--var enable_account_baseline=false --var enable_regional_baseline=true, so that region still gets EBS encryption by default, GuardDuty and Access Analyzer. az_countcan change on a deployed environment: the subnet layout is pinned bysubnet_stride, new AZs get new subnets and nothing is re-addressed (fewer AZs remove the last AZs' subnets, which fails while something still runs in them).--tagon AWS: keys of 1-128 and values of up to 256 letters, digits, spaces and_ . : / = + - @(IAM's set), no key starting withaws:. Where the environment creates the GuardDuty detector (the regional baseline withenable_guarddutyon, the default) keys are narrower: ASCII letters, digits and_ . : / = + -only (no space, no@), soCost CenterneedsCost-Centerthere or--var enable_guardduty=false. Setup refuses anything else before Terraform runs.- AWS China (
cn-*) and the isolated ISO regions are not supported (setup refuses them). - IAM role names include
<name>-<env>: the same env name in two regions of one account would collide with the other environment's roles. Use different env names. - A full destroy deletes CloudTrail (with its bucket), GuardDuty, Access Analyzer, Security Hub and the Config recorder, but leaves the S3 account public-access block, EBS encryption by default (in its region), the IAM password policy and the AWS Config service-linked role in place (unmanaged).
- With EKS, destroy first deletes what controllers created outside Terraform state (Karpenter NodePools and their instances, Gateway/Ingress/LoadBalancer NLBs, PVC-templated StatefulSets and Delete-policy EBS volumes); the cluster must be reachable (VPN or the bastion tunnel), otherwise it tells you what to delete by hand before the VPC deletion fails.
- Credentials:
aws configure,aws sso login, orAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEYenv vars. Never handle the values yourself. - Cost drivers: NAT gateway (hourly + per GB), bastion, EKS control plane + nodes, VPN host, CloudTrail/GuardDuty, AWS Config (with Security Hub). Destroying the env removes what Terraform created.