community.general.lxc_container module – Manage LXC Containers
Note
This module is part of the community.general collection (version 5.8.3).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.lxc_container
.
Synopsis
Management of LXC containers.
Requirements
The below requirements are needed on the host that executes this module.
lxc >= 2.0 # OS package
python3 >= 3.5 # OS Package
python3-lxc # OS Package
Parameters
Parameter |
Comments |
---|---|
Create an archive of a container. This will create a tarball of the running container. Choices:
|
|
Type of compression to use when creating an archive of a running container. Choices:
|
|
Path the save the archived container. If the path does not exist the archive method will attempt to create it. |
|
Backend storage type for the container. Choices:
|
|
Name of the new cloned server. This is only used when state is clone. |
|
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. Choices:
|
|
Path to the LXC configuration file. |
|
Run a command within a container. |
|
A list of |
|
Enable a container log for host actions to the container. Choices:
|
|
Set the log level for a container where container_log was set. Choices:
|
|
Place rootfs directory under DIR. |
|
File system Size. Default: |
|
Create fstype TYPE. Default: |
|
Name of the logical volume, defaults to the container name. If not specified, it defaults to |
|
Place container under |
|
Name of a container. |
|
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. Choices:
|
|
Name of the template to use within an LXC create. Default: |
|
Template options when building the container. |
|
Use LVM thin pool called TP. |
|
If backend store is lvm, specify the name of the volume group. Default: |
|
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 statestopped
the container will bestarted
, the command executed, and then the containerstopped
again. Likewise if state=stopped and the container does not exist it will be first created,started
, the command executed, and thenstopped
. If you use a “|” in the variable you can use common script formatting within the variable itself. The container_command option will always execute as BASH. When using container_command, a log file is created in the/tmp/
directory which contains bothstdout
andstderr
of any command executed.If archive=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
python3-lxc
, which is a requirement for this module, it can be installed from source at https://github.com/lxc/python3-lxc or installed via pip using the package namelxc
.
Examples
- name: Create a started container
community.general.lxc_container:
name: test-container-started
container_log: true
template: ubuntu
state: started
template_options: --release trusty
- name: Create a stopped container
community.general.lxc_container:
name: test-container-stopped
container_log: true
template: ubuntu
state: stopped
template_options: --release trusty
- name: Create a frozen container
community.general.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
community.general.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
community.general.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"
ansible.builtin.debug:
var: lvm_container_info
- name: Run a command in a container and ensure its in a "stopped" state.
community.general.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.
community.general.lxc_container:
name: test-container-stopped
state: frozen
container_command: |
echo 'hello world.' | tee /opt/frozen
- name: Start a container
community.general.lxc_container:
name: test-container-stopped
state: started
- name: Run a command in a container and then restart it
community.general.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
community.general.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
community.general.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
community.general.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"
ansible.builtin.debug:
var: clone_container_info
- name: Clone a container using snapshot
community.general.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
community.general.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
community.general.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.
community.general.lxc_container:
name: test-container-new-archive-destroyed-clone
state: started
- name: Destroy a container
community.general.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 |
Description |
---|---|
container information Returned: success |
|
resulting state of the container Returned: success, when archive is true Sample: |
|
if the container was cloned Returned: success, when clone_name is specified Sample: |
|
pid of the lxc init process Returned: success Sample: |
|
list of the container’s network interfaces Returned: success Sample: |
|
list of ips Returned: success Sample: |
|
name of the lxc container Returned: success Sample: |
|
resulting state of the container Returned: success Sample: |
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication