Skip to content

Commit 99dfb79

Browse files
josecelanojosecelano
committed
docs: add comprehensive local deployment instructions to README
- Add step-by-step local deployment guide with prerequisites verification - Position LXD as official provider and Multipass as experimental - Include complete OpenTofu workflow (init, plan, apply, output) - Add Ansible playbook execution instructions - Update comparison table to reflect official provider status - Provide installation commands for all required tools (LXD, OpenTofu, Ansible) - Add verification steps to confirm successful deployment - Emphasize LXD group membership setup requirements
1 parent 66217a0 commit 99dfb79

File tree

1 file changed

+133
-25
lines changed

1 file changed

+133
-25
lines changed

‎README.md‎

Lines changed: 133 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -14,44 +14,152 @@ This repository contains configurations for testing VM provisioning and cloud-in
1414

1515
This repository tests two different virtualization technologies:
1616

17-
### 🖥️ **Multipass (`config/tofu/multipass/`)**
17+
### ☁️ **LXD Containers (`config/tofu/lxd/`)** - **OFFICIAL**
18+
19+
- **Technology**: System containers with cloud-init support
20+
- **Status**: ✅ Official provider - Guaranteed GitHub Actions compatibility
21+
- **Best for**: CI/CD environments, fast provisioning, local development
22+
- **Requirements**: No special virtualization needed
23+
24+
**[📖 See detailed documentation →](config/tofu/lxd/README.md)**
25+
26+
### 🖥️ **Multipass (`config/tofu/multipass/`)** - **EXPERIMENTAL**
1827

1928
- **Technology**: Full VMs with nested virtualization
20-
- **Status**: ⚠️ Works in GitHub Actions but undocumented
21-
- **Best for**: Local development, full VM isolation
29+
- **Status**: ⚠️ Experimental - Works in GitHub Actions but undocumented support
30+
- **Best for**: Local development requiring full VM isolation
2231
- **Requirements**: Nested virtualization support
2332

2433
**[📖 See detailed documentation →](config/tofu/multipass/README.md)**
2534

26-
### ☁️ **LXD Containers (`config/tofu/lxd/`)**
35+
## 🔄 **Quick Comparison**
2736

28-
- **Technology**: System containers with cloud-init support
29-
- **Status**: ✅ Guaranteed GitHub Actions compatibility
30-
- **Best for**: CI/CD environments, fast provisioning
31-
- **Requirements**: No special virtualization needed
37+
| Feature | LXD Containers (Official) | Multipass (Experimental) |
38+
| -------------------------- | --------------------------- | ------------------------------ |
39+
| **Status** | ✅ Official Provider | ⚠️ Experimental |
40+
| **GitHub Actions Support** | ✅ Guaranteed | 🔶 Discovered but undocumented |
41+
| **Nested Virtualization** | ❌ Not needed | ✅ Required |
42+
| **Cloud-init Support** | ✅ Container boot | ✅ Full VM boot |
43+
| **Resource Usage** | ✅ Lower (containers) | ❌ Higher (full VMs) |
44+
| **Isolation Level** | 🔶 Process-level | ✅ Complete (separate kernel) |
45+
| **Boot Time** | ✅ Faster (container start) | ❌ Slower (full boot) |
46+
| **Docker Support** | ✅ Full support | ✅ Full support |
47+
| **Setup Complexity** | 🔶 Requires LXD setup | ✅ Simple (snap install) |
3248

33-
**[📖 See detailed documentation →](config/tofu/lxd/README.md)**
49+
## 🚀 **Getting Started**
3450

35-
## 🔄 **Quick Comparison**
51+
### 🏠 **Local Deployment (Recommended)**
3652

37-
| Feature | Multipass | LXD Containers |
38-
| -------------------------- | ------------------------------ | --------------------------- |
39-
| **GitHub Actions Support** | 🔶 Discovered but undocumented | ✅ Guaranteed |
40-
| **Nested Virtualization** | ✅ Required | ❌ Not needed |
41-
| **Cloud-init Support** | ✅ Full VM boot | ✅ Container boot |
42-
| **Resource Usage** | ❌ Higher (full VMs) | ✅ Lower (containers) |
43-
| **Isolation Level** | ✅ Complete (separate kernel) | 🔶 Process-level |
44-
| **Boot Time** | ❌ Slower (full boot) | ✅ Faster (container start) |
45-
| **Docker Support** | ✅ Full support | ✅ Full support |
46-
| **Setup Complexity** | ✅ Simple (snap install) | 🔶 Requires LXD setup |
53+
The **LXD provider** is the official and recommended approach for both local development and CI/CD environments. Multipass is experimental as GitHub runners' full virtualization support is undocumented.
4754

48-
## 🚀 **Getting Started**
55+
#### **1. Prerequisites Verification**
56+
57+
Before deploying, verify that all required tools are installed:
58+
59+
```bash
60+
# Check LXD installation
61+
lxd version
62+
63+
# Check OpenTofu installation
64+
tofu version
65+
66+
# Check Ansible installation
67+
ansible --version
68+
```
69+
70+
**Install missing tools:**
71+
72+
```bash
73+
# Install LXD (via snap - recommended)
74+
sudo snap install lxd
75+
sudo lxd init --auto
76+
sudo usermod -a -G lxd $USER
77+
78+
# Install OpenTofu
79+
curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/install-opentofu.sh -o install-opentofu.sh
80+
chmod +x install-opentofu.sh
81+
./install-opentofu.sh --install-method deb
82+
83+
# Install Ansible
84+
sudo apt update && sudo apt install ansible
85+
86+
# IMPORTANT: After adding user to lxd group, restart your terminal or run:
87+
newgrp lxd
88+
```
89+
90+
#### **2. Deploy Infrastructure with OpenTofu**
91+
92+
Navigate to the LXD configuration and deploy the VM:
93+
94+
```bash
95+
# Navigate to LXD configuration
96+
cd config/tofu/lxd
97+
98+
# Initialize OpenTofu
99+
tofu init
100+
101+
# Review planned changes (optional)
102+
tofu plan
103+
104+
# Deploy the infrastructure
105+
tofu apply
106+
# Type 'yes' when prompted
107+
108+
# View deployment results
109+
tofu output
110+
```
111+
112+
After successful deployment, you should see output similar to:
113+
114+
```text
115+
container_info = {
116+
"image" = "ubuntu:24.04"
117+
"ip_address" = "10.140.190.177"
118+
"name" = "torrust-vm"
119+
"status" = "Running"
120+
}
121+
```
122+
123+
#### **3. Configure with Ansible**
124+
125+
Execute Ansible playbooks to configure and verify the deployed VM:
126+
127+
```bash
128+
# Navigate to Ansible configuration
129+
cd ../../ansible
130+
131+
# Update inventory with the VM's IP address
132+
# Edit inventory.yml and update ansible_host with the IP from step 2
133+
134+
# Test connectivity
135+
ansible all -m ping
136+
137+
# Execute the cloud-init verification playbook
138+
ansible-playbook wait-cloud-init.yml
139+
```
140+
141+
#### **4. Verification**
142+
143+
Verify the deployment is working correctly:
144+
145+
```bash
146+
# Check VM status
147+
lxc list torrust-vm
148+
149+
# Connect to the VM
150+
lxc exec torrust-vm -- /bin/bash
151+
152+
# Test SSH connection (from Ansible directory)
153+
ssh -i ~/.ssh/testing_rsa torrust@<VM_IP>
154+
```
155+
156+
### 🧪 **Alternative Approaches**
49157

50-
Choose your preferred approach:
158+
Choose your preferred approach for specific use cases:
51159

52-
1. **For local development**: Start with [Multipass configuration](config/tofu/multipass/README.md)
53-
2. **For CI/CD reliability**: Use [LXD configuration](config/tofu/lxd/README.md)
54-
3. **For testing both**: Try both approaches to compare
160+
1. **For local development**: Start with [LXD configuration](config/tofu/lxd/README.md) (recommended)
161+
2. **For experimental testing**: Try [Multipass configuration](config/tofu/multipass/README.md) (nested virtualization required)
162+
3. **For testing both**: Compare both approaches to evaluate differences
55163

56164
## 🎭 **Ansible Configuration Management**
57165

0 commit comments

Comments
 (0)