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 容器和虚拟机的管理。

参数

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

属性

属性	支持	描述
check_mode	支持：完全支持 在 community.general 6.4.0 中添加	可以在 check_mode 下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：完全支持 在 community.general 6.4.0 中添加	在差异模式下，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息。

备注

注意

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

• 有两种方法可以在容器或虚拟机内部运行命令：使用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地址列表的映射。 返回：当状态为started或restarted时 示例： {"eth0": ["10.155.92.191"]}
logs 列表 / 元素=字符串	请求和响应的日志。 返回：当使用 -vvvv 调用 ansible-playbook 时。 示例： ["(此处内容过长)"]
old_state 字符串	实例的旧状态。 返回：当状态为started或restarted时 示例： "stopped"

作者

• 中村弘明 (@hnakamur)

集合链接

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