lxc_container - Manage LXC Containers
New in version 1.8.0.
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 |
|
Create an archive of a container. This will create a tarball of the running container. | |
| archive_compression |
no | gzip |
|
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 |
|
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 |
|
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 |
|
Enable a container log for host actions to the container. | |
| container_log_level |
no | INFO |
|
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 |
|
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 Common Return Values, the following are the fields unique to this module:
| name | description | returned | type | sample |
|---|---|---|---|---|
| lxc_container | container information | success | list |
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”.
Note
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.
Note
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.
Note
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.
This is an Extras Module
For more information on what this means please read Extras Modules
For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.