ansible.builtin.apt 模块 – 管理 apt 包

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，您也可以使用简短的模块名称 apt。但是，我们建议您使用完全限定的集合名称 (FQCN) ansible.builtin.apt，以便轻松链接到模块文档，并避免与其他可能具有相同模块名称的集合冲突。

概要 

管理 apt 包（例如 Debian/Ubuntu）。

要求 

以下要求需要在执行此模块的主机上满足。

python3-apt
aptitude (2.4 之前)

参数 

参数	注释
allow_change_held_packages boolean 在 ansible-core 2.13 中添加	允许更改 apt hold 列表中软件包的版本。选项 `false` ← (默认) `true`
allow_downgrade 别名: allow-downgrade, allow_downgrades, allow-downgrades boolean 在 ansible-core 2.12 中添加	对应于 apt 的 `--allow-downgrades` 选项。此选项使指定的软件包和版本能够替换已安装的该软件包的更高版本。请注意，设置 `allow_downgrade=true` 可能会使此模块以非幂等的方式运行。（任务最终可能得到一组与要安装的指定软件包的完整列表不匹配的软件包）。 `allow_downgrade` 仅受 `apt` 支持，如果检测到或指定了 `aptitude`，则将被忽略。选项 `false` ← (默认) `true`
allow_unauthenticated 别名：allow-unauthenticated boolean	忽略无法验证身份的软件包。这对于管理自己的 apt-key 设置的引导环境非常有用。 `allow_unauthenticated` 仅在 `state` 为：`install`/`present` 时受支持。选项 `false` ← (默认) `true`
auto_install_module_deps boolean 在 ansible-core 2.19 中添加	自动安装运行此模块所需的依赖项。选项 `false` `true` ← (默认)
autoclean boolean	如果为 `true`，则清除本地存储库中无法再下载的已检索软件包文件。选项 `false` ← (默认) `true`
autoremove boolean	如果为 `true`，则删除所有模块状态（`build-dep` 除外）的未使用依赖包。它也可以作为唯一选项使用。在 2.4 版本之前，`autoclean` 也是 `autoremove` 的别名，现在它是单独的命令。有关更多信息，请参阅文档。选项 `false` ← (默认) `true`
cache_valid_time integer	如果 apt 缓存的时间早于 `cache_valid_time`，则更新 apt 缓存。此选项以秒为单位设置。从 Ansible 2.4 开始，如果显式设置，则将设置 `update_cache=yes`。默认: `0`
clean boolean 在 ansible-core 2.13 中添加	运行等效于 `apt-get clean` 的命令，以清除本地存储库中已检索的软件包文件。它会删除 `/var/cache/apt/archives/` 和 `/var/cache/apt/archives/partial/` 中的所有内容，但锁定文件除外。可以作为软件包安装的一部分运行（clean 在安装之前运行），也可以作为单独的步骤运行。选项 `false` ← (默认) `true`
deb path	远程计算机上 .deb 包的路径。如果路径中包含 `://`，ansible 将尝试在安装前下载 deb。（版本添加于 2.1）需要 `xz-utils` 包来提取要安装的 deb 包的控制文件。
default_release 别名: default-release string	对应于 apt 的 `-t` 选项，并设置 pin 优先级。
dpkg_options string	将 `dpkg` 选项添加到 `apt` 命令。默认为 `-o "Dpkg::Options::=--force-confdef" -o "Dpkg::Options::=--force-confold"`。选项应以逗号分隔列表的形式提供。默认: `"force-confdef,force-confold"`
fail_on_autoremove boolean 在 ansible-core 2.11 中添加	对应于 `apt` 的 `--no-remove` 选项。如果为 `true`，则确保不会删除任何软件包，否则任务将失败。 `fail_on_autoremove` 仅在 `state` 不为 `absent` 时受支持。 `fail_on_autoremove` 仅受 `apt` 支持，如果检测到或指定了 `aptitude`，则将被忽略。选项 `false` ← (默认) `true`
force boolean	对应于 `apt-get` 的 `--force-yes`，并暗示 `allow_unauthenticated=yes` 和 `allow_downgrade=yes`。此选项将禁用对软件包签名和下载它们的 Web 服务器证书的检查。此选项不等同于在命令行上传递 `-f` 标志给 `apt-get`。这是一个具有破坏性的操作，可能会破坏您的系统，几乎不应该使用它。另请参阅 `man apt-get` 以获取更多信息。选项 `false` ← (默认) `true`
force_apt_get boolean	强制使用 apt-get 而不是 aptitude。选项 `false` ← (默认) `true`
install_recommends 别名: install-recommends boolean	对应于 `apt` 的 `--no-install-recommends` 选项。`true` 安装推荐的软件包。`false` 不安装推荐的软件包。默认情况下，Ansible 将使用与操作系统相同的默认值。永远不会安装建议的软件包。选项 `false` `true`
lock_timeout integer 在 ansible-core 2.12 中添加	此操作将等待多少秒来获取 apt 数据库的锁。有时会出现瞬时锁，此操作将至少重试到超时为止。默认值： `60`
name 别名：package, pkg 列表 / 元素=字符串	软件包名称列表，例如 `foo`，或者带有版本的软件包指定符，例如 `foo=1.0` 或 `foo>=1.0`。也支持名称通配符（fnmatch），例如 `apt`，以及版本通配符，例如 `foo=1.0`。在引用带有特定版本的软件包名称时，请勿在版本周围使用单引号或双引号，例如 `foo=1.0` 或 `foo>=1.0`。
only_upgrade boolean	仅当软件包已安装时才升级。选项 `false` ← (默认) `true`
policy_rc_d integer 在 Ansible 2.8 中添加	强制 `/usr/sbin/policy-rc.d` 的退出代码。例如，如果 `policy_rc_d=101`，则安装的软件包不会触发服务启动。如果 `/usr/sbin/policy-rc.d` 已存在，它将在软件包安装后备份并恢复。如果 `null`，则不会创建/更改 `/usr/sbin/policy-rc.d`。
purge boolean	如果 `state=absent` 或 `autoremove=yes`，将强制清除配置文件。选项 `false` ← (默认) `true`
state string	指示所需的软件包状态。`latest` 确保安装最新版本。`build-dep` 确保安装软件包构建依赖项。`fixed` 尝试更正具有损坏依赖项的系统。选项 `"absent"` `"build-dep"` `"latest"` `"present"` ← (默认) `"fixed"`
update_cache 别名：update-cache boolean	在操作之前运行相当于 `apt-get update` 的命令。可以作为软件包安装的一部分运行，也可以作为单独的步骤运行。默认情况下不更新缓存。选项 `false` `true`
update_cache_retries integer 在 ansible-base 2.10 中添加	如果缓存更新失败，则重试次数。另请参见 `update_cache_retry_max_delay`。默认值： `5`
update_cache_retry_max_delay integer 在 ansible-base 2.10 中添加	为每次重试使用指数退避延迟（请参见 `update_cache_retries`），直到达到此最大延迟（以秒为单位）。默认值： `12`
upgrade string	如果为 yes 或 safe，则执行 aptitude safe-upgrade。如果为 full，则执行 aptitude full-upgrade。如果为 dist，则执行 apt-get dist-upgrade。注意：这不会升级特定的软件包，请使用 state=latest 来升级。注意：自 2.4 起，如果 aptitude 不存在，则将 apt-get 用作后备。选项 `"dist"` `"full"` `"no"` ← (默认) `"safe"` `"yes"`

属性 

属性	支持	描述
check_mode	支持：完全	可以在 check_mode 中运行，并在不修改目标的情况下返回已更改状态的预测；如果不支持，则将跳过该操作。
diff_mode	支持：完全	当处于 diff 模式时，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息
platform	平台： debian	可以针对其操作的目标操作系统/系列

说明 

注意

三种升级模式（full、safe 及其别名 true）在 2.3 之前需要 aptitude，自 2.4 起，apt-get 被用作后备。
在大多数情况下，使用 *apt* 安装的软件包默认会启动新安装的服务。大多数发行版都有避免这种情况的机制。例如，在 Debian 9 中安装 Postgresql-9.5 时，创建一个返回代码为 101 的可执行 shell 脚本 (/usr/sbin/policy-rc.d) 将阻止 Postgresql 9.5 在安装后启动。之后删除该文件或其执行权限。
apt-get 命令行在此处支持隐式正则表达式匹配，但我们不支持，因为它更容易让拼写错误通过（如果将 foo 拼写为 fo，apt-get 将安装名称中带有“fo”的软件包，并向用户发出警告和提示。由于安装前没有警告和提示，因此我们不允许这样做。如果要使用通配符，请使用显式的 fnmatch 模式）。
当与 loop: 一起使用时，每个软件包都将单独处理，将列表直接传递给 name 选项效率更高。
当使用 default_release 时，将使用 990 的隐式优先级。这与 apt-get -t 的行为相同。
当指定确切的版本时，将使用 1001 的隐式优先级。
如果解释器无法导入 python3-apt，该模块还将在系统拥有的解释器中检查它。如果找不到依赖项，则根据 auto_install_module_deps 的值，该模块将尝试安装它。如果找到或安装了依赖项，该模块将在正确的解释器下重新生成。

示例 

- name: Install apache httpd (state=present is optional)
  ansible.builtin.apt:
    name: apache2
    state: present

- name: Update repositories cache and install "foo" package
  ansible.builtin.apt:
    name: foo
    update_cache: yes

- name: Remove "foo" package
  ansible.builtin.apt:
    name: foo
    state: absent

- name: Install the package "foo"
  ansible.builtin.apt:
    name: foo

- name: Install a list of packages
  ansible.builtin.apt:
    pkg:
    - foo
    - foo-tools

- name: Install the version '1.00' of package "foo"
  ansible.builtin.apt:
    name: foo=1.00

- name: Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
  ansible.builtin.apt:
    name: nginx
    state: latest
    default_release: squeeze-backports
    update_cache: yes

- name: Install the version '1.18.0' of package "nginx" and allow potential downgrades
  ansible.builtin.apt:
    name: nginx=1.18.0
    state: present
    allow_downgrade: yes

- name: Install zfsutils-linux with ensuring conflicted packages (e.g. zfs-fuse) will not be removed.
  ansible.builtin.apt:
    name: zfsutils-linux
    state: latest
    fail_on_autoremove: yes

- name: Install latest version of "openjdk-6-jdk" ignoring "install-recommends"
  ansible.builtin.apt:
    name: openjdk-6-jdk
    state: latest
    install_recommends: no

- name: Update all packages to their latest version
  ansible.builtin.apt:
    name: "*"
    state: latest

- name: Upgrade the OS (apt-get dist-upgrade)
  ansible.builtin.apt:
    upgrade: dist

- name: Run the equivalent of "apt-get update" as a separate step
  ansible.builtin.apt:
    update_cache: yes

- name: Only run "update_cache=yes" if the last one is more than 3600 seconds ago
  ansible.builtin.apt:
    update_cache: yes
    cache_valid_time: 3600

- name: Pass options to dpkg on run
  ansible.builtin.apt:
    upgrade: dist
    update_cache: yes
    dpkg_options: 'force-confold,force-confdef'

- name: Install a .deb package
  ansible.builtin.apt:
    deb: /tmp/mypackage.deb

- name: Install the build dependencies for package "foo"
  ansible.builtin.apt:
    pkg: foo
    state: build-dep

- name: Install a .deb package from the internet
  ansible.builtin.apt:
    deb: https://example.com/python-ppq_0.1-1_all.deb

- name: Remove useless packages from the cache
  ansible.builtin.apt:
    autoclean: yes

- name: Remove dependencies that are no longer required
  ansible.builtin.apt:
    autoremove: yes

- name: Remove dependencies that are no longer required and purge their configuration files
  ansible.builtin.apt:
    autoremove: yes
    purge: true

- name: Run the equivalent of "apt-get clean" as a separate step
  ansible.builtin.apt:
    clean: yes

返回值 

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

键	描述
cache_update_time integer	上次缓存更新的时间（如果未知，则为 0）返回：成功，在某些情况下示例： `1425828348000`
cache_updated boolean	缓存是否已更新返回：成功，在某些情况下示例： `true`
stderr string	来自 apt 的错误输出返回：成功，在需要时示例： `"AH00558: apache2: 无法可靠地确定服务器的完全限定域名，使用 127.0.1.1。全局设置 'ServerName' 指令 ..."`
stdout string	来自 apt 的输出返回：成功，在需要时示例： `"正在读取软件包列表...\n正在构建依赖关系树...\n正在读取状态信息...\n将安装以下额外软件包：\n apache2-bin ..."`

作者

Matthew Williams (@mgwilliams)