Skip to content

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 free 10.N.0.0/16), DNS on, default security group stripped of all rules.
  • Subnets per AZ (default 2 AZs): public (bastion, NAT; tagged kubernetes.io/role/elb for internet-facing load balancers), private (workloads, egress via NAT; tagged kubernetes.io/role/internal-elb for internal ones), data (no internet route at all, no load balancer tag). The layout is pinned by subnet_stride (the AZ count of the first deployment), so az_count can change later: new AZs get new subnets and nothing is re-addressed.
  • NAT: single gateway by default (single_nat_gateway=true); set false for 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 from allowed_ssh_cidrs, egress limited to 443/80/NTP and SSH into the VPC. Instance profile has AmazonSSMManagedInstanceCore, so Session Manager works as a no-inbound alternative; with EKS it may also run aws eks update-kubeconfig (eks:DescribeCluster on the environment's cluster), and provisioning installs kubectl of the cluster's minor version (sha256-verified): on the bastion run aws eks update-kubeconfig --name <cluster> --region <region>, then kubectl. In FIPS mode its login shells export AWS_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 = follows enable_account_baseline; ONE env per account AND region): EBS encryption by default (AWS-managed aws/ebs key, 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=false where 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, needs az_count >= 2): private cluster in the private subnets (private API endpoint unless kubernetes_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 under external_secrets_prefixes (default <name>-<env>/, e.g. secret acme-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 by cloudseed 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, needs TS_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-setup on the AL2023 bastion; the Ubuntu VPN host needs UBUNTU_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=false with 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 (or CLOUDSEED_ADOPT=1). Adopted resources are deleted by cloudseed 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_count can change on a deployed environment: the subnet layout is pinned by subnet_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).
  • --tag on AWS: keys of 1-128 and values of up to 256 letters, digits, spaces and _ . : / = + - @ (IAM's set), no key starting with aws:. Where the environment creates the GuardDuty detector (the regional baseline with enable_guardduty on, the default) keys are narrower: ASCII letters, digits and _ . : / = + - only (no space, no @), so Cost Center needs Cost-Center there 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, or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env 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.