community.general.lxd_container 模块 – 管理 LXD 实例

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。

要在 playbook 中使用它，请指定：community.general.lxd_container。

概要

• 管理 LXD 容器和虚拟机。

参数

参数	注释
architecture 字符串	实例的架构（例如 x86_64 或 i686）。请参阅 https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get。
client_cert 别名：cert_file 路径	客户端证书文件路径。 如果未指定，则默认为 ${HOME}/.config/lxc/client.crt。
client_key 别名：key_file 路径	客户端证书密钥文件路径。 如果未指定，则默认为 ${HOME}/.config/lxc/client.key。
config 字典	实例的配置（例如 {"limits.cpu": "2"}）。请参阅 https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get。 如果实例已存在，并且从 LXD API 获取的元数据中的“config”值 https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get 不同，则此模块尝试应用配置 https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put。 当 ignore_volatile_options=true 时，以 volatile. 开头的键将在此比较中被忽略。
devices 字典	实例的设备（例如 { "rootfs": { "path": "/dev/kvm", "type": "unix-char" }}）。请参阅 https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get。
ephemeral 布尔值	实例是否为临时的（例如 true 或 false）。请参阅 https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get。 选择 false true
force_stop 布尔值	如果此值为 true，则 lxd_container 会在停止或重启实例时强制停止该实例。 选择 false ←（默认） true
ignore_volatile_options 布尔值 在 community.general 3.7.0 中添加	如果设置为 true，则会忽略以 volatile. 开头的选项。因此，它们将在每次执行时重新应用。 可以通过将此选项设置为 false 来更改此默认行为。 默认值在 community.general 6.0.0 中从 true 更改为 false。 选择 false ←（默认） true
name 字符串 / 必需	实例的名称。
profiles 列表 / 元素=字符串	实例要使用的配置文件。
project 字符串 在 community.general 4.8.0 中添加	实例项目。请参阅https://documentation.ubuntu.com/lxd/en/latest/projects/。
snap_url 字符串	当 LXD 通过 snap 包管理器安装时，Unix 域套接字路径。 默认值： "unix:/var/snap/lxd/common/lxd/unix.socket"
source 字典	实例的来源（例如 { "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/", "protocol": "simplestreams", "alias": "22.04" }）。 有关完整的 API 文档，请参阅 https://documentation.ubuntu.com/lxd/en/latest/api/。 请注意，protocol 接受两个选项：lxd 或 simplestreams。
state 字符串	定义实例的状态。 选择 "started" ←（默认） "stopped" "restarted" "absent" "frozen"
target 字符串 在 community.general 1.0.0 中添加	用于集群部署。将尝试在目标节点上创建实例。如果实例已存在于集群的其他位置，则不会被替换或移动。该名称应与您在 lxc cluster list 中看到的节点名称相同。
timeout 整数	更改实例状态的超时时间。 这也用作等待 IPv4 地址在启动或重启后设置到实例中的所有网络接口的超时时间。 默认值： 30
trust_password 字符串	客户端信任密码。 您需要在运行此模块之前，使用以下命令在 LXD 服务器上设置此密码：lxc config set core.trust_password <some random password>。请参阅 https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/。 如果设置了 trust_password，此模块将在发送任何请求之前发送身份验证请求。
type 字符串 在 community.general 4.1.0 中添加	实例类型可以是 virtual-machine 或 container。 选择 "container" ←（默认） "virtual-machine"
url 字符串	LXD 服务器的 Unix 域套接字路径或 https URL。 默认值： "unix:/var/lib/lxd/unix.socket"
wait_for_container 布尔值 在 community.general 4.4.0 中添加	如果设置为 true，则在执行容器操作时，任务将等待直到任务报告成功状态。 选择 false ←（默认） true
wait_for_ipv4_addresses 布尔值	如果此项为 true，则 lxd_container 将等待，直到 IPv4 地址在启动或重启后设置到实例中的所有网络接口。 选择 false ←（默认） true

属性

属性	支持	描述
check_mode	支持：完整 在 community.general 6.4.0 中添加	可以在 check_mode 中运行并返回已更改状态预测，而无需修改目标。
diff_mode	支持：完整 在 community.general 6.4.0 中添加	在 diff 模式下，将返回已更改（或可能需要在 check_mode 中更改）的详细信息。

注释

注意

• 实例可以是容器或虚拟机，两者都必须具有唯一的名称。如果您尝试创建名称已存在于用户命名空间中的实例，该模块将仅返回为“unchanged”。

• 有两种方法可以在容器或虚拟机内部运行命令，一种是使用 command 模块，另一种是使用 Ansible >= 2.1 中捆绑的 Ansible lxd 连接插件，后者需要在实例中安装 Python，这可以使用 command 模块完成。

• 您可以使用 Ansible ansible.builtin.copy 和 ansible.builtin.template 模块以及 community.general.lxd 连接插件将文件从主机复制到实例。请参阅下面的示例。

• 您可以使用 command=lxc file pull instance_name/dir/filename filename 将创建的实例中的文件复制到本地主机。请参阅下面的第一个示例。

• linuxcontainers.org 已于 2024 年 3 月停止对 LXC/LXD 的支持 (https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)。目前只有 Ubuntu 仍在提供镜像。

示例

# An example for creating a Ubuntu container and install python
- hosts: localhost
  connection: local
  tasks:
    - name: Create a started container
      community.general.lxd_container:
        name: mycontainer
        ignore_volatile_options: true
        state: started
        source:
          type: image
          mode: pull
          server: https://cloud-images.ubuntu.com/releases/
          protocol: simplestreams
          alias: "22.04"
        profiles: ["default"]
        wait_for_ipv4_addresses: true
        timeout: 600

    - name: Check python is installed in container
      delegate_to: mycontainer
      ansible.builtin.raw: dpkg -s python
      register: python_install_check
      failed_when: python_install_check.rc not in [0, 1]
      changed_when: false

    - name: Install python in container
      delegate_to: mycontainer
      ansible.builtin.raw: apt-get install -y python
      when: python_install_check.rc == 1

# An example for creating an Ubuntu 14.04 container using an image fingerprint.
# This requires changing 'server' and 'protocol' key values, replacing the
# 'alias' key with with 'fingerprint' and supplying an appropriate value that
# matches the container image you wish to use.
- hosts: localhost
  connection: local
  tasks:
    - name: Create a started container
      community.general.lxd_container:
        name: mycontainer
        ignore_volatile_options: true
        state: started
        source:
          type: image
          mode: pull
          # Provides current (and older) Ubuntu images with listed fingerprints
          server: https://cloud-images.ubuntu.com/releases
          # Protocol used by 'ubuntu' remote (as shown by 'lxc remote list')
          protocol: simplestreams
          # This provides an Ubuntu 14.04 LTS amd64 image from 20150814.
          fingerprint: e9a8bdfab6dc
        profiles: ["default"]
        wait_for_ipv4_addresses: true
        timeout: 600

# An example of creating a ubuntu-minial container
- hosts: localhost
  connection: local
  tasks:
    - name: Create a started container
      community.general.lxd_container:
        name: mycontainer
        ignore_volatile_options: true
        state: started
        source:
          type: image
          mode: pull
          # Provides Ubuntu minimal images
          server: https://cloud-images.ubuntu.com/minimal/releases/
          protocol: simplestreams
          alias: "22.04"
        profiles: ["default"]
        wait_for_ipv4_addresses: true
        timeout: 600

# An example for creating container in project other than default
- hosts: localhost
  connection: local
  tasks:
    - name: Create a started container in project mytestproject
      community.general.lxd_container:
        name: mycontainer
        project: mytestproject
        ignore_volatile_options: true
        state: started
        source:
          protocol: simplestreams
          type: image
          mode: pull
          server: https://cloud-images.ubuntu.com/releases/
          alias: "22.04"
        profiles: ["default"]
        wait_for_ipv4_addresses: true
        timeout: 600

# An example for deleting a container
- hosts: localhost
  connection: local
  tasks:
    - name: Delete a container
      community.general.lxd_container:
        name: mycontainer
        state: absent
        type: container

# An example for restarting a container
- hosts: localhost
  connection: local
  tasks:
    - name: Restart a container
      community.general.lxd_container:
        name: mycontainer
        state: restarted
        type: container

# An example for restarting a container using https to connect to the LXD server
- hosts: localhost
  connection: local
  tasks:
    - name: Restart a container
      community.general.lxd_container:
        url: https://127.0.0.1:8443
        # These client_cert and client_key values are equal to the default values.
        #client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
        #client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
        trust_password: mypassword
        name: mycontainer
        state: restarted

# Note your container must be in the inventory for the below example.
#
# [containers]
# mycontainer ansible_connection=lxd
#
- hosts:
    - mycontainer
  tasks:
    - name: Copy /etc/hosts in the created container to localhost with name "mycontainer-hosts"
      ansible.builtin.fetch:
        src: /etc/hosts
        dest: /tmp/mycontainer-hosts
        flat: true

# An example for LXD cluster deployments. This example will create two new container on specific
# nodes - 'node01' and 'node02'. In 'target:', 'node01' and 'node02' are names of LXD cluster
# members that LXD cluster recognizes, not ansible inventory names, see: 'lxc cluster list'.
# LXD API calls can be made to any LXD member, in this example, we send API requests to
#'node01.example.com', which matches ansible inventory name.
- hosts: node01.example.com
  tasks:
    - name: Create LXD container
      community.general.lxd_container:
        name: new-container-1
        ignore_volatile_options: true
        state: started
        source:
          type: image
          mode: pull
          alias: "22.04"
        target: node01

    - name: Create container on another node
      community.general.lxd_container:
        name: new-container-2
        ignore_volatile_options: true
        state: started
        source:
          type: image
          mode: pull
          alias: "22.04"
        target: node02

# An example for creating a virtual machine
- hosts: localhost
  connection: local
  tasks:
    - name: Create container on another node
      community.general.lxd_container:
        name: new-vm-1
        type: virtual-machine
        state: started
        ignore_volatile_options: true
        wait_for_ipv4_addresses: true
        profiles: ["default"]
        source:
          protocol: simplestreams
          type: image
          mode: pull
          server: [...] # URL to the image server
          alias: debian/11
        timeout: 600

返回值

常见的返回值记录在此处，以下是此模块特有的字段

键	描述
actions 列表 / 元素=字符串	为实例执行的操作列表。 返回： 成功 示例： ["create", "start"]
addresses 字典	从网络设备名称到实例中 IPv4 地址列表的映射。 返回： 当状态为启动或重启时 示例： {"eth0": ["10.155.92.191"]}
logs 列表 / 元素=字符串	请求和响应的日志。 返回： 当使用 -vvvv 调用 ansible-playbook 时。 示例： ["(too long to be placed here)"]
old_state 字符串	实例的旧状态。 返回： 当状态为启动或重启时 示例： "stopped"

作者

• Hiroaki Nakamura (@hnakamur)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助
• 提交错误报告
• 请求功能
• 通信