lxc_container - Manage LXC Containers

New in version 1.8.0.

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status

Synopsis

Management of LXC containers

Requirements (on host that executes module)

lxc >= 1.0 # OS package
python >= 2.6 # OS Package
lxc-python2 >= 0.1 # PIP Package from https://github.com/lxc/python2-lxc

Options

parameter	required	default	choices	comments
archive	no		True False	Create an archive of a container. This will create a tarball of the running container.
archive_compression	no	gzip	gzip bzip2 none	Type of compression to use when creating an archive of a running container.
archive_path	no			Path the save the archived container. If the path does not exist the archive method will attempt to create it.
backing_store	no	dir	dir lvm loop btrfs overlayfs zfs	Backend storage type for the container.
clone_name (added in 2.0)	no			Name of the new cloned server. This is only used when state is clone.
clone_snapshot (added in 2.0)	no		True False	Create a snapshot a container when cloning. This is not supported by all container storage backends. Enabling this may fail if the backing store does not support snapshots.
config	no			Path to the LXC configuration file.
container_command	no			Run a command within a container.
container_config	no			list of 'key=value' options to use when configuring a container.
container_log	no		True False	Enable a container log for host actions to the container.
container_log_level	no	INFO	INFO ERROR DEBUG	Set the log level for a container where container_log was set.
directory	no			Place rootfs directory under DIR.
fs_size	no	5G		File system Size.
fs_type	no	ext4		Create fstype TYPE.
lv_name	no	$CONTAINER_NAME		Name of the logical volume, defaults to the container name.
lxc_path	no			Place container under PATH
name	yes			Name of a container.
state	no	started	started stopped restarted absent frozen	Define the state of a container. If you clone a container using `clone_name` the newly cloned container created in a stopped state. The running container will be stopped while the clone operation is happening and upon completion of the clone the original container state will be restored.
template	no	ubuntu		Name of the template to use within an LXC create.
template_options	no			Template options when building the container.
thinpool	no			Use LVM thin pool called TP.
vg_name	no	lxc		If Backend store is lvm, specify the name of the volume group.
zfs_root	no			Create zfs under given zfsroot.

Examples

- name: Create a started container
  lxc_container:
    name: test-container-started
    container_log: true
    template: ubuntu
    state: started
    template_options: --release trusty

- name: Create a stopped container
  lxc_container:
    name: test-container-stopped
    container_log: true
    template: ubuntu
    state: stopped
    template_options: --release trusty

- name: Create a frozen container
  lxc_container:
    name: test-container-frozen
    container_log: true
    template: ubuntu
    state: frozen
    template_options: --release trusty
    container_command: |
      echo 'hello world.' | tee /opt/started-frozen

# Create filesystem container, configure it, and archive it, and start it.
- name: Create filesystem container
  lxc_container:
    name: test-container-config
    backing_store: dir
    container_log: true
    template: ubuntu
    state: started
    archive: true
    archive_compression: none
    container_config:
      - "lxc.aa_profile=unconfined"
      - "lxc.cgroup.devices.allow=a *:* rmw"
    template_options: --release trusty

# Create an lvm container, run a complex command in it, add additional
# configuration to it, create an archive of it, and finally leave the container
# in a frozen state. The container archive will be compressed using bzip2
- name: Create a frozen lvm container
  lxc_container:
    name: test-container-lvm
    container_log: true
    template: ubuntu
    state: frozen
    backing_store: lvm
    template_options: --release trusty
    container_command: |
      apt-get update
      apt-get install -y vim lxc-dev
      echo 'hello world.' | tee /opt/started
      if [[ -f "/opt/started" ]]; then
          echo 'hello world.' | tee /opt/found-started
      fi
    container_config:
      - "lxc.aa_profile=unconfined"
      - "lxc.cgroup.devices.allow=a *:* rmw"
    archive: true
    archive_compression: bzip2
  register: lvm_container_info

- name: Debug info on container "test-container-lvm"
  debug:
    var: lvm_container_info

- name: Run a command in a container and ensure its in a "stopped" state.
  lxc_container:
    name: test-container-started
    state: stopped
    container_command: |
      echo 'hello world.' | tee /opt/stopped

- name: Run a command in a container and ensure its it in a "frozen" state.
  lxc_container:
    name: test-container-stopped
    state: frozen
    container_command: |
      echo 'hello world.' | tee /opt/frozen

- name: Start a container
  lxc_container:
    name: test-container-stopped
    state: started

- name: Run a command in a container and then restart it
  lxc_container:
    name: test-container-started
    state: restarted
    container_command: |
      echo 'hello world.' | tee /opt/restarted

- name: Run a complex command within a "running" container
  lxc_container:
    name: test-container-started
    container_command: |
      apt-get update
      apt-get install -y curl wget vim apache2
      echo 'hello world.' | tee /opt/started
      if [[ -f "/opt/started" ]]; then
          echo 'hello world.' | tee /opt/found-started
      fi

# Create an archive of an existing container, save the archive to a defined
# path and then destroy it.
- name: Archive container
  lxc_container:
    name: test-container-started
    state: absent
    archive: true
    archive_path: /opt/archives

# Create a container using overlayfs, create an archive of it, create a
# snapshot clone of the container and and finally leave the container
# in a frozen state. The container archive will be compressed using gzip.
- name: Create an overlayfs container archive and clone it
  lxc_container:
    name: test-container-overlayfs
    container_log: true
    template: ubuntu
    state: started
    backing_store: overlayfs
    template_options: --release trusty
    clone_snapshot: true
    clone_name: test-container-overlayfs-clone-snapshot
    archive: true
    archive_compression: gzip
  register: clone_container_info

- name: debug info on container "test-container"
  debug:
    var: clone_container_info

- name: Clone a container using snapshot
  lxc_container:
    name: test-container-overlayfs-clone-snapshot
    backing_store: overlayfs
    clone_name: test-container-overlayfs-clone-snapshot2
    clone_snapshot: true

- name: Create a new container and clone it
  lxc_container:
    name: test-container-new-archive
    backing_store: dir
    clone_name: test-container-new-archive-clone

- name: Archive and clone a container then destroy it
  lxc_container:
    name: test-container-new-archive
    state: absent
    clone_name: test-container-new-archive-destroyed-clone
    archive: true
    archive_compression: gzip

- name: Start a cloned container.
  lxc_container:
    name: test-container-new-archive-destroyed-clone
    state: started

- name: Destroy a container
  lxc_container:
    name: '{{ item }}'
    state: absent
  with_items:
    - test-container-stopped
    - test-container-started
    - test-container-frozen
    - test-container-lvm
    - test-container-config
    - test-container-overlayfs
    - test-container-overlayfs-clone
    - test-container-overlayfs-clone-snapshot
    - test-container-overlayfs-clone-snapshot2
    - test-container-new-archive
    - test-container-new-archive-clone
    - test-container-new-archive-destroyed-clone

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name

description

returned

type

sample

lxc_container

container information

success

complex

contains:

name	description	returned	type	sample
ips	list of ips	success	list	['10.0.3.3']
state	resulting state of the container	success	string	running
name	name of the lxc container	success	string	test_host
init_pid	pid of the lxc init process	success	int	19786
clone	if the container was cloned	success, when clone_name is specified	boolean	True
interfaces	list of the container's network interfaces	success	list	['eth0', 'lo']
archive	resulting state of the container	success, when archive is true	string	/tmp/test-container-config.tar

Notes

Note

Containers must have a unique name. If you attempt to create a container with a name that already exists in the users namespace the module will simply return as “unchanged”.
The “container_command” can be used with any state except “absent”. If used with state “stopped” the container will be “started”, the command executed, and then the container “stopped” again. Likewise if the state is “stopped” and the container does not exist it will be first created, “started”, the command executed, and then “stopped”. If you use a “|” in the variable you can use common script formatting within the variable iteself The “container_command” option will always execute as BASH. When using “container_command” a log file is created in the /tmp/ directory which contains both stdout and stderr of any command executed.
If “archive” is true the system will attempt to create a compressed tarball of the running container. The “archive” option supports LVM backed containers and will create a snapshot of the running container when creating the archive.
If your distro does not have a package for “python2-lxc”, which is a requirement for this module, it can be installed from source at “https://github.com/lxc/python2-lxc” or installed via pip using the package name lxc-python2.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/lxc_container_module.html