lxc

Table of Contents

1. Overview
2. Module Description
3. Reference
4. Usage
5. NOTES
6. TODO
7. Limitations - OS compatibility, etc.
8. Contributions

Overview

Manages the state of LXC based containers on a Ubuntu host.

Module Description

This module installs LXC tools, LXC Ruby bindings, manages LXC service and configures
LXC networking settings. The lxc module adds the following resources to Puppet:

• lxc
• lxc_interface
• lxc_cgroups

For more information about LXC visit: linuxcontainers.org.

Reference

Classes

Public Classes

• lxc: Main class, provides logic and public interface with the following parameters:

• lxc_ruby_bindings_provider
  Provider used to install LXC ruby bindings. Defaults to gem.

• lxc_ruby_bindings_package
  Name for the LXC ruby bindings. Defaults to ruby-lxc.

• lxc_ruby_bindings_gem_deps
  Name for the LXC ruby bindings gem dependencies. Defaults are distribution and release specific.

• lxc_ruby_bindings_version
  Version for LXC ruby bindings. Defaults to 1.2.0.

• lxc_lxc_package
  Package for installing lxc tools and libraries. Defaults to lxc.

• lxc_lxc_version
  Version for $lxc_lxc_package. Defaults to latest.

• lxc_lxc_service
  Name for lxc service. Defaults to lxc.

• lxc_lxc_service_ensure
  Defines state for LXC service. Defaults to running.

• lxc_lxc_service_enabled
  Enables/disables LXC service on boot time. Defaults to true.

• lxc_networking_container_ensure
  Whether configuration is present or absent. Default is present.

• lxc_networking_device_link
  Host device to be used as link, i.e. lxcbr0.

• lxc_networking_type
  The networking type containers will use by default, i.e. veth.

• lxc_networking_flags
  Networking flags, up activates the interface. Defaults to 'up'.

• lxc_networking_hwaddr
  The parameter controls a fixed part of the MAC address, to randomly generate
  containers new MACs. Defaults to '00:16:3e:xx:xx:xx'.

• lxc_networking_nat_bridge
  Bridge to be used as link device for containers. Default is 'lxcbr0'.

• lxc_networking_nat_address
  Address for the bridge. Default '10.0.3.1'.

• lxc_networking_nat_mask
  Mask address for the bridge. Default '255.255.255.0'.

• lxc_networking_nat_network
  Network address for the bridge. Default '10.0.3.0/24'.

• lxc_networking_nat_dhcp_range
  DHCP range, comman-separated. Default '10.0.3.2,10.0.3.254'.

• lxc_networking_nat_max_hosts
  Maximum number of hosts to be assigned by the DHCP server. Default 253.

• lxc_networking_nat_dns_domain
  DNS domain to be assigned by the DHCP server. Default undef.

• lxc_networking_nat_dhcp_conf
  Configuration file to be used for LXC's DHCP server. Default undef.

• lxc_networking_nat_dhcp_options
  A hash with DHCP specific options, it will be used to create
  the file pointed by $networking_nat_dhcp_conf. The end result
  will be in the format key=value. Default undef.

• lxc_networking_nat_update_dnsmasq
  Whether to update system-wide dnsmasq instance to avoid it binding
  on $lxc_networking_nat_bridge. Default false.

• lxc_networking_nat_dnsmasq_conf
  System-wide dnsmasq configuration file, where except-interface setting
  will be modified with $lxc_networking_nat_bridge value. Default
  /etc/dnsmasq.d/lxc.

• lxc::install: This class manages the installation of lxc tools, bindings and dependencies.

• lxc::service: This class manages LXC service state.

• lxc::networking::containers: This class manages the default networking settings for containers.

• lxc::networking::nat: This class manages the host networking settings to create a Nat'ed bridge.

Resources

lxc

• Defines the container itself, allows the following parameters/properties:
  • name: container's name.
  • template: template to be used during container creation. Default 'ubuntu'.
  • template_options: array with template's extra options. User must make sure they are valid.
  • timeout: timeout (in seconds) to wait for container opertions to complete. Default 10s.
  • storage_backend: dir, lvm, btrfs, loop or best. Default 'dir'.
  • storage_options: options to be passed to the chosen storage backend.
  • state: running, stopped or frozen. Default running.
  • restart: whether to restart the container after applying network configuration. Default false.
  • autostart: enable/disable starting the container at boot time. Default false.
  • autostart_delay: time to wait before starting next container.
  • autostart_order: position on which the container will be started.
  • groups: array with all the container's groups.

lxc_interface

• Defines network interfaces and allows the following paramters/properties:
  • name: Just a name...(public, private, ...)
  • container: container's name.
  • index: index number for the interface.
  • device_name: eth0, eth1, ...
  • veth_name_host: name of the veth pair device on the host (e.g. containername-eth0)
  • link: host interface where to link the container interface.
  • vlan_id: VLAN ID.
  • macvlan_mode: private, vepa or bridge.
  • type: defaults to veth.
  • ipv4: IPv4 address (can be string or array).
  • ipv4_gateway: container's default gateway.
  • hwaddr: MAC.
  • restart: whether to restart the container after applying configuration.

lxc_cgroups

• Defines cgroup values and allows the following parameters/properties:
  • name: The actual control file, i.e. 'memory.limit_in_bytes'.
  • container: container's name.
  • value: desired value for the control file.

Usage

# lxc class defining NAT'ed network.
class { 'lxc':
  lxc_networking_nat_address        => '10.0.4.1',
  lxc_networking_nat_mask           => '255.255.255.0',
  lxc_networking_nat_network        => '10.0.4.0/24',
  lxc_networking_nat_dhcp_range     => '10.0.4.2,10.0.4.254',
}


# Create ubuntu_test container based on ubuntu template, set its state to
# running, using as storage the VG vg00 and LV ubuntu_test01.
lxc { 'ubuntu_test':
  ensure           => present,
  state            => running,
  autostart        => true,
  template         => 'ubuntu',
  template_options => ['--mirror','http://de.archive.ubuntu.com/ubuntu'],
  storage_backend  => 'lvm',
  storage_options  => {'vgname' => 'vg00', 'lvname' => 'ubuntu_test01'},
}

# Will configure eth1 on container 'ubuntu_test', with two different IP addresses
lxc_interface { 'public':
  ensure       => present,
  device_name  => 'eth0',
  container    => 'ubuntu_test',
  index        => 0,
  link         => 'lxcbr0',
  type         => 'veth',
  ipv4         => '10.0.3.2/24',
  ipv4_gateway => '10.0.3.1',
  restart      => true,
}

lxc_interface { 'private':
  device_name => 'eth1',
  ensure      => present,
  container   => 'ubuntu_test',
  index       => 1,
  link        => 'lxcbr1',
  type        => 'veth',
  ipv4        => ['192.168.200.5/16','192.168.100.10/24'],
  restart     => true,
}

lxc_cgroups { 'memory.limit_in_bytes':
  container => 'ubuntu_test',
  value     => '1073741824',
}

NOTES

• All the networking settings in lxc_interface are only applied/checked to/from the
  container's configuration file, for them to take effect the container must be restarted
  (stopped/started), use restart => true if that's what you need.

TODO

• Add support for current CentOS releases.
• Improve lxc-cgroup provider.
• Get rid of duplications.

Limitations

• The module lxc only works for Ubuntu 14.04, on other platforms with Ruby LXC
  bindings installed, the types should work as expected.
• The lxc_cgroups provider is really basic, doesn't do much validation and currently it's
  not ensurable, as it seems not everything inside cgroups has a reset value. So,
  this provider only sets the given value in the given cgroup key.
• lxc_groups provider is not able to use values such as 1G, cause when comparing, liblxc
  returns the values in bytes and puppet will set the value again.

Contributions

Any contribution will be more than welcomed, specially in tests and Ruby parts,
I've tried to do my best, but it's far from perfect.

From version 0.2.0, a development branch is included in module's repository and all the
contributions should be made against it.

If a new feature is added, please, write the tests for it.