/ home / community / community.general / 8.5.0 / module / lxc_container

community.general.lxc_container (8.5.0) — module

Manage LXC Containers

Authors: Kevin Carter (@cloudnull)

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

Management of LXC containers.

Requirements

lxc >= 2.0 # OS package
python3 >= 3.5 # OS Package
python3-lxc # OS Package

Usage examples

Scanned by Steampunk Spotter

- name: Create a started container
  community.general.lxc_container:
    name: test-container-started
    container_log: true
    template: ubuntu
    state: started
    template_options: --release trusty

Scanned by Steampunk Spotter

- name: Create a stopped container
  community.general.lxc_container:
    name: test-container-stopped
    container_log: true
    template: ubuntu
    state: stopped
    template_options: --release trusty

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

# 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

Scanned by Steampunk Spotter

# 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

Scanned by Steampunk Spotter

- name: Debug info on container "test-container-lvm"
  ansible.builtin.debug:
    var: lvm_container_info

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- name: Start a container
  community.general.lxc_container:
    name: test-container-stopped
    state: started

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

# 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

Scanned by Steampunk Spotter

# 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

Scanned by Steampunk Spotter

- name: Debug info on container "test-container"
  ansible.builtin.debug:
    var: clone_container_info

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- name: Start a cloned container.
  community.general.lxc_container:
    name: test-container-new-archive-destroyed-clone
    state: started

Scanned by Steampunk Spotter

- 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

Inputs

    
name:
    description:
    - Name of a container.
    required: true
    type: str

state:
    choices:
    - started
    - stopped
    - restarted
    - absent
    - frozen
    - clone
    default: started
    description:
    - Define the state of a container.
    - If you clone a container using O(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.
    type: str

config:
    description:
    - Path to the LXC configuration file.
    type: path

archive:
    default: false
    description:
    - Create an archive of a container.
    - This will create a tarball of the running container.
    type: bool

fs_size:
    default: 5G
    description:
    - File system Size.
    type: str

fs_type:
    default: ext4
    description:
    - Create fstype TYPE.
    type: str

lv_name:
    description:
    - Name of the logical volume, defaults to the container name.
    - If not specified, it defaults to C($CONTAINER_NAME).
    type: str

vg_name:
    default: lxc
    description:
    - If backend store is lvm, specify the name of the volume group.
    type: str

lxc_path:
    description:
    - Place container under E(PATH).
    type: path

template:
    default: ubuntu
    description:
    - Name of the template to use within an LXC create.
    type: str

thinpool:
    description:
    - Use LVM thin pool called TP.
    type: str

zfs_root:
    description:
    - Create zfs under given zfsroot.
    type: str

directory:
    description:
    - Place rootfs directory under DIR.
    type: path

clone_name:
    description:
    - Name of the new cloned server.
    - This is only used when state is clone.
    type: str

archive_path:
    description:
    - Path the save the archived container.
    - If the path does not exist the archive method will attempt to create it.
    type: path

backing_store:
    choices:
    - dir
    - lvm
    - loop
    - btrfs
    - overlayfs
    - zfs
    default: dir
    description:
    - Backend storage type for the container.
    type: str

container_log:
    default: false
    description:
    - Enable a container log for host actions to the container.
    type: bool

clone_snapshot:
    default: false
    description:
    - 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.
    type: bool

container_config:
    description:
    - A list of C(key=value) options to use when configuring a container.
    elements: str
    type: list

template_options:
    description:
    - Template options when building the container.
    type: str

container_command:
    description:
    - Run a command within a container.
    type: str

archive_compression:
    choices:
    - gzip
    - bzip2
    - none
    default: gzip
    description:
    - Type of compression to use when creating an archive of a running container.
    type: str

container_log_level:
    choices:
    - Info
    - info
    - INFO
    - Error
    - error
    - ERROR
    - Debug
    - debug
    - DEBUG
    default: INFO
    description:
    - Set the log level for a container where O(container_log) was set.
    required: false
    type: str

Outputs

lxc_container:
  contains:
    archive:
      description: resulting state of the container
      returned: success, when archive is true
      sample: /tmp/test-container-config.tar
      type: str
    clone:
      description: if the container was cloned
      returned: success, when clone_name is specified
      sample: true
      type: bool
    init_pid:
      description: pid of the lxc init process
      returned: success
      sample: 19786
      type: int
    interfaces:
      description: list of the container's network interfaces
      returned: success
      sample:
      - eth0
      - lo
      type: list
    ips:
      description: list of ips
      returned: success
      sample:
      - 10.0.3.3
      type: list
    name:
      description: name of the lxc container
      returned: success
      sample: test_host
      type: str
    state:
      description: resulting state of the container
      returned: success
      sample: running
      type: str
  description: container information
  returned: success
  type: complex