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

注意

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

概要 

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

需求 

执行此模块的主机需要以下需求。

python-apt (python 2)
python3-apt (python 3)
aptitude (2.4 版本之前)

参数 

参数	注释
allow_change_held_packages 布尔值在 ansible-core 2.13 中添加	允许更改位于 apt 保持列表中的包的版本选项 `false` ← (默认) `true`
allow_downgrade 别名：allow-downgrade, allow_downgrades, allow-downgrades 布尔值在 ansible-core 2.12 中添加	对应于 apt 的 `--allow-downgrades` 选项。此选项允许使用指定的包和版本替换已安装的更高版本的该包。请注意，设置 `allow_downgrade=true` 会使此模块的行为非幂等。（任务最终可能得到一组与指定的完整安装包列表不匹配的包）。 `allow_downgrade` 只受 `apt` 支持，如果检测到或指定了 `aptitude`，则将被忽略。选项 `false` ← (默认) `true`
allow_unauthenticated 别名：allow-unauthenticated 布尔值	忽略无法验证的包。这对于引导管理其自身 apt 密钥设置的环境非常有用。 `allow_unauthenticated` 只与 `state`: `install`/`present` 一起支持选项 `false` ← (默认) `true`
autoclean 布尔值	如果 `true`，则清除本地存储库中无法再下载的已检索包文件。选项 `false` ← (默认) `true`
autoremove 布尔值	如果 `true`，则删除所有模块状态（`build-dep` 除外）的未使用依赖项包。它也可以用作唯一的选项。 2.4 版本之前，autoclean 也是 autoremove 的别名，现在它是一个单独的命令。有关更多信息，请参阅文档。选项 `false` ← (默认) `true`
cache_valid_time 整数	如果 apt 缓存比 `cache_valid_time` 旧，则更新 apt 缓存。此选项以秒为单位设置。从 Ansible 2.4 开始，如果显式设置，则设置 `update_cache=yes`。默认值： `0`
clean 布尔值在 ansible-core 2.13 中添加	运行相当于 `apt-get clean` 的命令以清除本地存储库中已检索的包文件。它会删除 /var/cache/apt/archives/ 和 /var/cache/apt/archives/partial/ 中除锁文件以外的所有内容。可以作为包安装的一部分运行 (clean 在安装之前运行) 或作为单独的步骤运行。选项 `false` ← (默认) `true`
deb 路径	远程机器上 .deb 包的路径。如果路径中包含 ://，ansible 将尝试在安装之前下载 deb。(版本 2.1 中添加) 需要 `xz-utils` 包才能提取 deb 包的控制文件以进行安装。
default_release 别名：default-release 字符串	对应于 apt 的 `-t` 选项，并设置 pin 优先级
dpkg_options 字符串	将 dpkg 选项添加到 apt 命令。默认为 ‘-o “Dpkg::Options::=–force-confdef” -o “Dpkg::Options::=–force-confold”’ 选项应作为逗号分隔的列表提供默认值： `"force-confdef,force-confold"`
fail_on_autoremove 布尔值在 ansible-core 2.11 中添加	对应于 `apt` 的 `--no-remove` 选项。如果 `true`，则确保不会删除任何包，否则任务将失败。 `fail_on_autoremove` 只与 `state`（`absent` 除外）一起支持。 `fail_on_autoremove` 只受 `apt` 支持，如果检测到或指定了 `aptitude`，则将被忽略。选项 `false` ← (默认) `true`
force 布尔值	对应于apt-get的`--force-yes`，并隐含`allow_unauthenticated=yes`和`allow_downgrade=yes` 此选项将禁用对软件包签名和下载它们的Web服务器证书的检查。此选项不等同于在命令行上向apt-get传递`-f`标志。这是一个具有破坏系统潜力的破坏性操作，几乎不应该使用。请参阅`man apt-get`以了解更多信息。选项 `false` ← (默认) `true`
force_apt_get 布尔值	强制使用apt-get而不是aptitude 选项 `false` ← (默认) `true`
install_recommends 别名：install-recommends 布尔值	对应于apt的`--no-install-recommends`选项。`true`安装推荐的软件包。`false`不安装推荐的软件包。默认情况下，Ansible将使用与操作系统相同的默认值。建议的软件包永远不会被安装。选项 `false` `true`
lock_timeout 整数在 ansible-core 2.12 中添加	此操作等待获取apt数据库锁的秒数。有时存在短暂的锁，这将至少重试到超时。默认值：`60`
name 别名：package, pkg 列表 / 元素=字符串	软件包名称列表，例如`foo`，或带有版本的软件包说明符，例如`foo=1.0`或`foo>=1.0`。还支持名称通配符（fnmatch），例如`apt`和版本通配符，例如`foo=1.0`。
only_upgrade 布尔值	仅在已安装软件包时才升级。选项 `false` ← (默认) `true`
policy_rc_d 整数 Ansible 2.8 中添加	强制/usr/sbin/policy-rc.d的退出代码。例如，如果policy_rc_d=101，则已安装的软件包不会触发服务启动。如果/usr/sbin/policy-rc.d已存在，则会在软件包安装后备份并恢复。如果为`null`，则不会创建/更改/usr/sbin/policy-rc.d。
purge 布尔值	如果`state=absent`或`autoremove=yes`，则将强制清除配置文件。选项 `false` ← (默认) `true`
state 字符串	指示所需的软件包状态。`latest`确保安装最新版本。`build-dep`确保安装软件包构建依赖项。`fixed`尝试纠正系统中存在的依赖关系损坏。选项 `"absent"` `"build-dep"` `"latest"` `"present"` ← (默认) `"fixed"`
update_cache 别名：update-cache 布尔值	在操作之前运行等效于`apt-get update`的命令。可以作为软件包安装的一部分运行，也可以作为单独的步骤运行。默认是不更新缓存。选项 `false` `true`
update_cache_retries 整数 ansible-base 2.10 中添加	如果缓存更新失败，则重试次数。另请参见`update_cache_retry_max_delay`。默认值：`5`
update_cache_retry_max_delay 整数 ansible-base 2.10 中添加	对每次重试使用指数退避延迟（参见`update_cache_retries`），最大延迟时间为秒。默认值：`12`
upgrade 字符串	如果是yes或safe，则执行aptitude安全升级。如果是full，则执行aptitude完全升级。如果是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时，创建一个可执行的shell脚本（/usr/sbin/policy-rc.d）并抛出101的返回代码将阻止Postgresql 9.5在安装后启动。之后删除该文件或其执行权限。
apt-get命令行在此处支持隐式正则表达式匹配，但我们不支持，因为它更容易让错别字通过（如果您将foo误输入为fo，apt-get将安装名称中包含“fo”的软件包，并显示警告和用户提示。由于我们在安装前没有警告和提示，因此我们不允许这样做。如果您想要通配符，请使用显式的fnmatch模式）。
当与loop:一起使用时，每个软件包将被单独处理，将列表直接传递给name选项效率更高。
当使用default_release时，将使用990的隐式优先级。这与apt-get -t的行为相同。
当指定确切版本时，将使用1001的隐式优先级。
如果解释器无法导入``python-apt``/``python3-apt``，模块也将检查系统拥有的解释器中是否存在该模块。如果找不到依赖项，模块将尝试安装它。如果找到或安装了依赖项，则模块将在正确的解释器下重新生成。

示例 

- 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 整数	上次缓存更新的时间（如果未知则为0）返回：成功，在某些情况下示例：`1425828348000`
cache_updated 布尔值	缓存是否已更新返回：成功，在某些情况下示例：`true`
stderr 字符串	来自apt的错误输出返回：成功，在需要时示例：`"AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to ..."`
stdout 字符串	来自apt的输出返回：成功，在需要时示例：`"Reading package lists...\nBuilding dependency tree...\nReading state information...\nThe following extra packages will be installed:\n apache2-bin ..."`

作者

Matthew Williams (@mgwilliams)