Terraform provider for libvirt
(IRC gateway)
- Planning board: Github Projects
This is a terraform provider that lets you provision servers on a libvirt host via Terraform.
Table of Content
- Migrating to terraform v13
- Introduction and Goals
- Downloading
- Installing
- Quickstart
- Building from source
- How to contribute
- Upstream project using this provider
Website Docs
Introduction & Goals
This project exists:
- To allow teams to get the benefits Software Defined Infrastructure Terraform provides, on top of classical and cheap virtualization infrastructure provided by Linux and KVM This helps in very dynamic DevOps, Development and Testing activities.
- To allow for mixing KVM resources with other infrastructure Terraform is able to manage
What is NOT in scope:
-
To support every advanced feature libvirt supports
This would make the mapping from terraform complicated and not maintanable. See the How to contribute section to understand how to approach new features.
Downloading
Builds for openSUSE, CentOS, Ubuntu, Fedora are created with openSUSE's OBS. The build definitions are available for both the stable and master branches.
Using published binaries/builds
- Stable releases: Head to the releases section and download the latest stable release build for your distribution.
- git master builds: Head to the download area of the OBS project and download the build for your distribution.
Using packages
Follow the instructions for your distribution:
Building from source
Requirements
- Terraform
- Go (to build the provider plugin)
- libvirt 1.2.14 or newer development headers
cgo
is required by the libvirt-go package.export CGO_ENABLED="1"
This project uses go modules to vendor all its dependencies.
You do not have to interact with modules
since the vendored packages are already included in the repo.
Ensure you have the latest version of Go installed on your system, terraform usually takes advantage of features available only inside of the latest stable release.
You need also need libvirt-dev(el) package installed.
Building The Provider
Clone repository to: $GOPATH/src/github.com/dmacvicar/terraform-provider-libvirt
mkdir -p $GOPATH/src/github.com/dmacvicar; cd $GOPATH/src/github.com/dmacvicar
git clone https://github.com/dmacvicar/terraform-provider-libvirt.git
Enter the provider directory and build the provider
cd $GOPATH/src/github.com/dmacvicar/terraform-provider-libvirt
make install
If you are using Go >= 1.11, you don't need to build inside GOPATH:
export GO111MODULE=on
export GOFLAGS=-mod=vendor
go mod vendor
make install
You will now find the binary at $GOPATH/bin/terraform-provider-libvirt
.
Windows
To build it on Windows (64bit) one can use MinGW64 (http://www.msys2.org/)
Install Golang on Windows
Clone terraform-provider-libvirt repository
Open MinGW64 Console
pacman -S mingw-w64-x86_64-libvirt
export PATH=$PATH:/c/Go/bin
pacman -S mingw-w64-x86_64-pkg-config
pacman -S mingw-w64-x86_64-glib2
pacman -S mingw-w64-x86_64-dbus-glib
pacman -S mingw-w64-x86_64-libssh
pacman -S mingw-w64-x86_64-yajl
export GO111MODULE=on
export GOFLAGS=-mod=vendor
go install
Installing
- Check that libvirt daemon 1.2.14 or newer is running on the hypervisor (
virsh version --daemon
) mkisofs
is required to use the CloudInit
Copied from the Terraform documentation:
At present Terraform can automatically install only the providers distributed by HashiCorp. Third-party providers can be manually installed by placing their plugin executables in one of the following locations depending on the host operating system:
On Linux and unix systems, in the sub-path
.terraform.d/plugins
in your user's home directory.
On Windows, in the sub-path
terraform.d/plugins
beneath your user's "Application Data" directory.
terraform init will search this directory for additional plugins during plugin initialization.
Using the provider
Here is an example that will setup the following:
- A virtual server resource
(create this as libvirt.tf and run terraform commands from this directory):
provider "libvirt" {
uri = "qemu:///system"
}
You can also set the URI in the LIBVIRT_DEFAULT_URI environment variable.
Now, define a libvirt domain:
resource "libvirt_domain" "terraform_test" {
name = "terraform_test"
}
Now you can see the plan, apply it, and then destroy the infrastructure:
$ terraform init
$ terraform plan
$ terraform apply
$ terraform destroy
Look at more advanced examples here
Using multiple hypervisors / provider instances
You can target different libvirt hosts instantiating the provider multiple times. Example.
Using qemu-agent
From its documentation, qemu-agent:
It is a daemon program running inside the domain which is supposed to help management applications with executing functions which need assistance of the guest OS.
Until terraform-provider-libvirt 0.4.2, qemu-agent was used by default to get network configuration. However, if qemu-agent is not running, this creates a delay until connecting to it times-out.
In current versions, we default to not to attempt connecting to it, and attempting to retrieve network interface information from the agent needs to be enabled explicitly with qemu_agent = true
, further details here. Note that you still need to make sure the agent is running in the OS, and that is unrelated to this option.
Note: when using bridge network configurations you need to enable the qemu_agent = true
. otherwise you will not retrieve the ip adresses of domains.
Be aware that this variables may be subject to change again in future versions.
Upstream projects using terraform-libvirt:
-
sumaform sumaform is a way to quickly configure, deploy, test Uyuni and SUSE Manager setups with clients and servers.
-
ha-cluster-sap Automated HA and SAP Deployments in Public/Private Clouds (including Libvirt/KVM)
-
ceph-open-terrarium ceph-open-terrarium is a way to quickly configure, deploy, tests CEPH cluster without or with Deepsea
-
- kubic-terraform-kvm Kubic Terraform script using KVM/libvirt
-
Community Driven Docker Examples Docker examples showing how to use the Libvirt Provider
-
Openshift 4 Installer The Openshift 4 Installer uses Terraform for cluster orchestration and relies on terraform-provider-libvirt for libvirt platform.
Authors
- Duncan Mac-Vicar P. [email protected]
See also the list of contributors who participated in this project.
The structure and boilerplate is inspired from the Softlayer and Google Terraform provider sources.
License
- Apache 2.0, See LICENSE file