VMware (local) target reference¶
What cloudseed setup vmware builds, every variable you can set with --var, and every output. In the terminal: cloudseed help vmware-skill or cloudseed explain target vmware.
Generated from the code
This page is generated by scripts/gen-docs.py from terraform/vmware/variables.tf, terraform/vmware/outputs.tf, the setup questions and skills/cloudseed-vmware/SKILL.md, so it always matches the CLI you install (this build: cloudseed 0.2.3).
What it builds¶
cloudseed setup vmware --env <env> builds on the local machine:
- Host detection: Fusion Pro on macOS, Workstation Pro on Linux. Windows detection is experimental; native environment changes are refused because supported locking and a native Ansible control node are unavailable. Host arch decides guest arch (Apple Silicon -> arm64 guests only, Intel/AMD -> amd64). Fusion Pro 13 / Workstation Pro 17 or newer: older releases are refused for new environments. A
VMWARE_HOMEthat does not hold vmrun is reported by name.cloudseed doctor vmwareshows what was found. - Private network: by default VMware's built-in host-only vmnet (vmnet1 on Fusion) is adopted as it is: its existing subnet (e.g.
192.168.x.0/24) and DHCP setting are kept - VMware serves DHCP on the upper half (e.g..128-.254) - and the VMs use fixed addresses below the DHCP pool. Every environment without--cidrgets that same vmnet, so only one of them can have VMs: setup refuses a second one while another has VMs. To run two, give the new one its own network:--cidr <cidr>asks for a dedicated vmnet, created through vmrest with DHCP off; VMware only lets root create networks, so that needssudo vmrestwithVMREST_USER/VMREST_PASSWORDexported for it. An explicit--cidrmust be a private (RFC 1918) range: a public one would hide the real hosts of that range from the host, and one containing 1.1.1.1 or 8.8.8.8 would also cut the VMs off from their DNS servers. When vmrest lists no host-only network, the placeholder - the first free10.N.0.0/24from10.100.0.0/24on, normally10.100.0.0/24itself - becomes this environment's own vmnet. Pass the network with--cidr, never--var private_cidr. - Address plan (fixed offsets in the private network): bastion
.2; workloads.10+(at most 10 when Kubernetes is on, they end at.19); 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 (platform catalog), so a LoadBalancer address never lands on a worker added later. Setup refuses counts that do not fit; an existing cluster that already has more workers is only warned (remove the ones abovewk60, highest first, before using LoadBalancer services), andcloudseed node addrefuses a node whose address would fall in the pool. - Pod / Service ranges: with Kubernetes on, the private network must not overlap the cluster's pod or Service range (RKE2
10.42.0.0/16+10.43.0.0/16, kubeadm10.244.0.0/16+10.96.0.0/16). Setup refuses such a network for a new environment or when Kubernetes is turned on (pick another--cidr, or the other distro when it fits), and only warns for a cluster that already runs there. - Bastion VM: NAT NIC (DHCP, reachable from the host) + private NIC (
.2), forwards and NATs the private network; hardened by Ansible like cloud bastions (nat_source_cidrskeeps the NAT rules). - Workload VMs (
workload_count): private NIC only, static IPs.10+, default route via the bastion. They are bootstrapped by cloud-init only, not Ansible-hardened; VMs created by this version turn on unattended security updates themselves. Kubernetes nodes are hardened by the Kubernetes play and deliberately not auto-updated. - Images:
guest_os= ubuntu-24.04 (default) | ubuntu-22.04 | debian-12; downloaded + checksum-verified into~/.cloudseed/images, converted with qemu-img when only qcow2 is published (arm64 Ubuntu, Debian). Debian 12 uses Debian'sgenericimage: thegenericcloudkernel has no AHCI driver for the cloud-init seed ISO. - Terraform: cloudseed's own provider
registry.local/cloudseed/vmdesktop(built fromproviders/vmdesktopwith Go on first use). State is local, in the environment's working directory. Remote state, VPN andupdate-ipdo not apply (the host reaches the VMs directly). - Kubernetes (
enable_kubernetes=true): control-plane (.20+) and worker (.40+) VMs on the private network, RKE2 (default) or kubeadm installed by Ansible from the host. RKE2's CIS hardening profile is not enabled unless--var kubernetes_cis_profile=true(RKE2 only, refused with kubeadm; it enforces the restricted Pod Security Standard outside the exempt namespaces - RKE2's system ones pluscloudseed-scan,velero,local-path-storage,minioandchaos-mesh-: pods that need root or host access are rejected unless their namespace is labelledpod-security.kubernetes.io/enforce=privilegedorbaseline).cloudseed platform installsets those labels itself before installing catalog items whose pods need more than restricted (privileged: velero, local-path-provisioner, metallb, kube-prometheus-stack, falco, neuvector, kured, chaos-mesh, istio ambient, kubescape-operator, trivy-operator; baseline: minio, loki, alloy and similar);cloudseed platform info <item>shows the level. The first control plane installs RKE2's stable channel (kubeadm: Kubernetes 1.35); nodes added later join at the version the cluster runs, and adding a control plane leaves the workers alone.--var kubernetes_versionpins the release instead (RKE2v1.36.4+rke2r1: every new node installs it, so changing it later puts new nodes on another version than the cluster; kubeadm1.35: only a new cluster uses it) and never upgrades a node that is already installed - it is not an upgrade path.kubernetes_workers=0puts the workloads on the control planes. Kubeconfig at<workdir>/k8s/kubeconfig;cloudseed k8s kubeconfig vmware --env <env>merges it into ~/.kube/config and makes it the current kubectl context (tell the user;cloudseed undoswitches back);cloudseed provision vmware --env <env> --host k8sre-runs it. - FIPS (
fips_mode=true, new environments only): every VM attaches Ubuntu Pro (export UBUNTU_PRO_TOKEN, free for personal use) and enables fips-updates,guest_osmust be Ubuntu, SSH keys are RSA-4096, and Kubernetes must be RKE2.
Stack variables¶
Override any of these with --var name=value on cloudseed setup vmware (JSON for lists and maps; --var name=null drops a saved override). Values are read by the variable's declared type.
| Variable | Default | Description |
|---|---|---|
vm_dir | <workdir>/vms | Directory holding the VMs. |
ssh_username | your local username (--ssh-username) | Login user cloud-init creates at first boot on every VM. Changing it on a deployed environment rebuilds every VM (their disks are wiped). |
bastion_cpus | 2 | Bastion vCPUs |
bastion_memory_mb | 2048 | Bastion memory (MB) |
bastion_disk_gb | 20 | Bastion disk (GB) |
workload_count | 0 | Private workload VMs behind the bastion (no NAT NIC; egress through the bastion). |
workload_cpus | 2 | Workload vCPUs |
workload_memory_mb | 2048 | Workload memory (MB) |
workload_disk_gb | 20 | Workload disk (GB) |
packages | [] | Extra packages cloud-init installs at first boot on the bastion and the workload VMs (Kubernetes nodes get a fixed package set). First boot only: changing it on a deployed environment rebuilds the bastion and every workload VM (their disks are wiped); to add a package to running VMs, install it over cloudseed ssh. |
enable_kubernetes | false | Create control-plane and worker VMs on the private network and install Kubernetes (RKE2 or kubeadm). |
kubernetes_distro | "rke2" | rke2 (default; batteries included; CIS hardening profile opt-in via kubernetes_cis_profile) or kubeadm (vanilla upstream). |
kubernetes_control_planes | 1 | Control-plane VMs (1-20; an odd number keeps etcd's quorum tolerant of failures). |
kubernetes_workers | 2 | Worker VMs (addresses .40 and up; at most 60 on a /24 or larger network, whose .100-.127 are kept for MetalLB's LoadBalancer pool). 0 is allowed: a cluster created without workers runs its workloads on the control planes. |
kubernetes_cpus | 2 | vCPUs per Kubernetes node |
kubernetes_memory_mb | 4096 | Memory per Kubernetes node (MB) |
kubernetes_disk_gb | 40 | Disk per Kubernetes node (GB) |
fips_mode | false | FIPS 140 mode: Ubuntu Pro FIPS packages on every VM (needs UBUNTU_PRO_TOKEN), RKE2 (FIPS-validated Go crypto) for Kubernetes, FIPS-only SSH algorithms, ECDSA SSH keys. |
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 |
|---|---|---|---|
guest_os | ubuntu-24.04 | – | Guest OS for the VMs (ubuntu-24.04, ubuntu-22.04, debian-12) |
kubernetes_version | - | – | Kubernetes version: an RKE2 release (e.g. v1.36.4+rke2r1) or a kubeadm minor (e.g. 1.35); empty = automatic (RKE2's stable channel / kubeadm's supported default; nodes added later match the cluster) |
kubernetes_cis_profile | false | – | RKE2 CIS hardening profile (enforces the restricted Pod Security Standard outside the system namespaces; cloudseed exempts its own - cloudseed-scan, velero, local-path-storage, minio, chaos-mesh - and cs platform install labels the namespaces of other items that need host access; your own such workloads need a privileged namespace label) |
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) |
private_cidr | --cidr for a dedicated vmnet (default: the subnet of VMware's built-in host-only vmnet) |
base_disk | --var guest_os=... (the downloaded, checksum-verified image of guest_os) |
guest_os_id | --var guest_os=... (derived from guest_os and the host architecture) |
ssh_public_key | the environment's generated key, or --ssh-public-key |
tags | --tag is accepted but not applied (VMware VMs have no tags) |
Outputs¶
Read them with cloudseed output vmware --env <env> (add --json for scripts).
| Output | Description |
|---|---|
host_product | fusion or workstation. |
host_version | VMware Fusion/Workstation version reported by the host. |
guest_arch | Guest architecture this host runs (arm64 / amd64). |
private_vmnet | Host-only vmnet of the private network. |
private_vmnet_adopted | true when the private vmnet existed before (adopted, e.g. vmnet1) and must be kept on destroy; false when this stack created it; null for networks recorded before this was tracked. |
private_cidr | CIDR of the host-only private network. |
bastion_public_ip | Bastion address on the NAT network (reachable from this machine). |
bastion_private_ip | Bastion address on the private network (gateway for workloads). |
workload_private_ips | Private IPs of the workload VMs (reach them through the bastion). |
workload_names | Names of the workload VMs. |
ssh_user | Login user on the bastion. |
kubernetes_distro | rke2 or kubeadm (null when Kubernetes is disabled). |
kubernetes_control_plane_ips | Private IPs of the control-plane VMs. |
kubernetes_worker_ips | Private IPs of the worker VMs. |
kubernetes_endpoint | API server URL (reachable from this machine over the host-only network). |
fips_mode | Whether the environment was built in FIPS 140 mode. |
Gotchas¶
- If VMware is missing,
doctor vmwareprints the download link; nothing can be created without it. - vmrest credentials are generated and configured by cloudseed automatically (no user action); VMREST_USER/VMREST_PASSWORD override them. When vmrest was never configured for this OS user, cloudseed configures it (its own credentials) - or, with the user's own VMREST_USER/VMREST_PASSWORD, says to run
vmrest -Conce. vm_diris per environment by default (<workdir>/vms). Setup warns when the directory is shared with another environment or already holds other VMs, and refuses a new environment whose VM names (<name>-<env>-*) would clash with another's there; point that out to the user. A VM bundle named like one of the environment's VMs but unknown to its state is moved aside to<name>.replaced-<time>.vmwarevm(never deleted) when the VM is created; a running one stops the apply.destroyremoves only this environment's VMs (<name>-<env>-bastion|vmN|cpN|wkN, or VMs Terraform recorded for it) and sweeps their files; other VMs in the samevm_dirare listed and never touched, and avm_dirthe user chose is never deleted. The built-in vmnet1 is always kept (and reused next time); a dedicated--cidrvmnet is removed from VMware's networking file with sudo when possible, otherwise it is kept and reused. With--purge, vmrest is stopped only when this cloudseed home started it, no other VMware environment is left and no VM is running.- Workload VMs have no public address: reach them via
cloudseed ssh vmware --env <env>then ssh to their private IP, or an SSH ProxyJump through the bastion. - Never copy
~/.cloudseed(keys/state) into a VM; only the repository is synced byprovision.