Skip to content

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_HOME that does not hold vmrun is reported by name. cloudseed doctor vmware shows 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 --cidr gets 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 needs sudo vmrest with VMREST_USER/VMREST_PASSWORD exported for it. An explicit --cidr must 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 free 10.N.0.0/24 from 10.100.0.0/24 on, normally 10.100.0.0/24 itself - 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 above wk60, highest first, before using LoadBalancer services), and cloudseed node add refuses 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, kubeadm 10.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_cidrs keeps 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's generic image: the genericcloud kernel has no AHCI driver for the cloud-init seed ISO.
  • Terraform: cloudseed's own provider registry.local/cloudseed/vmdesktop (built from providers/vmdesktop with Go on first use). State is local, in the environment's working directory. Remote state, VPN and update-ip do 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 plus cloudseed-scan, velero, local-path-storage, minio and chaos-mesh -: pods that need root or host access are rejected unless their namespace is labelled pod-security.kubernetes.io/enforce=privileged or baseline). cloudseed platform install sets 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_version pins the release instead (RKE2 v1.36.4+rke2r1: every new node installs it, so changing it later puts new nodes on another version than the cluster; kubeadm 1.35: only a new cluster uses it) and never upgrades a node that is already installed - it is not an upgrade path. kubernetes_workers=0 puts 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 undo switches back); cloudseed provision vmware --env <env> --host k8s re-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_os must 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 vmware prints 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 -C once.
  • vm_dir is 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.
  • destroy removes 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 same vm_dir are listed and never touched, and a vm_dir the user chose is never deleted. The built-in vmnet1 is always kept (and reused next time); a dedicated --cidr vmnet 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 by provision.