Ansible-Bootstrap/README.md

Ansible-Bootstrap

An Ansible playbook for automating system bootstrap processes in an Infrastructure-as-Code manner.

Info

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.

NOTE:

• 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:

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)

Documentation

Table of Contents

1. Overview
2. Global Variables
3. Inventory Variables
4. How to Use the Playbook
   • 4.1 Prerequisites
   • 4.2 Running the Playbook
   • 4.3 Example Usage

1. Overview

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.

2. Global Variables

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
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

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
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.

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
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 (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.yml file containing the required configurations.

4.3 Example Usage

An effective way to use the playbook involves defining all necessary configurations within a vars.yml file. 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:

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/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.
• With LUKS enabled on Debian/Ubuntu and RHEL-based systems, provisioning uses an ESP (50 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.