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

Docs, examples, and tooling

Browse Source
This commit is contained in:
Sandwich
2025-12-27 23:07:47 +01:00
parent dda1287f23
commit 0211efbae7
7 changed files with 228 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.ansible-lint Normal file
View File

@@ -0,0 +1,2 @@
skip_list:
- run-once

151
README.md
View File

@@ -1,6 +1,6 @@
# Ansible-Bootstrap
An Ansible playbook for automating system bootstrap processes in an Infrastructure-as-Code manner, utilizing ArchISO as the foundational tool.
An Ansible playbook for automating system bootstrap processes in an Infrastructure-as-Code manner.
# Info
@@ -8,13 +8,15 @@ Most of the roles are adaptable for use with systems beyond ArchLinux, requiring
**NOTE**:
- For RHEL 8 and RHEL 9, repository access requires the `rhel_iso` variable. This variable specifies a local ISO or proxy repository.
- 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.
# Supported Distributions
This playbook supports multiple Linux distributions with specific versions tailored to each. Below is a list of supported distributions:
This playbook supports multiple Linux distributions with specific versions tailored to each.
Below is a list of supported distributions:
| `os` | Distribution |
| ---------- | ---------------------------------- |
@@ -51,22 +53,70 @@ The playbook uses the ArchLinux ISO as a foundational tool to provides an effici
Global variables apply across your Ansible project and are loaded from `vars.yml` by default. 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.
### 2.1 Core Provisioning
| Variable | Description | Example Value |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------- |
| `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 and RHEL 9. | `local-btrfs:iso/rhel-9.4-x86_64-dvd.iso` |
| `install_type` | Type of installation. | `virtual`, `physical` |
| `hypervisor` | Type of hypervisor. | `libvirt`, `proxmox`, `vmware`, `none` |
| `vmware_ssh` | If Ansible should use SSH after base VM setup on VMware. | `true`, `false (default)` |
| `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` |
| `selinux` (optional) | Toggle SELinux where supported. | `true`, `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_password` | Password for hypervisor authentication. | `123456` |
| `hypervisor_storage` | Storage identifier for VM disks. | `local-btrfs` |
| `hypervisor_url` | URL/IP address for the hypervisor interface. | `192.168.0.2` |
| `hypervisor_username` | Username for hypervisor authentication. | `root@pam` |
| `install_drive` | Drive where the system will be installed. | `/dev/sda` |
| `install_type` | Type of installation. | `virtual`, `physical` |
| `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` |
| `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` |
| `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` |
To protect sensitive information, such as passwords, API keys, and other confidential variables (e.g., `hypervisor_password`), **it is recommended to use Ansible Vault**.
@@ -74,30 +124,51 @@ To protect sensitive information, such as passwords, API keys, and other confide
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 |
| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `cis` (optional) | Adjusts the installation to be CIS level 3 conformant. | `true`, `false` |
| `selinux` (optional) | Toggle SELinux, `false` means it should be disabled.` | `true`, `false` |
| `filesystem` | Filesystem type for the VM's primary storage. | `btrfs`, `ext4`, `xfs` |
| `hostname` | The hostname assigned to the virtual machine or system. | `vm01` |
| `os` | Operating system to be installed on the VM. | `archlinux`, `almalinux`, `debian11`, `debian12`, `fedora`, `rhel8`, `rhel9`, `rhel10`, `rocky`, `ubuntu`, `ubuntu-lts` |
| `root_password` | Root password for the VM or system, used for initial setup or secure access. | `SecurePass123` |
| `user_name` | Username for a user account within the VM, often used with cloud-init. | `adminuser` |
| `user_password` | Password for the user account within the VM. | `UserPass123` |
| `user_public_key` | SSH Key for the user account within the VM. | `ssh-ed25519 AAAAC` |
| `vm_ballo` (optional) | Ballooning memory size for the VM, used to adjust memory allocation dynamically. | `2048` |
| `vm_cpus` | Number of CPU cores assigned to the virtual machine. | `4` |
| `vm_dns` | DNS server IP address(es) for the virtual machine's network configuration. | `1.0.0.1`, `1.1.1.1` |
| `vm_dns_search` | DNS search zone for the virtual machine's network configuration. | `example.com` |
| `vm_gw` | Default gateway IP address for the virtual machine's network configuration. | `192.168.0.1` |
| `vm_id` | Unique identifier for the virtual machine. | `101` |
| `vm_ip` | IP address assigned to the virtual machine. | `192.168.0.10` |
| `vm_nm` (optional) | IP address netmask assigned to the virtual machine. | `255.255.255.0` |
| `vm_nms` (optional) | IP address netmask assigned to the virtual machine. | `24` |
| `vm_memory` | Amount of memory (in MB) allocated to the virtual machine. | `2048` |
| `vm_nif` | Network interface type or identifier for the VM's network connection. | `vmbr0` |
| `vm_path (optional)` | Path or folder where the VM configuration or related files will be stored. | `/var/lib/libvirt/images/` |
| `vm_size` | Disk size allocated for the VM's primary storage (in GB). | `20` |
| ------------ | -------------------------------------- | ---------------------- |
| `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. | `20` |
| `vm_memory` | Amount of memory in MB. | `2048` |
| `vm_cpus` | Number of CPU cores. | `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
@@ -118,3 +189,15 @@ ansible-playbook -i inventory.yml -e @vars.yml main.yml
```
This command prompts Ansible to execute the `main.yml` playbook, applying configurations defined in both `vars.yml` and the inventory file.
Use `inventory_example.yml`, `vars_example.yml`, and the bare-metal examples as starting points for new inventories.
## Notes
- `vm_size`/`vm_memory` 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.
- 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.

9
collections/requirements.yml Normal file
View File

@@ -0,0 +1,9 @@
---
collections:
- name: ansible.posix
- name: community.general
- name: community.libvirt
- name: community.crypto
- name: community.proxmox
- name: community.vmware
- name: vmware.vmware

9
inventory_baremetal_example.yml Normal file
View File

@@ -0,0 +1,9 @@
---
all:
hosts:
baremetal01.example.com:
ansible_host: 10.0.0.162
ansible_user: root
ansible_password: "1234"
ansible_become_password: "1234"
hostname: "baremetal01.example.com"

63
inventory_example.yml
View File

@@ -1,35 +1,40 @@
---
all:
vars:
hypervisor: 'proxmox'
install_drive: '/dev/sda'
cis: true
boot_iso: "local-btrfs:iso/archlinux-x86_64.iso"
hypervisor: "proxmox"
install_type: "virtual"
install_drive: "/dev/sda"
boot_iso: "local:iso/archlinux-x86_64.iso"
vm_nif: "vmbr0"
vm_gw: "10.0.0.1"
vm_dns:
- 1.1.1.1
- 1.0.0.1
vm_dns_search:
- example.com
children:
promox-kvm:
proxmox:
hosts:
192.168.122.10:
hostname: proxy
proxy01.example.com:
ansible_host: 10.0.0.10
hostname: "proxy01.example.com"
vm_id: 100
os: archlinux
filesystem: btrfs
vm_memory: "2048"
vm_ballo: "1024"
vm_cpus: "2"
vm_size: "5"
vm_nif: vmbr1
vm_gw: 192.168.122.1
vm_dns: 1.1.1.1
vm_dns_search: "example.com"
192.168.122.11:
hostname: database
os: "archlinux"
filesystem: "btrfs"
vm_memory: 4096
vm_ballo: 2048
vm_cpus: 2
vm_size: 40
vm_ip: 10.0.0.10
database01.example.com:
ansible_host: 10.0.0.11
hostname: "database01.example.com"
vm_id: 101
os: rhel9
filesystem: xfs
vm_memory: "6144"
vm_ballo: "3072"
vm_cpus: "4"
vm_size: "40"
vm_nif: vmbr1
vm_gw: 192.168.122.1
vm_dns: 1.1.1.1
rhel_iso: "local-btrfs:iso/rhel-9.4-x86_64-dvd.iso"
os: "rhel9"
filesystem: "xfs"
vm_memory: 4096
vm_ballo: 2048
vm_cpus: 4
vm_size: 60
vm_ip: 10.0.0.11
rhel_iso: "local:iso/rhel-9.4-x86_64-dvd.iso"

15
vars_baremetal_example.yml Normal file
View File

@@ -0,0 +1,15 @@
---
hypervisor: "none"
install_type: "physical"
install_drive: "/dev/sda"
os: "archlinux"
filesystem: "btrfs"
luks_enabled: true
luks_passphrase: "1234"
luks_mapper_name: "SYSTEM_DECRYPTED"
luks_auto_decrypt: true
luks_auto_decrypt_method: "tpm2"
luks_tpm2_device: "auto"
luks_tpm2_pcrs: "7"

45
vars_example.yml
View File

@@ -1,18 +1,39 @@
---
# Set vm_ip for static addressing. Remove vm_ip to use DHCP.
vm_ip: "{{ inventory_hostname }}"
install_type: "virtual"
install_drive: "/dev/sda" # Use /dev/vda for virtio/libvirt.
custom_iso: false # Set true to skip ArchISO-specific validation and pacman setup.
hypervisor_url: "192.168.0.2"
hypervisor_url: "pve01.example.com"
hypervisor_username: "root@pam"
hypervisor_password: "SomePassword"
hypervisor_node: "NodeName"
hypervisor_storage: "local-btrfs"
hypervisor_password: "CHANGE_ME"
hypervisor_node: "pve01"
hypervisor_storage: "local-lvm"
hypervisor_datacenter: "dc01"
hypervisor_cluster: "cluster01"
# For VMware-Tools
ansible_vmware_host: "{{ hypervisor_url }}"
ansible_vmware_user: "{{ hypervisor_username }}"
ansible_vmware_password: "{{ hypervisor_password }}"
ansible_vmware_guest_path: "/{{ hypervisor_cluster }}/vm{{ vm_path }}/{{ hostname }}"
ansible_vmware_validate_certs: no
ansible_vmware_tools_user: "root"
ansible_vmware_tools_password: ""
# VMware (only needed when hypervisor: vmware)
# vm_path: "/Folder" # Optional folder path segment in vCenter.
vmware_ssh: true
# LUKS disk encryption (optional)
# These map to partitioning_luks_* internally.
luks_enabled: false
luks_passphrase: "CHANGE_ME"
luks_mapper_name: "SYSTEM_DECRYPTED"
luks_auto_decrypt: true
luks_auto_decrypt_method: "tpm2"
luks_tpm2_device: "auto"
luks_tpm2_pcrs: "7"
luks_keyfile_size: 64
luks_options: "discard,tries=3"
luks_type: "luks2"
luks_cipher: "aes-xts-plain64"
luks_hash: "sha512"
luks_iter_time: 4000
luks_key_size: 512
luks_pbkdf: "argon2id"
luks_use_urandom: true
luks_verify_passphrase: true