Help topics¶
The guides built into the CLI (cloudseed help <topic>). Topics that share a name with a command (deps, agentic, destroy) are part of that command's page in the command reference.
Generated from the code
This page is generated by scripts/gen-docs.py from the CLI's help topics (cloudseed/help.py), so it always matches the CLI you install (this build: cloudseed 0.2.3).
Quickstart¶
cloudseed help quickstart
1. cloudseed doctor # what's installed, how you're authenticated
2. log in: aws configure | gcloud auth application-default login | az login
3. cloudseed setup aws # answer the prompts; a plan is shown before anything is created
4. cloudseed ssh aws --env dev # you're on the bastion; workloads go in the private subnets
5. cloudseed status aws --env dev # outputs: subnet IDs, workload SG / tag, bastion IP
6. cloudseed destroy aws --env dev # when you're done (clean slate: --purge-state --purge)
Non-interactive: add -y and the flags for every answer, plus --auto-approve.
Security model¶
cloudseed help security
Network
- Only the bastion (and the optional VPN host) has a public address. The cloud firewall admits TCP/22 from --allow-ip
only: IPv4, nothing wider than a /8 and at most two /8s in all (0.0.0.0/0 is refused), a range written as its
network (an address with host bits such as 203.0.113.7/24 is refused); `update-ip` changes it. The host's own
nftables firewall denies all other inbound traffic.
- Workloads live in private subnets behind NAT; the isolated data tier (AWS) has no internet route.
- Default security groups are stripped (AWS); explicit deny-all inbound rules on GCP (logged) and on Azure NSGs
(not logged: NSG / VNet flow logs are not managed yet).
- Bastion egress is limited (AWS): 443/80 for updates, NTP, SSH into the VPC.
Hosts
- Key-only SSH, root login and password auth disabled, latest LTS images, encrypted disks.
- AWS: IMDSv2 required, SSM Session Manager available as a no-inbound alternative.
- GCP: Shielded VM, dedicated least-privilege service account, project SSH keys blocked.
- Azure: Trusted Launch (secure boot + vTPM), managed identity.
Logging & account baseline
- VPC / subnet flow logs, NAT and firewall logging (AWS, GCP); Azure: no NSG / VNet flow logs yet.
- AWS, in two halves. Account-wide (enable_account_baseline, one environment per account): multi-region CloudTrail
with validation + KMS, S3 account public-access block, IAM password policy. Regional (enable_regional_baseline,
one environment per account AND region; it follows enable_account_baseline unless set): EBS default encryption
(AWS-managed aws/ebs key), GuardDuty, Access Analyzer (one per region: --var enable_access_analyzer=false when one
exists), optional Security Hub FSBP (which turns on AWS Config recording; --var enable_aws_config=false where
Config already records). A second environment in the same region: --var enable_account_baseline=false; one alone
in another region: add --var enable_regional_baseline=true. An existing GuardDuty detector, Security Hub or
account Access Analyzer is never adopted: while it is only on by default here, setup leaves it alone and saves
enable_guardduty=false (enable_access_analyzer=false) with the environment; one you set true explicitly stops setup
before anything changes (pass --var enable_guardduty=false / enable_security_hub=false).
A full destroy leaves the S3 public-access block, EBS default encryption, the password policy and the AWS Config
service-linked role in place (no longer managed) and deletes CloudTrail, GuardDuty, Access Analyzer, Security Hub
and the Config recorder.
- GCP: _Default log bucket retention, optional Data Access audit logs (allServices). Both are project-wide: one
environment per project manages them (--var enable_project_baseline=false for the others), and a destroy keeps
both - the retention stays at the value cloudseed set, the audit logs stay on.
- Azure: Activity Log -> Log Analytics, optional Microsoft Defender for Servers / Storage (subscription-wide: enable
it in one environment only; destroy leaves it on).
State
Agentic mode
- Agents never receive credentials: secret env vars (and the vault's secrets) are stripped from the agent's
environment and served to child cloudseed commands over a per-session unix socket (nothing on disk; the session
ends with the agent); prompts and cloudseed's output are redacted, kubectl, helm, databricks and snowflake output
included. They run without a terminal there, so k9s, kubectl edit, kubectl exec/attach/run/debug -i/-t, calls
that never end (logs -f, get/events -w, port-forward, proxy: use --tail/--since or kubectl wait --timeout), a
browser sign-in (databricks auth login), prompts and the interactive snow sql shell are refused with exit code 2:
run those in your own terminal. `dr schedule --ttl 30d` is taken as 720h.
- The built-in agent can only run cloudseed commands. In every agent session cloudseed itself refuses agentic,
enable, disable and the changing forms of install, deps, skill, creds, use, model, ui and mcp with the command for
you; their read-only forms work (creds list, model, use list, install list, ui status|logs, mcp
status|guide|tools|config|test|logs, deps status, skill list|show). The built-in agent also refuses ssh, k9s and
mcp serve, and its changes need your approval. Claude Code runs with cloudseed's secret files denied; Codex, Gemini and
Grok can read any file you can, so only the skills keep them away from credential/state files.
Terraform state¶
cloudseed help state
remote (default) cloudseed first creates hardened state storage in your account:
AWS S3 (versioned, SSE-KMS, TLS-only, native lockfile locking),
GCS (versioned, public-access prevention), Azure Storage (TLS1.2, versioning, soft delete).
Backend config is saved in the env config; the bucket is only deleted with --purge-state.
local <workdir>/stack/terraform.tfstate (default workdir: ~/.cloudseed/envs/<cloud>-<env>)
Switching: re-run cloudseed setup <cloud> --env <env> --state local|remote; state is migrated automatically. Rendered roots (main.tf.json) live next to the state; the checked-in Terraform stays generic.
Environments and config¶
cloudseed help envs
Each environment has a working directory, created by cloudseed: ~/.cloudseed/envs/<cloud>-<env> by default, or any path given with setup --workdir PATH (remembered in ~/.cloudseed/workdirs.json). It contains:
config.json everything you answered (name, region, CIDR, allowed IPs, vars, tags, state backend)
ssh/ generated key pair: ed25519, RSA-4096 in FIPS mode (unless you supplied one); known_hosts
logs/ audit.jsonl + one redacted log per command; inventory.json what exists + history
stack/ rendered Terraform root (main.tf.json), provider cache, local state
bootstrap/ root for the remote state storage
outputs.json cached outputs (used by `ssh`, `list`, the headliner)
Naming: every resource is <name>-<env>-<thing>; tags/labels Project, Environment, Owner, ManagedBy=cloudseed, CloudseedEnv=<cloud>-<env> and CloudseedEnvId (the environment's unique id) plus your --tag values. Tag keys are case-insensitive (--tag owner=alice sets Owner), --tag KEY= removes a saved tag, and ManagedBy, CloudseedEnv and CloudseedEnvId cannot be set (reconcile reads them to tell this environment's resources from anyone else's). Defaults are picked for you: name=cloudseed, env=dev, CIDR=first free 10.N.0.0/16, region from env vars or a sensible default.
Optional services¶
cloudseed help services · Enable per environment with --var, or answer the setup prompts.
enable_kubernetes=true private Kubernetes: EKS / GKE / AKS, RKE2 or kubeadm VMs on vmware -> cloudseed help k8s
enable_vpn=true VPN host: OpenVPN (default) or Tailscale (cloud targets) -> cloudseed help vpn
vpn_type=tailscale subnet router instead of OpenVPN (needs TS_AUTHKEY)
After setup applies, provision copies this repo to the bastion and VPN host and configures them with Ansible (hardening + tools + VPN server). Everything is re-runnable: cloudseed provision <cloud> --env <env>.
Local virtual machines¶
cloudseed help vmware · cloudseed setup vmware
Same shape as a cloud environment, on your own machine:
- VMware Fusion Pro 13+ (macOS, Intel or Apple Silicon) or Workstation Pro 17+ (Linux; Windows detection is
experimental, and native environment changes are unsupported: no locking or native Ansible control node) - both free; older releases are refused for new environments.
cloudseed detects which one is installed (VMWARE_HOME when set: a wrong one is reported by name), its version, and
the host architecture, and picks matching guest images (arm64 guests on Apple Silicon, amd64 elsewhere).
- A bastion VM with two NICs: NAT (reachable from your machine) and a private host-only network it
routes/NATs for. Optional workload VMs live only on the private network (`--var workload_count=N`).
- The private network is VMware's built-in host-only vmnet (vmnet1 on Fusion): its subnet and DHCP setting are
adopted (VMware serves DHCP on its upper half, e.g. .128-.254) and the VMs use fixed addresses below the DHCP pool:
bastion .2, workloads .10+ (at most 10 with Kubernetes on), control planes .20-.39 (1-20), workers .40-.99 (at
most 60 on a /24): .100-.127, just below VMware's DHCP pool, are kept for MetalLB's LoadBalancer pool. An
existing cluster that already has more workers is warned, not refused (remove the ones above wk60 before using
LoadBalancer services).
Every environment without --cidr gets that same vmnet, so only one of them can have VMs: a second one is refused
while another has VMs. `--cidr X` asks for a dedicated vmnet with DHCP off instead (VMware only lets root create
networks: run `sudo vmrest` and export VMREST_USER/VMREST_PASSWORD for it). An explicit --cidr must be a private
(RFC 1918) range: a public one would hide the real hosts of that range from this computer, and one containing
1.1.1.1 or 8.8.8.8 would also cut the VMs off from their DNS servers.
With Kubernetes on, the network must not overlap the cluster's pod or Service range (RKE2 10.42.0.0/16 +
10.43.0.0/16, kubeadm 10.244.0.0/16 + 10.96.0.0/16): setup refuses it for a new environment or when Kubernetes is
turned on, and only warns for a cluster that already runs there.
- Guest OS: ubuntu-24.04 (default), ubuntu-22.04, debian-12 (`--var guest_os=...`). Official cloud images
are downloaded and checksum-verified; qcow2 images are converted with qemu-img (installed on demand).
- cloud-init (NoCloud ISO + VMware guestinfo) creates your user with the generated SSH key; Ansible then
hardens the bastion exactly like in the cloud (nftables also NATs the private network). Workload VMs are not
Ansible-hardened: cloud-init bootstraps them and turns on unattended security updates (VMs created by this
version). Kubernetes nodes are hardened by the Kubernetes play and deliberately not auto-updated (node upgrades
are yours to schedule).
- Terraform all the way: cloudseed ships its own provider (providers/vmdesktop, Go) built once on first
use into ~/.cloudseed/providers and wired through ~/.cloudseed/terraform.rc; building it needs Go >= 1.25
(`cs doctor` shows an older Go as too old; `cs install go` upgrades it). Resources:
vmdesktop_network (adopts or creates a vmnet via vmrest), vmdesktop_vm (vmrun + vmware-vdiskmanager),
data vmdesktop_host.
- Kubernetes on VMs: `--var enable_kubernetes=true` adds control-plane and worker VMs on the private network and
installs RKE2 (default: single binary, Canal CNI) or kubeadm (upstream, containerd + Flannel) with Ansible run
from this machine (installed into ~/.cloudseed/venv-ansible on first use). RKE2's CIS hardening profile is not
enabled unless --var kubernetes_cis_profile=true (RKE2 only; it enforces the restricted Pod Security Standard
outside the exempt namespaces - RKE2's system ones plus cloudseed-scan, velero, local-path-storage, minio and
chaos-mesh -, and `cs platform install` labels the namespaces of catalog items that need privileged or baseline
pods before installing them; `cs platform info <item>` shows the level). Nodes added later join at the version
the cluster runs, and adding a control plane leaves the workers alone. kubernetes_version pins the release instead (RKE2: v1.36.4+rke2r1, installed by
every new node; kubeadm: 1.35, for a new cluster only; empty = RKE2's stable channel / kubeadm's supported
default); it never upgrades a node that is already installed. The kubeconfig lands in
<workdir>/k8s/kubeconfig; `cs k8s kubeconfig vmware` merges it into ~/.kube/config and makes it the current
context.
Sizes: kubernetes_control_planes (1), kubernetes_workers (2; 0 = the control planes run the workloads),
kubernetes_cpus/memory_mb/disk_gb.
- Sizes can change later: CPUs and memory in place (the VM restarts), a larger *_disk_gb grows the disk in place,
a smaller one rebuilds the VM (the plan shows it as a replace). Floors: 1 vCPU, 512 MB of memory in multiples of
4, 10 GB of disk (Kubernetes nodes 20 GB); kubeadm needs 2 vCPUs and 2048 MB per node, RKE2 2048 MB; no VM may
have more vCPUs or memory than this computer.
- Rebuilds: changing `packages` rebuilds the bastion and the workload VMs; ssh_username, the SSH key, guest_os,
vm_dir or --name rebuild every VM, Kubernetes nodes included (the plan says "must be replaced"). To add packages
to running VMs, install them over `cloudseed ssh` instead.
- A VM bundle in vm_dir named like one of this environment's VMs but unknown to its state (an earlier environment of
the same name, lost state) is moved aside to <name>.replaced-<time>.vmwarevm, never deleted; a running one stops
the apply.
- State is always local, inside the environment's working directory (`--workdir PATH` to choose it). The VM files
go to <workdir>/vms (vm_dir: an absolute path, ~/..., or a path relative to the working directory). No VPN is
needed (the host talks to the bastion directly); update-ip does not apply.
- destroy removes only this environment's VMs and files (other VMs in vm_dir are left alone); with --purge it stops
vmrest only when cloudseed started it and nothing else uses it.
If VMware is missing, setup vmware opens Broadcom's download page (free, login required), waits for the installer in ~/Downloads and installs it (cloudseed install vmrun [--from FILE] does the same on demand).
VMware's REST service (vmrest) is configured by cloudseed itself: it generates credentials, runs vmrest -C non-interactively, stores them in ~/.cloudseed/vmware.json (0600) and starts vmrest in the background. Set VMREST_USER/VMREST_PASSWORD only if you want to use your own (then run vmrest -C yourself once when vmrest was never configured for this OS user; cloudseed says so).
Examples
cloudseed setup vmware # bastion only
cloudseed setup vmware --env lab --var workload_count=2 --var guest_os=debian-12
cloudseed ssh vmware --env lab
cloudseed status vmware --env lab # workload_private_ips, private_vmnet
cloudseed destroy vmware --env lab
cloudseed install vmware-provider --rebuild # rebuild the provider after changing its source
FIPS 140 mode¶
cloudseed help fips · cloudseed setup <cloud> --var fips_mode=true
One switch for the whole environment; everything cloudseed puts into it must be FIPS-capable or setup / install refuses.
AWS provider + S3 state backend use the FIPS endpoints (so only us-east-1/2, us-west-1/2 and the GovCloud
regions); EKS node groups use Bottlerocket FIPS AMIs; the bastion (Amazon Linux 2023) gets
`fips-mode-setup --enable` (kernel fips=1, FIPS crypto policy) and a reboot. The VPN host is Ubuntu: it
attaches Ubuntu Pro (export UBUNTU_PRO_TOKEN before setup) and enables fips-updates.
GCP bastion and VPN host use the Ubuntu Pro FIPS 22.04 image (metered, no token needed); GKE nodes stay on
Container-Optimized OS (FIPS-validated kernel crypto module and BoringCrypto). A custom bastion_image must
be Ubuntu (a plain Ubuntu image without Pro needs UBUNTU_PRO_TOKEN) or RHEL-family; others are refused.
Azure bastion/VPN use the Ubuntu Pro FIPS marketplace image (terms accepted for you); the AKS node pool is created
with fips_enabled = true.
VMware every VM attaches Ubuntu Pro (export UBUNTU_PRO_TOKEN - free for personal use) and enables fips-updates, then
reboots; guest_os must be Ubuntu; Kubernetes must be RKE2 (FIPS-validated Go crypto; kubeadm is refused).
hosts sshd offers only FIPS-approved algorithms (AES-GCM/CTR, SHA-2 HMACs, ECDH P-curves, RSA/ECDSA host keys);
environments are created with an RSA-4096 SSH key (id_rsa) instead of ed25519: ed25519 is not FIPS-approved
and EC2 and Azure refuse ECDSA. A key you bring must be RSA-3072 or larger (RSA-4096 on AWS), or ECDSA on GCP / VMware;
OpenVPN restricts data and TLS ciphers to AES-GCM suites; Tailscale (WireGuard/ChaCha20) is refused.
platform catalog items come in four tiers: compatible (controllers and services: installed), tls-restricted
(the TLS terminators envoy-gateway and ingress-nginx: installed with TLS pinned to 1.2+ and FIPS cipher
suites, but their proxy crypto is not a validated module, so `cs scan fips` flags them), crypto-restricted
(items whose job is cryptography in a non-validated module - cert-manager, sealed-secrets, velero,
cloudnative-pg: installed, since the platform needs them, and flagged the same way) and the rest
(application stacks whose images ship their own crypto: refused unless --force, and listed by
`cs scan fips`).
verify cs scan fips (and `cs scan stig` for the DISA STIG, which includes FIPS checks). On AWS, `cs scan cloud`
audits only the environment's region, through the FIPS endpoints (the report's summary names them).
UBUNTU_PRO_TOKEN (VMware, AWS with a VPN host, a GCP bastion on a plain Ubuntu image): export it, or store it with cs creds set UBUNTU_PRO_TOKEN, before setup applies - a setup that would apply stops without it, nothing created; --dry-run and --plan-only only warn. FIPS mode is chosen at creation time (the SSH key type depends on it); it cannot be toggled on an existing environment.
Troubleshooting¶
cloudseed help troubleshooting
"terraform is not installed" cloudseed deps install terraform (or --runtime container)
No credentials detected run the login command doctor prints; or export the provider env vars
"already exists" errors cloudseed adopts the resource when its tags say it is this environment's (asks when
the owner is unknown; CLOUDSEED_ADOPT=1 without a terminal) - cs explain reconcile
GuardDuty / Security Hub already on never adopted. Only on by default here: left alone, enable_guardduty=false /
enable_access_analyzer=false saved for you. Set true explicitly: setup stops;
--var enable_guardduty=false / --var enable_security_hub=false; an account
analyzer already in the region: --var enable_access_analyzer=false
Second env in the same AWS account --var enable_account_baseline=false (same region); an env alone in another
region also takes --var enable_regional_baseline=true
SSH times out cloudseed update-ip <cloud> --env <env> (your IP changed)
Azure activity log permission error --var enable_activity_log=false (needs Contributor at subscription scope)
Azure 403 on role assignments (AKS) AKS / velero create role assignments (velero also a custom role): Owner, or
Contributor + User Access Administrator
Provider checksum errors after switching host <-> container: cloudseed resets the cache itself; re-run.
Any other checksum / lock error: delete that root's .terraform.lock.hcl and
.terraform, then re-run (with a shared TF_PLUGIN_CACHE_DIR, let parallel runs
finish first)
Plan shown, nothing applied (exit 3) add --auto-approve (a plan with no changes exits 0)
"<cloud>-<env> is busy" another cloudseed run (a terminal, the console, an MCP client or an agent) is
changing that environment; wait for it to finish (or stop it), then re-run
Agent auth failed set ANTHROPIC_API_KEY, `ant auth login`, or `cloudseed use claude` (Claude Code login)
"unknown command" for a sentence natural language goes through: cloudseed agentic "<sentence>"
Something failed and it's unclear why cloudseed troubleshoot <cloud> --env <env> --log
"Unexpected error" the redacted traceback is in the environment's log, or without an environment in
~/.cloudseed/logs/<ts>-<cmd>-crash.log (0600); CLOUDSEED_DEBUG=1 prints it too
A missing tool stops a -y run (exit 2) install it first (cloudseed install <tool>) or set CLOUDSEED_AUTO_INSTALL=1
A script or CI job must never prompt -y on every command, or export CLOUDSEED_NONINTERACTIVE=1 (same as -y)
Where is everything? cloudseed list · ~/.cloudseed (CLOUDSEED_HOME)
Examples¶
cloudseed help examples
# Interactive first environment
cloudseed setup aws
# Fully scripted prod environment with per-AZ NAT and 3 AZs
cloudseed setup aws -y --env prod --name acme --region eu-west-1 \
--allow-ip 203.0.113.7 --var az_count=3 --var single_nat_gateway=false --auto-approve
# GCP with OS Login and a bigger bastion
cloudseed setup gcp --env dev --project-id my-proj --var enable_os_login=true --var bastion_machine_type=e2-small
# Azure, local state, Defender on
cloudseed setup azure --env dev --subscription-id <id> --state local --var enable_defender=true
# Day-2
cloudseed update-ip aws --env prod
cloudseed ssh aws --env prod -- -L 8080:10.0.16.5:80
cloudseed output aws --env prod --json
# Teardown
cloudseed destroy aws --env prod --target module.stack.module.bastion # just the bastion
cloudseed destroy aws --env prod --purge-state --purge # everything, clean slate
# Agentic
cloudseed enable agentic
cloudseed agentic "set up a dev env on gcp in project my-proj, then show me the ssh command"
cs agentic "list my environments"