lxc_container - Manage LXC Containers
New in version 1.8.0.
Synopsis
- Management of LXC containers
Requirements
The below requirements are needed on the host that executes this module.
- lxc >= 1.0 # OS package
- python >= 2.6 # OS Package
- lxc-python2 >= 0.1 # PIP Package from https://github.com/lxc/python2-lxc
Parameters
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| archive
bool
|
|
Create an archive of a container. This will create a tarball of the running container.
|
| archive_compression |
|
Type of compression to use when creating an archive of a running container.
|
| archive_path |
Path the save the archived container. If the path does not exist the archive method will attempt to create it.
|
|
| backing_store |
|
Backend storage type for the container.
|
| clone_name
bool
(added in 2.0)
|
|
Name of the new cloned server. This is only used when state is clone.
|
| clone_snapshot
bool
(added in 2.0)
|
|
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 |
Path to the LXC configuration file.
|
|
| container_command |
Run a command within a container.
|
|
| container_config |
list of 'key=value' options to use when configuring a container.
|
|
| container_log
bool
|
|
Enable a container log for host actions to the container.
|
| container_log_level |
|
Set the log level for a container where *container_log* was set.
|
| directory |
Place rootfs directory under DIR.
|
|
| fs_size | Default:
"5G"
|
File system Size.
|
| fs_type | Default:
"ext4"
|
Create fstype TYPE.
|
| lv_name | Default:
"$CONTAINER_NAME"
|
Name of the logical volume, defaults to the container name.
|
| lxc_path |
Place container under PATH
|
|
| name
required
|
Name of a container.
|
|
| state |
|
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 | Default:
"ubuntu"
|
Name of the template to use within an LXC create.
|
| template_options |
Template options when building the container.
|
|
| thinpool |
Use LVM thin pool called TP.
|
|
| vg_name | Default:
"lxc"
|
If Backend store is lvm, specify the name of the volume group.
|
| zfs_root |
Create zfs under given zfsroot.
|
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.
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, the following are the fields unique to this module:
| Key | Returned | Description | |
|---|---|---|---|
| lxc_container
complex
|
success |
container information
|
|
| name
string
|
success |
name of the lxc container
Sample:
test_host
|
|
| init_pid
int
|
success |
pid of the lxc init process
Sample:
19786
|
|
| interfaces
list
|
success |
list of the container's network interfaces
Sample:
['eth0', 'lo']
|
|
| ips
list
|
success |
list of ips
Sample:
['10.0.3.3']
|
|
| state
string
|
success |
resulting state of the container
Sample:
running
|
|
| archive
string
|
success, when archive is true |
resulting state of the container
Sample:
/tmp/test-container-config.tar
|
|
| clone
boolean
|
success, when clone_name is specified |
if the container was cloned
Sample:
True
|
|
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Maintenance
This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.
For a list of other modules that are also maintained by the Ansible Community, see here.
Author
- Kevin Carter (@cloudnull)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.6/modules/lxc_container_module.html