Skip to content

Add sub-modules readme #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jmutai merged 1 commit into from
Jun 16, 2025
Merged

Add sub-modules readme #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,9 @@ provider "libvirt" {
}

module "storage_pool" {
source = "git::https://github.com/cloudspinx/terraform-kvm-modules.git//modules/storage-pool?ref=main"
source = "cloudspinx/kvm-modules/libvirt"
#version = "1.1.1"
#source = "git::https://github.com/cloudspinx/terraform-kvm-modules.git//modules/storage-pool?ref=main"
create_storage_pool = true
storage_pool_name = "vms_pool" # Set to name you want to use
storage_pool_path = "/data/vms_pool" # Path to use for the pool. Make sure not used by another pool `virsh pool-list`
Expand Down
106 changes: 106 additions & 0 deletions modules/libvirt-network/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
## Libvirt network module

The [network sub-module](https://github.com/cloudspinx/terraform-libvirt-kvm-modules/tree/main/modules/libvirt-network) allows you to create and destroy libvirt networks.

### Inputs

| Name | Description | Type | Default |
|------------------------|---------------------------------------------|--------------|-------------------------|
| `create_network` | Whether to create the libvirt network | bool | `false` |
| `network_name` | The name of the libvirt network | string | `"private"` |
| `network_bridge` | The bridge device for the network | string | `"virbr10"` |
| `network_mode` | The network mode (e.g., nat, bridge) | string | `"nat"` |
| `network_mtu` | The MTU for the network | number | `1500` |
| `network_autostart` | Whether the network should autostart | bool | `true` |
| `network_cidr` | List of CIDR addresses for the network | list(string) | `["172.21.0.0/24"]` |
| `network_dhcp_enabled` | Whether DHCP is enabled for the network | bool | `true` |

### Outputs

| Name | Description |
|-------------|--------------------------------------|
| `network_id` | The ID of the created libvirt network |
| `name` | The name of the libvirt network |

### Example 1: Create nat libvirt network

This example creates nat libvirt network:

```hcl
terraform {
required_version = ">= 1.0"
required_providers {
libvirt = {
source = "dmacvicar/libvirt"
version = "0.8.3"
}
}
}

provider "libvirt" {
uri = "qemu:///system"
#uri = "qemu+ssh://root@192.168.1.7/system"
}

module "libvirt_network" {
source = "git::https://github.com/cloudspinx/terraform-kvm-modules.git//modules/libvirt-network?ref=main"
create_network = true
network_name = "private"
network_mode = "nat"
network_mtu = 1500
network_cidr = ["172.24.30.0/24"]
network_autostart = true
}
```

Run terraform commands to create network:

```bash
terraform init
terraform apply
```

Validate:

```bash
# virsh net-list
Name State Autostart Persistent
--------------------------------------------
default active yes yes
private active yes yes

# virsh net-dumpxml private
```

### Example 2: Create libvirt network on existing host bridge

List configured bridge(s) on the host:

```bash
# brctl show
bridge name bridge id STP enabled interfaces
br0 8000.22d1dfd71e10 no enp89s0
```

Creating libvirt network using terraform

```hcl
module "libvirt_network" {
# Note that cidr and mtu are missing. This is often managed externally in bridged networks - network switch / router.
source = "git::https://github.com/cloudspinx/terraform-kvm-modules.git//modules/libvirt-network?ref=main"
create_network = true
network_name = "br0" # Good to use same name as bridge name
network_mode = "bridge" # Set network mode to bridge
network_bridge = "br0" # Name of host bridge to use
network_autostart = true
}
```

Create and confirm:

```bash
terraform plan
terraform init -upgrade
terraform apply
virsh net-list
```
91 changes: 91 additions & 0 deletions modules/os-images/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
## Cloud images module

To streamline instance creation, we created a [cloud images management module](https://github.com/cloudspinx/terraform-libvirt-kvm-modules/tree/main/modules/os-images)

### 1. Automatic image download (Default) - using the module

- Users can specify `os_name`, and optionally a `version`.
- If `version` is not provided, the latest available version is used.
- Terraform will automatically download the required cloud image during provisioning.

Table of images populated into sub-module: `modules/os-images`:

#### Supported OS Images

If version is not specified, it will default to using the latest version for that os.

| **OS Name** | **Version** | **Latest Version(Default choice)** |
|-------------------|------------|--------------------|
| **ubuntu** | latest | 24.04 |
| | 24.04 | |
| | 20.04 | |
| | 18.04 | |
| | 16.04 | |
| **rockylinux** | latest | 9 |
| | 9 | |
| | 8 | |
| **almalinux** | latest | 9 |
| | 9 | |
| | 8 | |
| **oraclelinux** | latest | 9 |
| | 9 | |
| | 8 | |
| **centos-stream** | latest | 9 |
| | 9 | |
| **debian** | latest | 12 |
| | 12 | |
| | 11 | |
| | 10 | |
| **fedora** | latest | 42 |
| | 41 | |
| **alpine** | latest | 3.21 |
| | 3.20 | |
| **amazonlinux** | latest | 2023 |
| **opensuse** | latest | 15.6 |
| | 15.5 | |
| **archlinux** | latest | latest |
| **freebsd** | latest | 14 |
| | 13 | |

Usage example:

```bash
# Ubuntu 24.04 cloud image
os_name = "ubuntu"
os_version = "24.04"

# AlmaLinux 8 cloud image
os_name = "almalinux"
os_version = "8"

# If you just provide the os_name, then latest release is used:
os_name = "debian"
```

#### 2. Cached Image Approach (Recommended for slow networks)

- Instead of downloading the image every time, users can pre-cache frequently used images locally.
- The module allows specifying a local path for the image, bypassing the need for downloads.
- This approach is particularly useful in development environments where instances are frequently created and destroyed. Or if bandwidth is an issue.


```bash
IMAGE_PATH="/home/os-images" # Define path to store cloud images
mkdir -p /home/os-images # Create directory where images are cached
cd /home/os-images # Naviage to the directory
wget <cloud-image-url> # Download remote cloud image locally
```

To use the cached image method, simply set `custom_image_path_url` to the local path of the pre-downloaded image. If left empty, the module will revert to automatic image downloading. The default image chosen in latest Ubuntu LTS, which at the time of updating this content it's `24.04`.

The `custom_image_path_url` can also be used to specify remote custom link to a cloud image to be downloaded. See below examples.

```bash
# Example
custom_image_path_url = "file:///home/os-images/ubuntu-latest.qcow2"
```

The `custom_image_path_url` can also be used to specify custom image URL:
```bash
custom_image_path_url = "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
```
62 changes: 62 additions & 0 deletions modules/storage-pool/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
## Libvirt storage pool module

We provide a [storage sub-module](https://github.com/cloudspinx/terraform-libvirt-kvm-module/tree/main/modules/storage-pool) in the repository that can be used to create storage pools independently.

### Inputs

| Name | Description | Type | Default |
|---------------------|--------------------------------------------------|--------|--------------------------|
| `storage_pool_name` | The name of the storage Libvirt pool | string | `"vms_storage"` |
| `create_storage_pool` | Whether to create the storage Libvirt storage pool | bool | `true` |
| `storage_pool_path` | The path where the storage Libvirt pool will be stored | string | `"/var/lib/libvirt/images"` |

### Outputs

| Name | Description |
|----------|-----------------------------------------------|
| `pool_id` | The ID of the created Libvirt storage pool |
| `name` | The name of the created Libvirt storage pool |

Usage example:

```hcl
terraform {
required_version = ">= 1.0"
required_providers {
libvirt = {
source = "dmacvicar/libvirt"
version = "0.8.3"
}
}
}

provider "libvirt" {
uri = "qemu:///system"
#uri = "qemu+ssh://root@192.168.1.7/system"
}

module "storage_pool" {
source = "git::https://github.com/cloudspinx/terraform-kvm-modules.git//modules/storage-pool?ref=main"
create_storage_pool = true
storage_pool_name = "vms_pool" # Set to name you want to use
storage_pool_path = "/data/vms_pool" # Path to use for the pool. Make sure not used by another pool `virsh pool-list`
}
```

Then create storage pool resource:

```bash
terraform init
terraform plan
terraform apply
```

Confirm creation:

```bash
# virsh pool-list
Name State Autostart
--------------------------------
default active yes
vms_pool active yes
```