diff options
Diffstat (limited to 'website')
| -rw-r--r-- | website/docs/index.html.markdown | 50 | ||||
| -rw-r--r-- | website/docs/r/cloudinit.html.markdown | 40 | ||||
| -rw-r--r-- | website/docs/r/coreos_ignition.html.markdown | 72 | ||||
| -rw-r--r-- | website/docs/r/domain.html.markdown | 364 | ||||
| -rw-r--r-- | website/docs/r/network.markdown | 108 | ||||
| -rw-r--r-- | website/docs/r/volume.html.markdown | 67 | ||||
| -rw-r--r-- | website/libvirt.erb | 38 |
7 files changed, 739 insertions, 0 deletions
diff --git a/website/docs/index.html.markdown b/website/docs/index.html.markdown new file mode 100644 index 00000000..6dc0cfe1 --- /dev/null +++ b/website/docs/index.html.markdown @@ -0,0 +1,50 @@ +--- +layout: "libvirt" +page_title: "Provider: libvirt" +sidebar_current: "docs-libvirt-index" +description: |- + The Libvirt provider is used to interact with Linux KVM/libvirt hypervisors. The provider needs to be configured with the proper connection information before it can be used. +--- + +# Libvirt Provider + +The Libvirt provider is used to interact with Linux +[libvirt](https://libvirt.org) hypervisors. + +The provider needs to be configured with the proper connection information +before it can be used. + +~> **Note:** while libvirt can be used with several types of hypervisors, this +provider focuses on [KVM](http://libvirt.org/drvqemu.html). Other drivers may not be +working and haven't been tested. + +## Example Usage + +```hcl +# Configure the Libvirt provider +provider "libvirt" { + uri = "qemu:///system" +} + +# Create a new domain +resource "libvirt_domain" "test1" { + ... +} +``` + +## Configuration Reference + +The following keys can be used to configure the provider. + +* `uri` - (Required) The [connection URI](https://libvirt.org/uri.html) used + to connect to the libvirt host. + +## Environment variables + +The libvirt connection URI can also be specified with the `LIBVIRT_DEFAULT_URI` +shell environment variable. + +```hcl +$ export LIBVIRT_DEFAULT_URI="qemu+ssh://root@192.168.1.100/system" +$ terraform plan +``` diff --git a/website/docs/r/cloudinit.html.markdown b/website/docs/r/cloudinit.html.markdown new file mode 100644 index 00000000..5cd67fd1 --- /dev/null +++ b/website/docs/r/cloudinit.html.markdown @@ -0,0 +1,40 @@ +--- +layout: "libvirt" +page_title: "Libvirt: libvirt_cloudinit" +sidebar_current: "docs-libvirt-cloudinit" +description: |- + Manages a cloud-init ISO to attach to a domain +--- + +# libvirt\_cloudinit + +Manages a [cloud-init](http://cloudinit.readthedocs.io/) ISO disk that can be +used to customize a domain during first boot. + +## Example Usage + +```hcl +resource "libvirt_cloudinit" "commoninit" { + name = "commoninit.iso" + local_hostname = "node" +} + +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) A unique name for the resource, required by libvirt. +* `pool` - (Optional) The pool where the resource will be created. + If not given, the `default` pool will be used. +* `local_hostname` - (Optional) If specified this is going to be the hostname of + the domain. +* `ssh_authorized_key` - (Optional) A public ssh key that will be accepted by + the `root` user. +* `user_data` - (Optional) Raw cloud-init user data. This content will + be merged automatically with the values specified in other arguments + (like `local_hostname`, `ssh_authorized_key`, etc). The contents of + `user_data` will take precedence over the ones defined by the other keys. + +Any change of the above fields will cause a new resource to be created. diff --git a/website/docs/r/coreos_ignition.html.markdown b/website/docs/r/coreos_ignition.html.markdown new file mode 100644 index 00000000..cac00305 --- /dev/null +++ b/website/docs/r/coreos_ignition.html.markdown @@ -0,0 +1,72 @@ +--- +layout: "libvirt" +page_title: "Libvirt: libvirt_ignition" +sidebar_current: "docs-libvirt-ignition" +description: |- + Manages a CoreOS Ignition file to supply to a domain +--- + +# libvirt\_ignition + +Manages a [CoreOS Ignition](https://coreos.com/ignition/docs/latest/supported-platforms.html) +file written as a volume to a libvirt storage pool that can be used to customize +a CoreOS Domain during first boot. + +~> **Note:** to make use of Ignition files with CoreOS the host must be running QEMU v2.6 or greater. + +## Example Usage + +```hcl +resource "libvirt_ignition" "ignition" { + name = "example.ign" + content = <file-name or ignition object> +} + +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) A unique name for the resource, required by libvirt. +* `pool` - (Optional) The pool where the resource will be created. + If not given, the `default` pool will be used. +* `content` - (Required) This points to the source of the Ignition configuration + information that will be used to create the Ignition file in the libvirt + storage pool. The `content` can be + * The name of file that contains Ignition configuration data, or its contents + * A rendered terraform Ignition object + +Any change of the above fields will cause a new resource to be created. + +## Integration with Ignition provider + +The `libvirt_ignition` resource can be integrated with terraform +[Ignition Provider](/docs/providers/ignition/index.html). + +An example where a terraform ignition provider object is used: + +```hcl +# Systemd unit resource containing the unit definition +resource "ignition_systemd_unit" "example" { + name = "example.service" + content = "[Service]\nType=oneshot\nExecStart=/usr/bin/echo Hello World\n\n[Install]\nWantedBy=multi-user.target" +} + +# Ignition config include the previous defined systemd unit resource +resource "ignition_config" "example" { + systemd = [ + "${ignition_systemd_unit.example.id}", + ] +} + +resource "libvirt_ignition" "ignition" { + name = "ignition" + content = "${ignition_config.example.rendered}" +} + +resource "libvirt_domain" "my_machine" { + coreos_ignition = "${libvirt_ignition.ignition.id}" + ... +} +``` diff --git a/website/docs/r/domain.html.markdown b/website/docs/r/domain.html.markdown new file mode 100644 index 00000000..6c40cb10 --- /dev/null +++ b/website/docs/r/domain.html.markdown @@ -0,0 +1,364 @@ +--- +layout: "libvirt" +page_title: "Libvirt: libvirt_domain" +sidebar_current: "docs-libvirt-domain" +description: |- + Manages a virtual machine (domain) in libvirt +--- + +# libvirt\_domain + +Manages a VM domain resource within libvirt. For more information see +[the official documentation](https://libvirt.org/formatdomain.html). + +## Example Usage + +```hcl +resource "libvirt_domain" "default" { + name = "test" +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) A unique name for the resource, required by libvirt. + Changing this forces a new resource to be created. +* `cpu` - (Optional) Configures CPU mode. See [below](#cpu-mode) for more + details. +* `vcpu` - (Optional) The amount of virtual CPUs. If not specified, a single CPU + will be created. +* `memory` - (Optional) The amount of memory in MiB. If not specified the domain + will be created with 512 MiB of memory be used. +* `running` - (Optional) Use `false` to turn off the instance. If not specified, + true is assumed and the instance, if stopped, will be started at next apply. +* `disk` - (Optional) An array of one or more disks to attach to the domain. The + `disk` object structure is documented [below](#handling-disks). +* `network_interface` - (Optional) An array of one or more network interfaces to + attach to the domain. The `network_interface` object structure is documented + [below](#handling-network-interfaces). +* `cloudinit` - (Optional) The `libvirt_cloudinit` disk that has to be used by + the domain. This is going to be attached as a CDROM ISO. Changing the + cloud-init won't cause the domain to be recreated, however the change will + have effect on the next reboot. +* `autostart` - (Optional) Set to `true` to start the domain on host boot up. + If not specified `false` is assumed. +* `filesystem` - (Optional) An array of one or more host filesystems to attach to + the domain. The `filesystem` object structure is documented + [below](#sharing-filesystem-between-libvirt-host-and-guest). +* `coreos_ignition` - (Optional) The + [libvirt_ignition](/docs/providers/libvirt/r/coreos_ignition.html) resource + that is to be used by the CoreOS domain. + +### UEFI images + +Some extra arguments are also provided for using UEFI images: + +* `firmware` - (Optional) The UEFI rom images for exercising UEFI secure boot in a qemu +environment. Users should usually specify one of the standard _Open Virtual Machine +Firmware_ (_OVMF_) images available for their distributions. The file will be opened +read-only. +* `nvram` - (Optional) the _nvram_ variables file corresponding to the firmware. When provided, +this file must be writable and specific to this domain, as it will be updated when running +the domain. However, `libvirt` can manage this automatically (and this is the recommended solution) +if a mapping for the firmware to a _variables file_ exists in `/etc/libvirt/qemu.conf:nvram`. +In that case, `libvirt` will copy that variables file into a file specific for this domain. + +So you should typically use the firmware as this, + +```hcl +resource "libvirt_domain" "my_machine" { + name = "my_machine" + firmware = "/usr/share/qemu/ovmf-x86_64-code.bin" + memory = "2048" + + disk { + volume_id = "${libvirt_volume.volume.id}" + } + ... +} +``` + +and `/etc/libvirt/qemu.conf` should contain: + +```hcl +nvram = [ + "/usr/share/qemu/ovmf-x86_64-code.bin:/usr/share/qemu/ovmf-x86_64-vars.bin" +] +``` + +### Handling disks + +The `disk` block supports: + +* `volume_id` - (Required) The volume id to use for this disk. +* `scsi` - (Optional) Use a scsi controller for this disk. The controller +model is set to `virtio-scsi` +* `wwn` - (Optional) Specify a WWN to use for the disk if the disk is using +a scsi controller, if not specified then a random wwn is generated for the disk + + +```hcl +resource "libvirt_volume" "leap" { + name = "leap" + source = "http://someurl/openSUSE_Leap-42.1.qcow2" +} + +resource "libvirt_volume" "mydisk" { + name = "mydisk" + base_volume_id = "${libvirt_volume.leap.id}" +} + +resource "libvirt_domain" "domain1" { + name = "domain1" + disk { + volume_id = "${libvirt_volume.mydisk.id}" + scsi = "yes" + } +} +``` + +Also note that the `disk` block is actually a list of maps, so it is possible to +declare several of them by using either the literal list and map syntax as in +the following examples: + +```hcl +resource "libvirt_domain" "my_machine" { + ... + disk { + volume_id = "${libvirt_volume.volume1.id}" + } + disk { + volume_id = "${libvirt_volume.volume2.id}" + } +} +``` + +```hcl +resource "libvirt_domain" "my_machine" { + ... + disk = [ + { + volume_id = "${libvirt_volume.volume1.id}" + }, + { + volume_id = "${libvirt_volume.volume2.id}" + } + ] +} +``` + +```hcl +resource "libvirt_domain" "my_machine" { + ... + disk = ["${var.disk_map_list}"] +} +``` + +### Handling network interfaces + +The `network_interface` specifies a network interface that can be connected +either to a virtual network (the preferred method on hosts with +dynamic / wireless networking configs) or directly to a LAN. + +```hcl +resource "libvirt_domain" "domain1" { + name = "domain1" + + network_interface { + network_id = "${libvirt_network.net1.id}" + hostname = "master" + addresses = ["10.17.3.3"] + mac = "AA:BB:CC:11:22:22" + wait_for_lease = 1 + } +} +``` + +When using a virtual network, users can specify: + +* `network_name` - (Optional) The name of an _existing_ network to attach this + interface to. The network will _NOT_ be managed by the Terraform libvirt + provider. +* `network_id` - (Optional) The ID of a network resource to attach this + interface to. This is a + [network resource](/docs/providers/libvirt/r/network.html) managed by the + Terraform libvirt provider. +* `mac` - (Optional) The specific MAC address to use for this interface. +* `addresses` - (Optional) An IP address for this domain in this network. +* `hostname` - (Optional) A hostname that will be assigned to this domain + resource in this network. +* `wait_for_lease`- (Optional) When creating the domain resource, wait until the + network interface gets a DHCP lease from libvirt, so that the computed IP + addresses will be available when the domain is up and the plan applied. + +When connecting to a LAN, users can specify a target device with: + +* `bridge` - Provides a bridge from the VM directly to the LAN. This assumes + there is a bridge device on the host which has one or more of the hosts + physical NICs enslaved. The guest VM will have an associated _tun_ device + created and enslaved to the bridge. The IP range / network configuration is + whatever is used on the LAN. This provides the guest VM full incoming & + outgoing net access just like a physical machine. +* `vepa` - All VMs' packets are sent to the external bridge. Packets whose + destination is a VM on the same host as where the packet originates from are + sent back to the host by the VEPA capable bridge (today's bridges are + typically not VEPA capable). +* `macvtap` - Packets whose destination is on the same host as where they + originate from are directly delivered to the target macvtap device. Both + origin and destination devices need to be in bridge mode for direct delivery. + If either one of them is in vepa mode, a VEPA capable bridge is required. +* `passthrough` - This feature attaches a virtual function of a SRIOV capable + NIC directly to a VM without losing the migration capability. All packets are + sent to the VF/IF of the configured network device. Depending on the + capabilities of the device additional prerequisites or limitations may apply; + for example, on Linux this requires kernel 2.6.38 or newer. + +Example of a `macvtap` interface: + +```hcl +resource "libvirt_domain" "my-domain" { + name = "master" + ... + network_interface { + macvtap = "eth0" + } +} +``` + +**Warning:** the [Qemu guest agent](http://wiki.libvirt.org/page/Qemu_guest_agent) +must be installed and running inside of the domain in order to discover the IP +addresses of all the network interfaces attached to a LAN. + +### Graphics devices + +The optional `graphics` block allows you to override the default graphics +settings. + +The block supports: + +* `type` - the type of graphics emulation (default is "spice") +* `autoport` - defaults to "yes" +* `listen_type` - "listen type", defaults to "none" + +On occasion we have found it necessary to set a `type` of `vnc` and a +`listen_type` of `address` with certain builds of QEMU. + +The `graphics` block will look as follows: + +```hcl +resource "libvirt_domain" "my_machine" { + ... + graphics { + type = "vnc" + listen_type = "address" + } +} +``` + +~> **Note well:** the `graphics` block is ignored for the architectures + `s390x` and `ppc64`. + + +### Console devices + +The optional `console` block allows you to define a console for the domain. + +The block looks as follows: + +```hcl +resource "libvirt_domain" "my_machine" { + ... + console { + type = "pty" + target_port = "0" + target_type = <"serial" or "virtio"> + source_path = "/dev/pts/4" + } +} +``` + +~> **Note well:** + <ul> + <li>You can repeat the `console` block to create more than one console, in the + same way that you can repeat `disk` blocks (see [above](#handling-disks)).</li> + <li>The `target_type` is optional for the first console and defaults to `serial`.</li> + <li>All subsequent `console` blocks must specify a `target_type` of `virtio`.</li> + <li>The `source_path` is optional for all consoles.</li> + </ul> + +See [libvirt Domain XML Console element](https://libvirt.org/formatdomain.html#elementsConsole) +for more information. + + +### CPU mode + +The optional `cpu` block allows to configure CPU mode. Example: + +```hcl +resource "libvirt_domain" "my_machine" { + ... + cpu { + mode = "host-passthrough" + } +} +``` + +To start the domain on host boot up set `autostart` to `true` like so: +``` +resource "libvirt_domain" "my_machine" { + ... + autostart = true +} +``` + +### Sharing filesystem between libvirt host and guest + +The optional `filesystem` block allows to define one or more [filesytem](https://libvirt.org/formatdomain.html#elementsFilesystems) +entries to be added to the domain. This allows to share a directory of the libvirtd +host with the guest. + +Currently the following attributes are supported: + + * `accessmode`: specifies the security mode for accessing the source. By default + the `mapped` mode is chosen. + * `source`: the directory of the host to be shared with the guest. + * `target`: an arbitrary string tag that is exported to the guest as a hint for + where to mount the source. + * `readonly`: enables exporting filesystem as a readonly mount for guest, by + default read-only access is given. + +Example: + +```hcl +filesystem { + source = "/tmp" + target = "tmp" + readonly = false +} +filesystem { + source = "/proc" + target = "proc" + readonly = true +} +``` + +The exported filesystems can be mounted inside of the guest in this way: + +```hcl +sudo mount -t 9p -o trans=virtio,version=9p2000.L,rw tmp /host/tmp +sudo mount -t 9p -o trans=virtio,version=9p2000.L,r proc /host/proc +``` + +This can be automated inside of `/etc/fstab`: +```hcl +tmp /host/tmp 9p trans=virtio,version=9p2000.L,rw 0 0 +proc /host/proc 9p trans=virtio,version=9p2000.L,r 0 0 +``` + +## Attributes Reference + +* `id` - a unique identifier for the resource. +* `network_interface.<N>.addresses.<M>` - M-th IP address assigned to the N-th + network interface. diff --git a/website/docs/r/network.markdown b/website/docs/r/network.markdown new file mode 100644 index 00000000..1c2f2757 --- /dev/null +++ b/website/docs/r/network.markdown @@ -0,0 +1,108 @@ +--- +layout: "libvirt" +page_title: "Libvirt: libvirt_network" +sidebar_current: "docs-libvirt-network" +description: |- + Manages a virtual machine (network) in libvirt +--- + +# libvirt\_network + +Manages a VM network resource within libvirt. For more information see +[the official documentation](https://libvirt.org/formatnetwork.html). + +## Example Usage + +```hcl +resource "libvirt_network" "kube_network" { + # the name used by libvirt + name = "k8snet" + + # mode can be: "nat" (default), "none", "route", "bridge" + mode = "nat" + + # the domain used by the DNS server in this network + domain = "k8s.local" + + # the addresses allowed for domains connected and served by the DHCP server + addresses = ["10.17.3.0/24", "2001:db8:ca2:2::1/64"] + + # (optional) the bridge device defines the name of a bridge device + # which will be used to construct the virtual network. + # (only necessary in "bridge" mode) + # bridge = "br7" + + # (Optional) one or more DNS forwarder entries. One or both of + # "address" and "domain" must be specified. The format is: + # dns_forwarder { + # address = "my address" + # domain = "my domain" + # } +} +``` + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) A unique name for the resource, required by libvirt. + Changing this forces a new resource to be created. +* `domain` - The domain used by the DNS server. +* `addresses` - A list of (0 or 1) ipv4 and (0 or 1) ipv6 subnets in CIDR notation + format for being served by the DHCP server. Address of subnet should be used. +* `mode` - One of: + - `none`: the guests can talk to each other and the host OS, but cannot reach + any other machines on the LAN. + - `nat`: it is the default network mode. This is a configuration that + allows guest OS to get outbound connectivity regardless of whether the host + uses ethernet, wireless, dialup, or VPN networking without requiring any + specific admin configuration. In the absence of host networking, it at + least allows guests to talk directly to each other. + - `route`: this is a variant on the default network which routes traffic from + the virtual network to the LAN **without applying any NAT**. It requires that + the IP address range be pre-configured in the routing tables of the router + on the host network. + - `bridge`: use a pre-existing host bridge. The guests will effectively be + directly connected to the physical network (i.e. their IP addresses will + all be on the subnet of the physical network, and there will be no + restrictions on inbound or outbound connections). The `bridge` network + attribute is mandatory in this case. +* `bridge` - (Optional) The bridge device defines the name of a bridge + device which will be used to construct the virtual network (when not provided, + it will be automatically obtained by libvirt in `none`, `nat` and `route` modes). +* `dns_forwarder` - (Optional) a DNS forwarder entry block. You can have + one or mode of these blocks in your network definition. You must specify one or + both of `address` and `domain`. You can use either of the forms below to + specify dns_forwarders: + +```hcl +resource "libvirt_network" "my_network" { + ... + dns_forwarder { + address = "my address" + } + dns_forwarder { + address = "my address 1" + domain = "my domain" + } +} +``` + +```hcl +resource "libvirt_network" "my_network" { + ... + dns_forwarder = [ + { + address = "my address" + }, + { + address = "my address 1" + domain = "my domain + } + ] +} +``` + +## Attributes Reference + +* `id` - a unique identifier for the resource diff --git a/website/docs/r/volume.html.markdown b/website/docs/r/volume.html.markdown new file mode 100644 index 00000000..78ef62f8 --- /dev/null +++ b/website/docs/r/volume.html.markdown @@ -0,0 +1,67 @@ +--- +layout: "libvirt" +page_title: "Libvirt: libvirt_volume" +sidebar_current: "docs-libvirt-volume" +description: |- + Manages a storage volume in libvirt +--- + +# libvirt\_volume + +Manages a storage volume in libvirt. For more information see +[the official documentation](https://libvirt.org/formatstorage.html). + +## Example Usage + +```hcl +# Base OS image to use to create a cluster of different +# nodes +resource "libvirt_volume" "opensuse_leap" { + name = "opensuse_leap" + source = "http://download.opensuse.org/repositories/Cloud:/Images:/Leap_42.1/images/openSUSE-Leap-42.1-OpenStack.x86_64.qcow2" +} + +# volume to attach to the "master" domain as main disk +resource "libvirt_volume" "master" { + name = "master.qcow2" + base_volume_id = "${libvirt_volume.opensuse_leap.id}" +} + +# volumes to attach to the "workers" domains as main disk +resource "libvirt_volume" "worker" { + name = "worker_${count.index}.qcow2" + base_volume_id = "${libvirt_volume.opensuse_leap.id}" + count = "${var.workers_count}" +} +``` + +~> **Tip:** when provisioning multiple domains using the same base image, create +a `libvirt_volume` for the base image and then define the domain specific ones +as based on it. This way the image will not be modified and no extra disk space +is going to be used for the base image. + +## Argument Reference + +The following arguments are supported: + +* `name` - (Required) A unique name for the resource, required by libvirt. + Changing this forces a new resource to be created. +* `pool` - (Optional) The storage pool where the resource will be created. + If not given, the `default` storage pool will be used. +* `source` - (Optional) If specified, the image will be uploaded into libvirt + storage pool. It's possible to specify the path to a local (relative to the + machine running the `terraform` command) image or a remote one. Remote images + have to be specified using HTTP(S) urls for now. +* `size` - (Optional) The size of the volume in bytes (if you don't like this, + help fix [this issue](https://github.com/hashicorp/terraform/issues/3287). + If `source` is specified, `size` will be set to the source image file size. +* `base_volume_id` - (Optional) The backing volume (CoW) to use for this volume. +* `base_volume_name` - (Optional) The name of the backing volume (CoW) to use + for this volume. Note well: when `base_volume_pool` is not specified the + volume is going to be searched inside of `pool`. +* `base_volume_pool` - (Optional) The name of the storage pool containing the + volume defined by `base_volume_name`. + +## Attributes Reference + +* `id` - a unique identifier for the resource diff --git a/website/libvirt.erb b/website/libvirt.erb new file mode 100644 index 00000000..707a51e6 --- /dev/null +++ b/website/libvirt.erb @@ -0,0 +1,38 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + <div class="docs-sidebar hidden-print affix-top" role="complementary"> + <ul class="nav docs-sidenav"> + <li<%= sidebar_current("docs-home") %>> + <a href="/docs/providers/index.html">All Providers</a> + </li> + + <li<%= sidebar_current("docs-libvirt-index") %>> + <a href="/docs/providers/libvirt/index.html">libvirt Provider</a> + </li> + + <li<%= sidebar_current("docs-libvirt-resource") %>> + <a href="#">Resources</a> + <ul class="nav nav-visible"> + <li<%= sidebar_current("docs-libvirt-resource-cloudinit") %>> + <a href="/docs/providers/libvirt/r/cloudinit.html">libvirt_cloudinit</a> + </li> + <li<%= sidebar_current("docs-libvirt-resource-coreos-ignition") %>> + <a href="/docs/providers/libvirt/r/coreos_ignition.html">libvirt_ignition</a> + </li> + <li<%= sidebar_current("docs-libvirt-resource-domain") %>> + <a href="/docs/providers/libvirt/r/domain.html">libvirt_domain</a> + </li> + <li<%= sidebar_current("docs-libvirt-resource-network") %>> + <a href="/docs/providers/libvirt/r/network.html">libvirt_network</a> + </li> + <li<%= sidebar_current("docs-libvirt-resource-volume") %>> + <a href="/docs/providers/libvirt/r/volume.html">libvirt_volume</a> + </li> + </ul> + </li> + </ul> + </div> + <% end %> + + <%= yield %> +<% end %> |