Getting Started With Libvirt¶

Libvirt is a toolkit to interact with the virtualization capabilities of recent versions of Linux (and other OSes). This driver Salt cloud provider is currently geared towards libvirt with qemu-kvm.

https://libvirt.org/

Host Dependencies¶

libvirt >= 1.2.18 (older might work)

Salt-Cloud Dependencies¶

libvirt-python

Provider Configuration¶

For every KVM host a provider needs to be set up. The provider currently maps to one libvirt daemon (e.g. one KVM host).

Set up the provider cloud configuration file at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/*.conf.

# Set up a provider with qemu+ssh protocol
kvm-via-ssh:
  driver: libvirt
  url: qemu+ssh://user@kvm.company.com/system?socket=/var/run/libvirt/libvirt-sock

# Or connect to a local libvirt instance
local-kvm:
  driver: libvirt
  url: qemu:///system
  # work around flag for XML validation errors while cloning
  validate_xml: no

Cloud Profiles¶

Virtual machines get cloned from so called Cloud Profiles. Profiles can be set up at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/*.conf:

Configure a profile to be used:

centos7:
  # points back at provider configuration
  provider: local-kvm
  base_domain: base-centos7-64
  ip_source: ip-learning
  ssh_username: root
  password: my-very-secret-password
  # /tmp is mounted noexec.. do workaround
  deploy_command: sh /tmp/.saltcloud/deploy.sh
  script_args: -F
  # grains to add to the minion
  grains:
    clones-are-awesome: true
  # override minion settings
  minion:
    master: 192.168.16.1
    master_port: 5506

The profile can be realized now with a salt command:

salt-cloud -p centos7 my-centos7-clone

This will create an instance named my-centos7-clone on the cloud host. Also the minion id will be set to my-centos7-clone.

If the command was executed on the salt-master, its Salt key will automatically be accepted on the master.

Once the instance has been created with salt-minion installed, connectivity to it can be verified with Salt:

salt my-centos7-clone test.version

Required Settings¶

The following settings are always required for libvirt:

centos7:
  provider: local-kvm
  # the domain to clone
  base_domain: base-centos7-64

SSH Key Authentication¶

Instead of specifying a password, an authorized key can be used for the minion setup. Ensure that the ssh user of your base image has the public key you want to use in ~/.ssh/authorized_keys. If you want to use a non-root user you will likely want to configure salt-cloud to use sudo.

An example using root:

centos7:
  provider: local-kvm
  # the domain to clone
  base_domain: base-centos7-64
  ssh_username: root
  private_key: /path/to/private/key

An example using a non-root user:

centos7:
  provider: local-kvm
  # the domain to clone
  base_domain: base-centos7-64
  ssh_username: centos
  private_key: /path/to/private/key
  sudo: True
  sudo_password: "--redacted--"

Optional Settings¶

centos7:
  # ssh settings
  # use forwarded agent instead of a local key
  ssh_agent: True
  ssh_port: 4910

  # credentials
  ssh_username: root
  # password will be used for sudo if defined, use sudo_password if using ssh keys
  password: my-secret-password
  private_key: /path/to/private/key
  sudo: True
  sudo_password: "--redacted--"

  # bootstrap options
  deploy_command: sh /tmp/.saltcloud/deploy.sh
  script_args: -F

  # minion config
  grains:
    sushi: more tasty
  # point at the another master at another port
  minion:
    master: 192.168.16.1
    master_port: 5506

  # libvirt settings
  # clone_strategy: [ quick | full ] # default is full
  clone_strategy: quick
  # ip_source: [ ip-learning | qemu-agent ] # default is ip-learning
  ip_source: qemu-agent
  # validate_xml: [ false | true ] # default is true
  validate_xml: false

The clone_strategy controls how the clone is done. In case of full the disks are copied creating a standalone clone. If quick is used the disks of the base domain are used as backing disks for the clone. This results in nearly instantaneous clones at the expense of slower write performance. The quick strategy has a number of requirements:

The disks must be of type qcow2
The base domain must be turned off
The base domain must not change after creating the clone

The ip_source setting controls how the IP address of the cloned instance is determined. When using ip-learning the IP is requested from libvirt. This needs a recent libvirt version and may only work for NAT/routed networks where libvirt runs the dhcp server. Another option is to use qemu-agent this requires that the qemu-agent is installed and configured to run at startup in the base domain.

The validate_xml setting is available to disable xml validation by libvirt when cloning.