Documentation

lxc_container - Manage LXC Containers

New in version 1.8.0.

Synopsis

  • Management of LXC containers

Requirements (on host that executes module)

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 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”.
                                  • 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.

                                  Support

                                  This module is community maintained without core committer oversight.

                                  For more information on what this means please read Module Support

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