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

docu(readme): recompose README from pre/post consolidation versions

Browse Source
This commit is contained in:
Sandwich
2026-02-11 08:25:15 +01:00
parent cd34b41862
commit e5d2720bfe
1 changed files with 236 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

317
README.md
View File

@@ -1,34 +1,58 @@
# Ansible Bootstrap Playbook
# Ansible Bootstrap
Automate Linux system bootstrap across multiple distributions and hypervisors in an Infrastructure-as-Code workflow.
An Ansible playbook for automating Linux system bootstrap in an Infrastructure-as-Code manner. It uses the Arch Linux ISO as a foundational tool to provide an efficient and systematic method for the automatic deployment of a variety of Linux distributions on designated target systems, ensuring a standardized setup across different platforms.
## Supported Distributions
Most roles are adaptable for use with systems beyond Arch Linux, requiring only that the target system can install the necessary package manager (e.g. `dnf` for RHEL-based systems). A replacement for the `arch-chroot` command may also be required; set `system.features.chroot.tool` accordingly.
| 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 |
## Table of Contents
## Supported Hypervisors
1. [Supported Platforms](#1-supported-platforms)
2. [Compatibility Notes](#2-compatibility-notes)
3. [Configuration Model](#3-configuration-model)
4. [Variable Reference](#4-variable-reference)
- 4.1 [Core Variables](#41-core-variables)
- 4.2 [`system` Dictionary](#42-system-dictionary)
- 4.3 [`hypervisor` Dictionary](#43-hypervisor-dictionary)
- 4.4 [VMware Guest Operations](#44-vmware-guest-operations)
- 4.5 [Multi-Disk Schema](#45-multi-disk-schema)
- 4.6 [Advanced Partitioning Overrides](#46-advanced-partitioning-overrides)
5. [How to Use the Playbook](#5-how-to-use-the-playbook)
- 5.1 [Prerequisites](#51-prerequisites)
- 5.2 [Running the Playbook](#52-running-the-playbook)
- 5.3 [Example Usage](#53-example-usage)
6. [Security](#6-security)
7. [Operational Notes](#7-operational-notes)
8. [Safety](#8-safety)
| Hypervisor | Value |
|---|---|
## 1. Supported Platforms
### Distributions
| `system.os` | Distribution | `system.version` |
| ------------ | ------------------------ | ------------------------------- |
| `almalinux` | AlmaLinux | `8`, `9`, `10` |
| `alpine` | Alpine Linux | latest (rolling) |
| `archlinux` | Arch Linux | latest (rolling) |
| `debian` | Debian | `10`, `11`, `12`, `13`, `unstable` |
| `fedora` | Fedora | `40`, `41`, `42`, `43` |
| `opensuse` | openSUSE Tumbleweed | latest (rolling) |
| `rhel` | Red Hat Enterprise Linux | `8`, `9`, `10` |
| `rocky` | Rocky Linux | `8`, `9`, `10` |
| `ubuntu` | Ubuntu | latest |
| `ubuntu-lts` | Ubuntu LTS | latest |
| `void` | Void Linux | latest (rolling) |
### Hypervisors
| Hypervisor | `hypervisor.type` |
| ----------- | ----------------- |
| libvirt | `libvirt` |
| Proxmox | `proxmox` |
| Proxmox VE | `proxmox` |
| VMware | `vmware` |
| Xen | `xen` |
| Bare metal | `none` |
## Compatibility Notes
## 2. Compatibility Notes
- `rhel_iso` is required for `system.os: rhel`.
- RHEL installs should use `system.filesystem: ext4` or `system.filesystem: xfs` (not `btrfs`).
@@ -36,28 +60,25 @@ Automate Linux system bootstrap across multiple distributions and hypervisors in
- `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.
## Configuration Model
## 3. Configuration Model
The project uses only dict-based variables:
The project uses two dict-based variables:
- `system` for host/runtime/install configuration
- `hypervisor` for virtualization backend configuration
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.
These 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 (`hash_behaviour = merge`), so you can set shared values like `system.filesystem` once in group vars and override only host-specific keys per host.
### Variable Placement
| 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 |
| Inventory inline host vars | Single host | Inline definitions for quick setup |
### Example Host Definition
### Example Inventory
```yaml
all:
@@ -120,80 +141,76 @@ all:
toolkit: nftables
```
## Core Variables
## 4. Variable Reference
### 4.1 Core Variables
These top-level variables sit outside the `system`/`hypervisor` dictionaries.
| 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 |
| ------------ | ------ | ------------------------------------------------ |
| `boot_iso` | string | Path to the boot ISO image (required for virtual installs). |
| `rhel_iso` | string | Path to the RHEL ISO (required when `system.os: rhel`). |
| `custom_iso` | bool | Skip ArchISO validation and pacman setup. Default `false`. |
## `system` Dictionary
### 4.2 `system` Dictionary
Top-level host install/runtime settings.
Use these keys under `system`.
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 |
| `os` | string | empty | Target distribution (see [table](#distributions)) |
| `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 |
| `id` | int/string | empty | VMID (required 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 |
| `ip` | string | empty | Static IP (omit for DHCP) |
| `prefix` | int | empty | CIDR prefix for static IP |
| `gateway` | string | empty | Default gateway (static only) |
| `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 |
| `packages` | list | `[]` | Additional packages installed post-reboot |
| `dns` | dict | see below | DNS configuration |
| `disks` | list | `[]` | Disk layout (see [Multi-Disk Schema](#45-multi-disk-schema)) |
| `user` | dict | see below | User account settings |
| `root` | dict | see below | Root account settings |
| `luks` | dict | see below | Encryption settings |
| `features` | dict | see below | Feature toggles |
### `system.dns`
DNS options used by network configuration tasks.
Use these keys under `system.dns`.
#### `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`
#### `system.user`
Target user account settings.
Use these keys under `system.user`.
Credentials are prompted interactively by default via `vars_prompt` in `main.yml`, but can be supplied via inventory, vars files, or `-e` for non-interactive runs.
| Key | Type | Default | Description |
|---|---|---|---|
| ---------- | ------ | ------- | ------------------------------------- |
| `name` | string | empty | Username created on target |
| `password` | string | empty | User password (also used for sudo/become) |
| `password` | string | empty | User password (also used for sudo) |
| `key` | string | empty | SSH public key for `authorized_keys` |
### `system.root`
Use these keys under `system.root`.
#### `system.root`
| Key | Type | Default | Description |
|---|---|---|---|
| ---------- | ------ | ------- | -------------- |
| `password` | string | empty | Root password |
### `system.luks`
#### `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` |
@@ -210,49 +227,76 @@ Use these keys under `system.luks`.
| `urandom` | bool | `true` | `true`/`false` | Use urandom during key generation |
| `verify` | bool | `true` | `true`/`false` | Verify passphrase during format |
### `system.luks.tpm2`
#### `system.luks.tpm2`
TPM2-specific policy settings used when `system.luks.method=tpm2`.
Use these keys under `system.luks.tpm2`.
TPM2-specific policy settings used when `system.luks.method: 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"`) |
| `pcrs` | string/list | empty | PCR expression | PCR binding policy (e.g. `"7"` or `"0+7"`) |
### `system.features`
#### `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 |
| `firewall.toolkit` | string | `nftables` | `nftables`, `iptables` | Packet filtering toolkit |
| `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.motd` | bool | `false` | `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.
### 4.3 `hypervisor` Dictionary
| 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) |
| ------------ | ------ | -------------------------------------------------------- |
| `type` | string | `libvirt`, `proxmox`, `vmware`, `xen`, or `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 identifier |
| `datacenter` | string | VMware datacenter |
| `cluster` | string | VMware cluster |
| `certs` | bool | TLS certificate validation for VMware |
| `ssh` | bool | VMware: enable SSH on guest and switch connection to SSH |
### 4.4 VMware Guest Operations
When `hypervisor.type: vmware` uses the `vmware_tools` connection, these Ansible connection variables are required.
| 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 hostname |
| `ansible_vmware_user` | vCenter/ESXi API username |
| `ansible_vmware_password` | vCenter/ESXi API password |
| `ansible_vmware_validate_certs` | Enable/disable TLS certificate validation |
### 4.5 Multi-Disk Schema
`system.disks[0]` is always the OS disk. Additional entries define data disks.
| Key | Type | Description |
| ------------- | ------ | ---------------------------------------------------- |
| `size` | number | Disk size in GB (required for virtual installs) |
| `device` | string | Explicit block device (required for physical data disks) |
| `mount.path` | string | Mount point (for additional disks) |
| `mount.fstype`| string | `btrfs`, `ext4`, or `xfs` |
| `mount.label` | string | Optional filesystem label |
| `mount.opts` | string | Mount options (`defaults` by default) |
| `mount.opts` | string | Mount options (default: `defaults`) |
Example:
Virtual install example:
```yaml
system:
@@ -270,7 +314,7 @@ system:
fstype: ext4
```
For physical installs, include device paths:
Physical install example (device paths required):
```yaml
system:
@@ -285,85 +329,74 @@ system:
fstype: ext4
```
## Advanced Partitioning Overrides
### 4.6 Advanced Partitioning Overrides
Use these only when you need to override default layout behavior.
Use these only when you need to override the default partition layout logic.
| 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_separate_boot` | Force a separate `/boot` partition | 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
## 5. How to Use the Playbook
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
### 5.1 Prerequisites
- Ansible installed on the control machine.
- Inventory and variables prepared for your target hosts.
- Inventory file with target systems defined and variables configured.
- Disposable/non-production targets (the playbook enforces production-safety checks).
## Usage
### 5.2 Running the Playbook
Execute the playbook using `ansible-playbook`, ensuring that all necessary variables are defined either in the inventory, in a vars file, or passed via `-e`. Credentials (`root_password`, `user_name`, `user_password`, `user_public_key`) are prompted interactively unless supplied through inventory or extra vars.
```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
ansible-playbook -i inventory.yml main.yml -e @vars_example.yml
```
## Security
### 5.3 Example Usage
Store sensitive data (passwords, API tokens, private keys) with Ansible Vault instead of plaintext inventory files.
Use the bundled example files as starting points for new inventories:
## Operational Notes
- `inventory_example.yml` -- Proxmox virtual setup
- `inventory_libvirt_example.yml` -- libvirt virtual setup
- `inventory_baremetal_example.yml` -- bare-metal physical setup
- `vars_example.yml` -- shared variable overrides
```bash
# Proxmox example
ansible-playbook -i inventory_example.yml main.yml
# libvirt example
ansible-playbook -i inventory_libvirt_example.yml main.yml
# Custom inventory with separate vars file
ansible-playbook -i inventory.yml main.yml -e @vars_example.yml
```
## 6. Security
To protect sensitive information such as passwords, API keys, and other confidential variables (e.g. `hypervisor.password`, `system.luks.passphrase`), **use Ansible Vault** instead of plaintext inventory files.
## 7. 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.
- For physical installs, sizing is derived from the detected install drive; set installer access (`ansible_user`/`ansible_password`) when the installer environment differs from the prompted user credentials.
- `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).
- `hypervisor.type` selects backend-specific provisioning and cleanup behavior.
- Guest tools are selected automatically by hypervisor: `qemu-guest-agent` for `libvirt`/`proxmox`, `open-vm-tools` for `vmware`.
- With `system.luks.method: tpm2` on virtual installs, the virtualization role enables a TPM2 device where supported (libvirt/proxmox/vmware).
- With LUKS enabled on non-Arch targets, provisioning uses an ESP (512 MiB), a separate `/boot` (1 GiB), and the encrypted root; adjust sizes via `partitioning_efi_size_mib` and `partitioning_boot_size_mib` if needed.
- For VMware, `hypervisor.ssh: true` enables SSH on the guest and switches the connection to SSH for the remaining tasks.
- Molecule is scaffolded with a delegated driver and a no-op converge for lint-only validation.
## Safety
## 8. 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
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.
Always run lint after changes: