sandwich/Ansible-Bootstrap
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docu(readme): consolidate final documentation state

Browse Source
This commit is contained in:
Sandwich
2026-02-11 05:37:18 +01:00
parent 9f6fff313b
commit 920e7d3f21
1 changed files with 351 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

553
README.md
View File

@@ -1,223 +1,372 @@
# Ansible-Bootstrap
# Ansible Bootstrap Playbook
An Ansible playbook for automating system bootstrap processes in an Infrastructure-as-Code manner.
Automate Linux system bootstrap across multiple distributions and hypervisors in an Infrastructure-as-Code workflow.
# Info
## Supported Distributions
Most of the roles are adaptable for use with systems beyond ArchLinux, requiring only that the target system can install a necessary package manager, such as `dnf` for RHEL-based systems. Additionally, a replacement for the `arch-chroot` command may be required for these systems.
| Distribution | Versions |
|---|---|
| AlmaLinux | 8.x, 9.x, 10.x |
| Alpine Linux | latest |
| Arch Linux | latest |
| Debian | 10, 11, 12, 13, unstable |
| Fedora | 40, 41, 42, 43 |
| openSUSE Tumbleweed | latest |
| RHEL | 8.x, 9.x, 10.x |
| Rocky Linux | 8.x, 9.x, 10.x |
| Ubuntu | latest |
| Ubuntu LTS | latest |
| Void Linux | latest |
**NOTE**:
## Supported Hypervisors
- For RHEL 8, RHEL 9, and RHEL 10, repository access requires the `rhel_iso` variable. This variable specifies a local ISO or proxy repository.
- RHEL systems do not support `btrfs`. Use `ext4` or `xfs` as alternatives.
- For RHEL 8, `xfs` may cause installation issues; `ext4` is recommended.
- `custom_iso: true` skips ArchISO validation and pacman setup, your installer ISO must provide the tools required by the selected roles.
| Hypervisor | Value |
|---|---|
| libvirt | `libvirt` |
| Proxmox | `proxmox` |
| VMware | `vmware` |
| Xen | `xen` |
| Bare metal | `none` |
# Supported Distributions
## Compatibility Notes
This playbook supports multiple Linux distributions with specific versions tailored to each.
Below is a list of supported distributions:
- `rhel_iso` is required for `system.os: rhel`.
- RHEL installs should use `system.filesystem: ext4` or `system.filesystem: xfs` (not `btrfs`).
- For RHEL 8 specifically, prefer `ext4` over `xfs` if you hit installer/filesystem edge cases.
- `custom_iso: true` skips ArchISO validation and pacman preparation; your installer image must already provide required tooling.
- On non-Arch installers, set `system.features.chroot.tool` (`arch-chroot`, `chroot`, or `systemd-nspawn`) explicitly as needed.
| `os` | Distribution |
| ---------- | ---------------------------------- |
| archlinux | ArchLinux (Latest rolling release) |
| almalinux | AlmaLinux 9.x |
| debian11 | Debian 11 (Bullseye) |
| debian12 | Debian 12 (Bookworm) |
| debian13 | Debian 13 (Trixie) |
| fedora | Fedora 43 |
| rhel8 | Red Hat Enterprise Linux 8 |
| rhel9 | Red Hat Enterprise Linux 9 |
| rhel10 | Red Hat Enterprise Linux 10 |
| rocky | Rocky Linux 9.x |
| ubuntu | Ubuntu 25.04 (Plucky Puffin) |
| ubuntu-lts | Ubuntu 24.04 LTS (Noble Numbat) |
## Configuration Model
# Documentation
The project uses only dict-based variables:
## Table of Contents
- `system` for host/runtime/install configuration
- `hypervisor` for virtualization backend configuration
1. [Overview](#1-overview)
2. [Global Variables](#2-global-variables)
3. [Inventory Variables](#3-inventory-variables)
4. [How to Use the Playbook](#4-how-to-use-the-playbook)
- 4.1 [Prerequisites](#41-prerequisites)
- 4.2 [Running the Playbook](#42-running-the-playbook)
- 4.3 [Example Usage](#43-example-usage)
These dictionaries are normal Ansible variables and belong in host/group vars.
You can define them in inventory host entries, `group_vars/*`, or `host_vars/*`.
Dictionary variables are merged across scopes (`group_vars` -> `host_vars`) by project config.
Set shared values like `system.filesystem` once in group vars, then override only host-specific keys per host.
## 1. Overview
### Variable Placement
The playbook uses the ArchLinux ISO as a foundational tool to provides an efficient and systematic method for the automatic deployment of a variety of Linux distributions on designated target systems. It ensures a standardized setup across different platforms, equipping each system with the essential configurations and software necessary for its designated role.
| Location | Scope | Typical use |
|---|---|---|
| `group_vars/all.yml` | All hosts | Shared defaults like `hypervisor`, `system.filesystem`, `boot_iso` |
| `group_vars/<group>.yml` | Group | Environment or role-specific defaults |
| `host_vars/<host>.yml` | Single host | Host-specific overrides |
| Inventory host vars | Single host | Inline definitions for quick setup |
## 2. Global Variables
### Example Host Definition
Global variables apply across your Ansible project and can be supplied via inventory or `-e @vars_example.yml`. These variables define common settings such as hypervisor connection details and the boot ISO path. They can be overridden by inventory variables for specific hosts or VMs if needed.
```yaml
all:
vars:
system:
filesystem: btrfs
boot_iso: "local:iso/archlinux-x86_64.iso"
hypervisor:
type: proxmox
url: pve01.example.com
username: root@pam
password: CHANGE_ME
host: pve01
storage: local-lvm
### 2.1 Core Provisioning
| Variable | Description | Example Value |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------- |
| `install_type` | Type of installation. | `virtual`, `physical` |
| `hypervisor` | Type of hypervisor (required for virtual installs). | `libvirt`, `proxmox`, `vmware`, `none` |
| `install_drive` | Drive where the system will be installed. | `/dev/sda` |
| `boot_iso` | Path to the boot ISO image. | `local-btrfs:iso/archlinux-x86_64.iso` |
| `rhel_iso` | Path to the RHEL ISO file, required for RHEL 8/9/10. | `local-btrfs:iso/rhel-9.4-x86_64-dvd.iso` |
| `custom_iso` (optional) | Skip ArchISO checks and pacman setup on installer media. | `true`, `false (default)` |
| `cis` (optional) | Adjusts the installation to be CIS level 3 conformant. | `true`, `false (default)` |
| `selinux` (optional) | Toggle SELinux where supported. | `true (default)`, `false` |
| `firewalld_enabled` (optional) | Toggle firewalld package/service enablement. | `true (default)`, `false` |
| `ssh_enabled` (optional) | Toggle SSH server package/service enablement. | `true (default)`, `false` |
### 2.2 Hypervisor Access (virtual installs)
| Variable | Description | Example Value |
| ----------------------- | ---------------------------------------------------------- | -------------------- |
| `hypervisor_url` | URL/IP address for the hypervisor interface. | `192.168.0.2` |
| `hypervisor_username` | Username for hypervisor authentication. | `root@pam` |
| `hypervisor_password` | Password for hypervisor authentication. | `123456` |
| `hypervisor_datacenter` | Name of the hypervisor datacenter. | `default-datacenter` |
| `hypervisor_cluster` | Name of the hypervisor cluster. | `default-cluster` |
| `hypervisor_node` | Hypervisor node name. | `node01` |
| `hypervisor_storage` | Storage identifier for VM disks. | `local-btrfs` |
| `vm_path` (optional) | Libvirt image dir or VMware folder path. | `/var/lib/libvirt/images` |
| `vmware_ssh` | If Ansible should use SSH after base VMware setup. | `true`, `false (default)` |
| `vlan_name` (optional) | VLAN for the VM's network interface. | `vlan100` |
| `note` (optional) | VMware VM annotation. | `Provisioned by Ansible` |
### 2.3 VMware Tools connection (VMware installs)
These are required when `hypervisor: vmware` uses the `vmware_tools` connection.
| Variable | Description | Example Value |
| ------------------------------- | ------------------------------------------ | -------------------------------------- |
| `ansible_vmware_tools_user` | Guest OS user for guest operations. | `root` |
| `ansible_vmware_tools_password` | Guest OS password for guest operations. | `""` |
| `ansible_vmware_guest_path` | VM inventory path (datacenter + folder). | `/dc01/vm/Folder/vm01.example.com` |
| `ansible_vmware_host` | vCenter/ESXi hostname. | `vcenter01.example.com` |
| `ansible_vmware_user` | vCenter/ESXi username. | `administrator@vsphere.local` |
| `ansible_vmware_password` | vCenter/ESXi password. | `********` |
| `ansible_vmware_validate_certs` | Validate vCenter/ESXi TLS certs. | `false` |
### 2.4 Disk Encryption (optional)
| Variable | Description | Example Value |
| -------------------------- | ----------------------------------------------- | ------------------ |
| `luks_enabled` | Enable LUKS encryption for the root volume. | `true`, `false` |
| `luks_passphrase` | Passphrase used for initial LUKS format/unlock. | `1234` |
| `luks_mapper_name` | Decrypted mapper name. | `SYSTEM_DECRYPTED` |
| `luks_auto_decrypt` | Enable automatic unlock on boot. | `true`, `false` |
| `luks_auto_decrypt_method` | Auto-unlock method. | `tpm2`, `keyfile`, `manual` |
| `luks_tpm2_device` | TPM2 device for enrollment. | `auto` |
| `luks_tpm2_pcrs` | TPM2 PCR list (systemd-cryptenroll). | `7` |
| `luks_keyfile_size` | Keyfile size in bytes for initramfs. | `64` |
| `luks_options` | LUKS options passed to crypttab/kernel. | `discard,tries=3` |
| `luks_type` | LUKS format type. | `luks2` |
| `luks_cipher` | LUKS cipher. | `aes-xts-plain64` |
| `luks_hash` | LUKS hash. | `sha512` |
| `luks_iter_time` | LUKS iter time in milliseconds. | `4000` |
| `luks_key_size` | LUKS key size in bits. | `512` |
| `luks_pbkdf` | LUKS PBKDF algorithm. | `argon2id` |
| `luks_use_urandom` | Reserved; module uses cryptsetup defaults. | `true` |
| `luks_verify_passphrase` | Reserved; module uses cryptsetup defaults. | `true` |
### 2.5 Partitioning Overrides (advanced)
Use these only when you need to override the default layout logic.
| Variable | Description | Example Value |
| ---------------------------- | -------------------------------------------------------- | ------------- |
| `partitioning_efi_size_mib` | ESP size in MiB. | `512` |
| `partitioning_boot_size_mib` | `/boot` size in MiB when a separate boot is used. | `1024` |
| `partitioning_separate_boot` | Force a separate `/boot` partition. | `true` |
| `partitioning_boot_fs_fstype` | Filesystem for `/boot` when separate. | `ext4` |
| `partitioning_use_full_disk` | Use remaining LVM space for the root volume. | `true` |
To protect sensitive information, such as passwords, API keys, and other confidential variables (e.g., `hypervisor_password`), **it is recommended to use Ansible Vault**.
## 3. Inventory Variables
Inventory variables are defined for individual hosts or VMs in the inventory file, allowing customization of settings such as the operating system, filesystem, and compliance with CIS benchmarks. These variables can be set globally and overridden for specific hosts or VMs.
### 3.1 System Identity and OS
| Variable | Description | Example Value |
| ------------ | -------------------------------------- | ---------------------- |
| `ansible_host` | Ansible connection address for the host. | `192.168.0.10` |
| `os` | Operating system to be installed. | `ubuntu-lts` |
| `filesystem` | Filesystem type for the root volume. | `btrfs`, `ext4`, `xfs` |
| `hostname` | The hostname assigned to the system. | `vm01` |
### 3.2 Credentials and Access
These are prompted by default via `vars_prompt` in `main.yml`, but can be supplied via inventory/vars/`-e` for non-interactive runs.
| Variable | Description | Example Value |
| ----------------- | ---------------------------------- | ----------------- |
| `root_password` | Root password (vault recommended). | `SecurePass123` |
| `user_name` | Username for a user account. | `adminuser` |
| `user_password` | Password for the user account. | `UserPass123` |
| `user_public_key` | SSH Key for the user account. | `ssh-ed25519 AAAA` |
### 3.3 Networking
| Variable | Description | Example Value |
| --------------- | -------------------------------------------------------------- | ----------------- |
| `vm_ip` | IP address assigned to the system (omit to use DHCP). | `192.168.0.10` |
| `vm_nms` | Netmask bits for static addressing. | `24` |
| `vm_gw` | Default gateway IP address (static only). | `192.168.0.1` |
| `vm_dns` | DNS server IP address(es). | `1.0.0.1,1.1.1.1` |
| `vm_dns_search` | DNS search zone(s) for the network configuration. | `example.com` |
| `vm_nif` | Network interface/bridge for the VM's network connection. | `vmbr0` |
### 3.4 VM Sizing (virtual installs)
| Variable | Description | Example Value |
| ----------- | --------------------------------- | ------------- |
| `vm_id` | Unique identifier for the VM. | `101` |
| `vm_size` | Disk size allocated in GB (min 20). | `20` |
| `vm_memory` | Amount of memory in MB. | `2048` |
| `vm_cpus` | Number of CPU cores (virtual installs). | `4` |
| `vm_ballo` | Ballooning memory size (optional).| `2048` |
### 3.5 Post-install Packages
| Variable | Description | Example Value |
| ------------------------ | --------------------------------------------------------------------- | ------------------ |
| `extra_packages` (optional) | Additional packages installed after the first boot into the installed OS. | `["git", "jq"]` |
## 4. How to Use the Playbook
### 4.1 Prerequisites
Before running the playbook, ensure you have Ansible installed and configured correctly, and your inventory file is set up with the target systems defined.
### 4.2 Running the Playbook
Execute the playbook using the `ansible-playbook` command, ensuring that all necessary variables are defined, typically by specifying a vars file (such as `vars_example.yml`) containing the required configurations.
### 4.3 Example Usage
An effective way to use the playbook involves defining all necessary configurations within a vars file (for example, `vars_example.yml`). This file should include all relevant global variables tailored to your specific deployment requirements. Additionally, you should prepare an inventory file (`inventory.yml`) that lists all the hosts along with any specific inventory variables they might need. Then, you can run the playbook as follows:
```bash
ansible-playbook -i inventory.yml -e @vars_example.yml main.yml
children:
bootstrap:
hosts:
app01.example.com:
ansible_host: 10.0.0.10
system:
type: virtual
os: debian
version: "12"
name: app01.example.com
id: 101
cpus: 2
memory: 4096
balloon: 0
network: vmbr0
ip: 10.0.0.10
prefix: 24
gateway: 10.0.0.1
dns:
servers: [1.1.1.1, 1.0.0.1]
search: [example.com]
disks:
- size: 40
- size: 120
mount:
path: /data
fstype: xfs
user:
name: ops
password: CHANGE_ME
key: "ssh-ed25519 AAAA..."
root:
password: CHANGE_ME
luks:
enabled: true
passphrase: CHANGE_ME
auto: true
method: tpm2
tpm2:
pcrs: "7"
features:
firewall:
enabled: true
backend: firewalld
toolkit: nftables
```
This command prompts Ansible to execute the `main.yml` playbook, applying configurations defined in both the vars file and the inventory file.
## Core Variables
Use `inventory_example.yml`, `inventory_libvirt_example.yml`, `vars_example.yml`, and the bare-metal examples as starting points for new inventories.
| Variable | Type | Description |
|---|---|---|
| `boot_iso` | string | Required when `system.type=virtual` |
| `rhel_iso` | string | Required when `system.os=rhel` |
| `custom_iso` | bool | Skip Arch ISO-specific preparation checks |
## Notes
## `system` Dictionary
- `vm_size`/`vm_memory`/`vm_cpus` are required for virtual installs only, physical installs use the full disk.
- `vm_dns` and `vm_dns_search` accept comma-separated strings or YAML lists.
- `hypervisor` determines which backend-specific roles run.
- Guest tools are installed based on `hypervisor`: `qemu-guest-agent` for `libvirt`/`proxmox`, `open-vm-tools` for `vmware`, otherwise none.
- Molecule is scaffolded with a delegated driver and a no-op converge for lint-only validation.
- With LUKS enabled on Debian/Ubuntu and RHEL-based systems, provisioning uses an ESP (512 MiB), a separate `/boot`
(1 GiB, same as `filesystem` unless `btrfs` uses ext4 on Debian/Ubuntu or xfs on RHEL-based), and the encrypted root;
adjust sizes via
`partitioning_efi_size_mib` and `partitioning_boot_size_mib` if needed.
- With `luks_auto_decrypt_method: tpm2` on virtual installs, the virtualization role enables a TPM2 device (libvirt/proxmox/vmware).
- For VMware, `vmware_ssh: true` enables SSH on the guest and switches the connection to SSH for the remaining tasks.
- For physical installs, set `ansible_user`/`ansible_password` for the installer environment when it differs from the prompted user credentials.
Top-level host install/runtime settings.
Use these keys under `system`.
| Key | Type | Default | Description |
|---|---|---|---|
| `type` | string | `virtual` | `virtual` or `physical` |
| `os` | string | empty (`archlinux` if omitted on physical) | Target distribution |
| `version` | string | empty | Version selector for distro families |
| `filesystem` | string | empty | `btrfs`, `ext4`, or `xfs` |
| `name` | string | inventory hostname | Final hostname |
| `id` | int/string | empty | VMID for Proxmox |
| `cpus` | int | `0` | vCPU count |
| `memory` | int | `0` | Memory in MiB |
| `balloon` | int | `0` | Balloon memory in MiB |
| `network` | string | empty | Hypervisor network/bridge |
| `vlan` | string/int | empty | VLAN tag |
| `ip` | string | empty | Static IP (optional) |
| `prefix` | int | empty | Prefix for static IP |
| `gateway` | string | empty | Static gateway |
| `path` | string | empty | Hypervisor folder/path (libvirt/vmware) |
| `packages` | list/string | empty | Post-reboot packages |
| `dns` | dict | `{servers: [], search: []}` | DNS nested dictionary |
| `disks` | list | `[]` | Disk layout list |
| `user` | dict | `{name:'', password:'', key:''}` | User account dictionary |
| `root` | dict | `{password:''}` | Root account dictionary |
| `luks` | dict | see below | Encryption dictionary |
| `features` | dict | see below | Feature flags dictionary |
### `system.dns`
DNS options used by network configuration tasks.
Use these keys under `system.dns`.
| Key | Type | Default | Description |
|---|---|---|---|
| `servers` | list/string | `[]` | DNS resolvers; comma-separated string is normalized |
| `search` | list/string | `[]` | Search domains; comma-separated string is normalized |
### `system.user`
Target user account settings.
Use these keys under `system.user`.
| Key | Type | Default | Description |
|---|---|---|---|
| `name` | string | empty | Username created on target |
| `password` | string | empty | User password (also used for sudo/become) |
| `key` | string | empty | SSH public key for `authorized_keys` |
### `system.root`
Use these keys under `system.root`.
| Key | Type | Default | Description |
|---|---|---|---|
| `password` | string | empty | Root password |
### `system.luks`
LUKS container, unlock, and initramfs-related settings.
Use these keys under `system.luks`.
| Key | Type | Default | Allowed | Description |
|---|---|---|---|---|
| `enabled` | bool | `false` | `true`/`false` | Enable encrypted root workflow |
| `passphrase` | string | empty | any string | Passphrase used for format/open/enroll |
| `mapper` | string | `SYSTEM_DECRYPTED` | mapper name | Mapper name under `/dev/mapper` |
| `auto` | bool | `true` | `true`/`false` | Auto-unlock behavior toggle |
| `method` | string | `tpm2` | `tpm2`,`keyfile` | Auto-unlock backend when `auto=true` |
| `keysize` | int | `64` | positive int | Keyfile size (bytes) for keyfile mode |
| `options` | string | `discard,tries=3` | crypttab opts | Additional crypttab/kernel options |
| `type` | string | `luks2` | cryptsetup type | LUKS format type |
| `cipher` | string | `aes-xts-plain64` | cipher name | Cryptsetup cipher |
| `hash` | string | `sha512` | hash name | Cryptsetup hash |
| `iter` | int | `4000` | positive int | PBKDF iteration time (ms) |
| `bits` | int | `512` | positive int | Key size (bits) |
| `pbkdf` | string | `argon2id` | pbkdf name | PBKDF algorithm |
| `urandom` | bool | `true` | `true`/`false` | Use urandom during key generation |
| `verify` | bool | `true` | `true`/`false` | Verify passphrase during format |
### `system.luks.tpm2`
TPM2-specific policy settings used when `system.luks.method=tpm2`.
Use these keys under `system.luks.tpm2`.
| Key | Type | Default | Allowed | Description |
|---|---|---|---|---|
| `device` | string | `auto` | `auto` or device path | TPM2 device selector |
| `pcrs` | string/list | empty | PCR expression | PCR binding policy (for example `"7"` or `"0+7"`) |
### `system.features`
Feature toggles for optional system configuration.
Use these keys under `system.features`.
| Key | Type | Default | Allowed | Description |
|---|---|---|---|---|
| `cis.enabled` | bool | `false` | `true`/`false` | Enable CIS hardening role |
| `selinux.enabled` | bool | `true` | `true`/`false` | SELinux management |
| `firewall.enabled` | bool | `true` | `true`/`false` | Enable firewall role actions |
| `firewall.backend` | string | `firewalld` | `firewalld`,`ufw` | Firewall service backend |
| `firewall.toolkit` | string | `nftables` | `nftables`,`iptables` | Packet filtering toolkit selection |
| `ssh.enabled` | bool | `true` | `true`/`false` | SSH service/package management |
| `zstd.enabled` | bool | `true` | `true`/`false` | zstd related tuning |
| `swap.enabled` | bool | `true` | `true`/`false` | Swap setup toggle |
| `banner.motd` | bool | `true` | `true`/`false` | MOTD banner management |
| `banner.sudo` | bool | `true` | `true`/`false` | Sudo banner management |
| `chroot.tool` | string | `arch-chroot` | `arch-chroot`,`chroot`,`systemd-nspawn` | Chroot wrapper command |
## Multi-Disk Schema
`system.disks[0]` is always the OS disk. Additional entries can define data disks.
| Key | Type | Description |
|---|---|---|
| `size` | number | Disk size in GB (required for virtual) |
| `device` | string | Explicit disk device (required for physical data disks) |
| `mount.path` | string | Mount target (for additional disks) |
| `mount.fstype` | string | `btrfs`, `ext4`, or `xfs` |
| `mount.label` | string | Optional filesystem label |
| `mount.opts` | string | Mount options (`defaults` by default) |
Example:
```yaml
system:
disks:
- size: 80
- size: 200
mount:
path: /data
fstype: xfs
label: DATA
opts: defaults,noatime
- size: 300
mount:
path: /backup
fstype: ext4
```
For physical installs, include device paths:
```yaml
system:
type: physical
disks:
- device: /dev/sda
size: 120
- device: /dev/sdb
size: 500
mount:
path: /data
fstype: ext4
```
## Advanced Partitioning Overrides
Use these only when you need to override default layout behavior.
| Variable | Description | Default |
|---|---|---|
| `partitioning_efi_size_mib` | EFI system partition size in MiB | `512` |
| `partitioning_boot_size_mib` | Separate `/boot` size in MiB (when used) | `1024` |
| `partitioning_separate_boot` | Force separate `/boot` partition logic | auto-derived |
| `partitioning_boot_fs_fstype` | Filesystem for `/boot` when separate | auto-derived |
| `partitioning_use_full_disk` | Consume remaining VG space for root LV | `true` |
## `hypervisor` Dictionary
Use these keys under `hypervisor`.
| Key | Type | Description |
|---|---|---|
| `type` | string | `libvirt`, `proxmox`, `vmware`, `xen`, `none` |
| `url` | string | Proxmox/VMware API host |
| `username` | string | API username |
| `password` | string | API password |
| `host` | string | Proxmox node name |
| `storage` | string | Proxmox/VMware storage |
| `datacenter` | string | VMware datacenter |
| `cluster` | string | VMware cluster |
| `certs` | bool | TLS cert validation for VMware |
| `ssh` | bool | VMware installer SSH bootstrap helper |
## VMware Guest Operations Variables
When `hypervisor.type: vmware` and connection uses `vmware_tools`, ensure these variables are set in inventory/group/host vars as needed by your vCenter/ESXi environment.
| Variable | Description |
|---|---|
| `ansible_vmware_tools_user` | Guest OS username for guest operations |
| `ansible_vmware_tools_password` | Guest OS password for guest operations |
| `ansible_vmware_guest_path` | VM inventory path (`/datacenter/vm/folder/name`) |
| `ansible_vmware_host` | vCenter/ESXi host |
| `ansible_vmware_user` | vCenter/ESXi API username |
| `ansible_vmware_password` | vCenter/ESXi API password |
| `ansible_vmware_validate_certs` | Enable/disable TLS certificate validation |
## Prerequisites
- Ansible installed on the control machine.
- Inventory and variables prepared for your target hosts.
- Disposable/non-production targets (the playbook enforces production-safety checks).
## Usage
```bash
ansible-playbook -i inventory_example.yml main.yml
ansible-playbook -i inventory_libvirt_example.yml main.yml
ansible-playbook -i inventory.yml main.yml -e @vars_example.yml
```
## Security
Store sensitive data (passwords, API tokens, private keys) with Ansible Vault instead of plaintext inventory files.
## Operational Notes
- For virtual installs, `system.cpus`, `system.memory`, and `system.disks[0].size` are required and validated.
- For physical installs, sizing is derived from the detected install drive; set installer access (`ansible_user`/`ansible_password`) when needed.
- `system.dns.servers` and `system.dns.search` accept either YAML lists or comma-separated strings.
- `hypervisor.type` selects backend-specific provisioning/cleanup behavior.
- Guest tools are selected automatically by hypervisor: `qemu-guest-agent` (`libvirt`/`proxmox`) and `open-vm-tools` (`vmware`).
- With `system.luks.method: tpm2` on virtual installs, the virtualization role enables a TPM2 device where supported.
- With LUKS on non-Arch targets, provisioning may use a separate `/boot`; tune with `partitioning_efi_size_mib` and `partitioning_boot_size_mib`.
- For VMware, `hypervisor.ssh: true` enables SSH on the guest and switches the connection to SSH for remaining tasks.
- Molecule scenario is lint-focused (`delegated` driver with non-destructive placeholder converge).
## Safety
This playbook intentionally aborts if it detects a non-live/production target.
It also refuses to touch pre-existing VMs and only cleans up VMs created in the current run.
## Validation
Always run lint after changes:
```bash
ansible-lint
```