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](#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)

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

```bash
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`, `inventory_libvirt_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.
- 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 (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.