/ home / ansible / ansible.builtin / v2.9.27 / module / lxc_container

ansible.builtin.lxc_container (v2.9.27) — module

Manage LXC Containers

| "added in version" 1.8.0 of ansible.builtin"

Authors: Kevin Carter (@cloudnull)

preview | supported by community

Install Ansible via `pip`

Install with pip install ansible==2.9.27

Description

Management of LXC containers

Requirements

lxc >= 1.0 # OS package
python >= 2.6 # OS Package
lxc-python2 >= 0.1 # PIP Package from https://github.com/lxc/python2-lxc

Usage examples

Scanned by Steampunk Spotter

- name: Create a started container
  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
  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
  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
  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
  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"
  debug:
    var: lvm_container_info

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- name: Start a container
  lxc_container:
    name: test-container-stopped
    state: started

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

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
  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
  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"
  debug:
    var: clone_container_info

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

- 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

Inputs

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

state:
    choices:
    - started
    - stopped
    - restarted
    - absent
    - frozen
    default: started
    description:
    - 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.

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

archive:
    choices:
    - true
    - false
    default: 'no'
    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.

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

lv_name:
    default: $CONTAINER_NAME
    description:
    - Name of the logical volume, defaults to the container name.

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

lxc_path:
    description:
    - Place container under PATH

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

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

zfs_root:
    description:
    - Create zfs under given zfsroot.

directory:
    description:
    - Place rootfs directory under DIR.

clone_name:
    description:
    - Name of the new cloned server. This is only used when state is clone.
    type: str
    version_added: '2.0'
    version_added_collection: ansible.builtin

archive_path:
    description:
    - 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
    default: dir
    description:
    - Backend storage type for the container.

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

clone_snapshot:
    choices:
    - true
    - false
    default: 'no'
    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
    version_added: '2.0'
    version_added_collection: ansible.builtin

container_config:
    description:
    - list of 'key=value' options to use when configuring a container.

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

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

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

container_log_level:
    choices:
    - INFO
    - ERROR
    - DEBUG
    default: INFO
    description:
    - Set the log level for a container where *container_log* was set.
    required: false

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

Install Ansible via pip

Description

Requirements

Usage examples

Inputs

Outputs

Install Ansible via `pip`