Skip to content

Files

Latest commit

orbatschoworbatschow
and
orbatschow
Sep 13, 2019
798900a · Sep 13, 2019

History

History
201 lines (170 loc) · 7.32 KB

network.markdown

File metadata and controls

201 lines (170 loc) · 7.32 KB
layout page_title sidebar_current description
libvirt
Libvirt: libvirt_network
docs-libvirt-network
Manages a virtual machine (network) in libvirt

libvirt_network

Manages a VM network resource within libvirt. For more information see the official documentation.

Example Usage

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"

  #  list of subnets the addresses allowed for domains connected
  # also derived to define the host addresses
  # also derived to define the addresses 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) the MTU for the network. If not supplied, the underlying device's
  # default is used (usually 1500)
  # mtu = 9000

  # (Optional) DNS configuration
  dns {
    # (Optional, default false)
    # Set to true, if no other option is specified and you still want to 
    # enable dns.
    enabled = true
    # (Optional, default false)
    # true: DNS requests under this domain will only be resolved by the
    # virtual network's own DNS server
    # false: Unresolved requests will be forwarded to the host's
    # upstream DNS server if the virtual network's DNS server does not
    # have an answer.local_only = true

    # (Optional) one or more DNS forwarder entries.  One or both of
    # "address" and "domain" must be specified.  The format is:
    # forwarders {
    #     address = "my address"
    #     domain = "my domain"
    #  } 
    # 

    # (Optional) one or more DNS host entries.  Both of
    # "ip" and "hostname" must be specified.  The format is:
    # hosts  {
    #     hostname = "my_hostname"
    #     ip = "my.ip.address.1"
    #   }
    # hosts {
    #     hostname = "my_hostname"
    #     ip = "my.ip.address.2"
    #   }
    # 

    # (Optional) one or more static routes.
    # "cidr" and "gateway" must be specified. The format is:
    # routes {
    #     cidr = "10.17.0.0/16"
    #     gateway = "10.18.0.2"
    #   }
  }
}

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 - (Optional) The domain used by the DNS server.
  • addresses - (Optional) A list of (0 or 1) IPv4 and (0 or 1) IPv6 subnets in CIDR notation. This defines the subnets associated to that network. This argument is also used to define the address on the real host. If dhcp { enabled = true } addresses is also used to define the address range served by the DHCP server. No DHCP server will be started if addresses is omitted.
  • 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).
  • mtu - (Optional) The MTU to set for the underlying network interfaces. When not supplied, libvirt will use the default for the interface, usually 1500. Libvirt version 5.1 and greater will advertise this value to nodes via DHCP.
  • autostart - (Optional) Set to true to start the network on host boot up. If not specified false is assumed.
  • routes - (Optional) a list of static routes. A cidr and a gateway must be provided. The gateway must be reachable via the bridge interface.
  • dns - (Optional) configuration of DNS specific settings for the network

Inside of dns section the following argument are supported:

  • local_only - (Optional) true/false: true means 'do not forward unresolved requests for this domain to the part DNS server
  • forwarders - (Optional) Either address, domain, or both must be set
  • srvs - (Optional) a DNS SRV entry block. You can have one or more of these blocks in your DNS definition. You must specify service and protocol.
  • hosts - (Optional) a DNS host entry block. You can have one or more of these blocks in your DNS definition. You must specify both ip and hostname.

An advanced example of round-robin DNS (using DNS host templates) follows:

resource "libvirt_network" "my_network" {
  ...
  dns {
    hosts { flatten(data.libvirt_network_dns_host_template.hosts.*.rendered) }
  }
  ...
}

data "libvirt_network_dns_host_template" "hosts" {
  count    = var.host_count
  ip       = var.host_ips[count.index]
  hostname = "my_host"
}

An advanced example of setting up multiple SRV records using DNS SRV templates is:

data "libvirt_network_dns_srv_template" "etcd_cluster" {
  count    = var.etcd_count
  service  = "etcd-server"
  protocol = "tcp"
  domain   = var.discovery_domain
  target   = "${var.cluster_name}-etcd-${count.index}.${discovery_domain}"
}

resource "libvirt_network" "k8snet" {
  ...
  dns {
    srvs = [ flatten(data.libvirt_network_dns_srv_template.etcd_cluster.*.rendered) ]
  }
  ...
}
  • dhcp - (Optional) DHCP configuration. You need to use it in conjuction with the adresses variable.
    • enabled - (Optional) when false, disable the DHCP server
				resource "libvirt_network" "test_net" {
					name      = "networktest"
					mode      = "nat"
					domain    = "k8s.local"
					addresses = ["10.17.3.0/24"]
					dhcp {
						enabled = true
					}

Altering libvirt's generated network XML definition

The optional xml block relates to the generated network XML.

Currently the following attributes are supported:

  • xslt: specifies a XSLT stylesheet to transform the generated XML definition before creating the network. This is used to support features the provider does not allow to set from the schema. It is not recommended to alter properties and settings that are exposed to the schema, as terraform will insist in changing them back to the known state.

See the domain option with the same name for more information and examples.

Attributes Reference

  • id - a unique identifier for the resource