feat: Integrate Authentik OIDC into Semaphore and enhance Proxmox VM template creation with image list selection and SSH key management.
This commit is contained in:
Nikholas Pcenicni
@@ -1,84 +1,119 @@
|
||||
# Home Server Ansible Configuration
|
||||
# Proxmox VM Management Suite
|
||||
|
||||
This directory contains Ansible playbooks for managing the Proxmox home server environment.
|
||||
A comprehensive Ansible automation suite for managing Proxmox Virtual Machines. This suite allows you to easily create Cloud-Init templates, provision new VMs, manage backups, and decommission resources across multiple Proxmox hosts.
|
||||
|
||||
## Directory Structure
|
||||
## Features
|
||||
|
||||
- `inventory/`: Contains the inventory file `hosts.ini` where you define your servers.
|
||||
- `playbooks/`: Contains the actual Ansible playbooks.
|
||||
- `ansible.cfg`: Local Ansible configuration.
|
||||
- `requirements.yml`: List of Ansible collections required.
|
||||
- **Template Management**:
|
||||
- Automatically download Cloud Images (Ubuntu, Debian, etc.).
|
||||
- Pre-configured with Cloud-Init (SSH keys, IP Config).
|
||||
- Support for selecting images from a curated list or custom URLs.
|
||||
- **VM Provisioning**:
|
||||
- Clone from templates (Full or Linked clones).
|
||||
- Auto-start option.
|
||||
- **Lifecycle Management**:
|
||||
- Backup VMs (Snapshot mode).
|
||||
- Delete/Purge VMs.
|
||||
- **Security**:
|
||||
- **Automatic SSH Key Injection**: Automatically adds a defined Admin SSH key to every template.
|
||||
- Support for injecting additional SSH keys per deployment.
|
||||
|
||||
## Setup
|
||||
|
||||
1. **Install Requirements**:
|
||||
```bash
|
||||
ansible-galaxy install -r requirements.yml
|
||||
```
|
||||
|
||||
2. **Configure Inventory**:
|
||||
Edit `inventory/hosts.ini` and update the following:
|
||||
- `ansible_host`: The IP address of your Proxmox node.
|
||||
- `ansible_user`: The SSH user (usually root).
|
||||
- `proxmox_api_*`: Variables if you plan to use API-based modules in the future.
|
||||
|
||||
*Note: Ensure you have SSH key access to your Proxmox node for passwordless login, or uncomment `ansible_ssh_pass`.*
|
||||
|
||||
## Available Playbooks
|
||||
|
||||
### Create Ubuntu Cloud Template (`playbooks/create_ubuntu_template.yml`)
|
||||
|
||||
This playbook downloads a generic Ubuntu 22.04 Cloud Image and converts it into a Proxmox VM Template.
|
||||
|
||||
**Usage:**
|
||||
### 1. Requirements
|
||||
|
||||
Install the required Ansible collections:
|
||||
```bash
|
||||
# Run the playbook
|
||||
ansible-playbook playbooks/create_ubuntu_template.yml
|
||||
ansible-galaxy install -r requirements.yml
|
||||
```
|
||||
|
||||
**Variables:**
|
||||
You can override variables at runtime or by editing the playbook:
|
||||
### 2. Configuration
|
||||
|
||||
- `template_id`: Default `9000`
|
||||
- `template_name`: Default `ubuntu-2204-cloud`
|
||||
- `storage_pool`: Default `local-lvm`
|
||||
Edit `roles/proxmox_vm/defaults/main.yml` to set your global defaults, specifically the **Admin SSH Key**.
|
||||
|
||||
Example overriding variables:
|
||||
```bash
|
||||
ansible-playbook playbooks/create_ubuntu_template.yml -e "template_id=9001 template_name=my-custom-template"
|
||||
**Important Variable to Change:**
|
||||
```yaml
|
||||
# ansible/roles/proxmox_vm/defaults/main.yml
|
||||
admin_ssh_key: "ssh-ed25519 AAAAC3... your-actual-public-key"
|
||||
```
|
||||
|
||||
### Manage VM Playbook (`playbooks/manage_vm.yml`)
|
||||
## Usage
|
||||
|
||||
This unified playbook allows you to manage VMs (create from template, delete, backup, create template) across your Proxmox hosts.
|
||||
The main entry point is the playbook `playbooks/manage_vm.yml`. You control the behavior using the `proxmox_action` variable.
|
||||
|
||||
**Usage:**
|
||||
### 1. Create a Cloud-Init Template
|
||||
|
||||
The playbook target defaults to the `proxmox` group, but you should usually specify a specific host using `target_host` variable or `-l` limit.
|
||||
You can create a template by selecting a predefined alias (e.g., `ubuntu-22.04`) or providing a custom URL.
|
||||
|
||||
1. **Create a New Template**:
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_template vmid=9003 template_name=my-ubuntu-template"
|
||||
```
|
||||
**Option A: Select from List (Default)**
|
||||
Current aliases: `ubuntu-22.04`, `ubuntu-24.04`, `debian-12`.
|
||||
|
||||
2. **Create a VM from Template**:
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_vm vmid=9002 new_vmid=105 new_vm_name=my-new-vm"
|
||||
```
|
||||
```bash
|
||||
# Create Ubuntu 22.04 Template (ID: 9000)
|
||||
ansible-playbook playbooks/manage_vm.yml \
|
||||
-e "proxmox_action=create_template vmid=9000 template_name=ubuntu-22-template image_alias=ubuntu-22.04"
|
||||
```
|
||||
|
||||
3. **Delete a VM**:
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=delete_vm vmid=105"
|
||||
```
|
||||
**Option B: Custom URL**
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml \
|
||||
-e "proxmox_action=create_template \
|
||||
vmid=9001 \
|
||||
template_name=custom-linux \
|
||||
image_source_type=url \
|
||||
custom_image_url='https://example.com/image.qcow2'"
|
||||
```
|
||||
|
||||
4. **Backup a VM**:
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=backup_vm vmid=105"
|
||||
```
|
||||
### 2. Create a VM from Template
|
||||
|
||||
**Variables:**
|
||||
- `proxmox_action`: One of `create_template`, `create_vm`, `delete_vm`, `backup_vm` (Default: `create_vm`)
|
||||
- `target_host`: The host to run on (Default: `proxmox` group). Example: `-e "target_host=mercury"`
|
||||
Clone a valid template to a new VM.
|
||||
|
||||
*See `roles/proxmox_vm/defaults/main.yml` for all available configuration options.*
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml \
|
||||
-e "proxmox_action=create_vm \
|
||||
vmid=9000 \
|
||||
new_vmid=105 \
|
||||
new_vm_name=web-server-01"
|
||||
```
|
||||
|
||||
### 3. Backup a VM
|
||||
|
||||
Create a snapshot backup of a specific VM.
|
||||
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml \
|
||||
-e "proxmox_action=backup_vm vmid=105"
|
||||
```
|
||||
|
||||
### 4. Delete a VM
|
||||
|
||||
Stop and purge a VM.
|
||||
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml \
|
||||
-e "proxmox_action=delete_vm vmid=105"
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Handling Multiple Hosts
|
||||
You can target a specific Proxmox node using the `target_host` variable.
|
||||
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_vm ... target_host=mercury"
|
||||
```
|
||||
|
||||
### Injecting Additional SSH Keys
|
||||
You can add extra SSH keys for a specific run (or add them to the defaults file).
|
||||
|
||||
```bash
|
||||
ansible-playbook playbooks/manage_vm.yml \
|
||||
-e "proxmox_action=create_template ... additional_ssh_keys=['ssh-rsa AAAAB3... key1', 'ssh-ed25519 AAAA... key2']"
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
- `roles/proxmox_vm/`: Core logic role.
|
||||
- `defaults/main.yml`: Configuration variables (Images, Keys, Defaults).
|
||||
- `tasks/`: Action modules (`create_template.yml`, `create_vm.yml`, etc.).
|
||||
- `inventory/`: Host definitions.
|
||||
|
||||
Reference in New Issue
Block a user