- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# lxc_container – Manage LXC Containers

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## 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 boolean | Choices: no ← yes | Create an archive of a container. This will create a tarball of the running container.
archive_compression - | Choices: gzip ← bzip2 none | 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 - | Choices: dir ← lvm loop btrfs overlayfs zfs | Backend storage type for the container.
clone_name string |  | Name of the new cloned server. This is only used when state is clone.
clone_snapshot boolean | Choices: no ← yes | 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 boolean | Choices: no ← yes | Enable a container log for host actions to the container.
container_log_level - | Choices: INFO ← ERROR DEBUG | 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 - | Choices: 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 - | 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 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 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
| 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
| init_pid integer | 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']
| name string | success | name of the lxc container Sample: test_host
| state string | success | resulting state of the container Sample: running

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Kevin Carter (@cloudnull)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.