# 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.

See also `salt.cloud.clouds.libvirt`