Difference between revisions of "Ansible APK Module"
m (Added internal link to Ansible) |
m (Clarification, collection not required, still in Ansible 2.10 core.) |
||
(2 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{Draft}} | {{Draft}} | ||
− | Alpine Linux uses [[Alpine_Linux_package_management|APK]] for | + | Alpine Linux uses [[Alpine_Linux_package_management|APK]] for package management. |
+ | |||
+ | * [[Ansible]] 2.0 includes the [https://docs.ansible.com/ansible/2.9/modules/apk_module.html APK module], which provides support for package management on Alpine Linux hosts. | ||
+ | * [https://github.com/ansible-collections/overview#where-we-ve-come-from-and-where-we-are-going Ansible 2.10 onwards]: the [https://docs.ansible.com/ansible/latest/collections/community/general/apk_module.html APK module] is also available in the [https://galaxy.ansible.com/community/general community.general] collection, installed via: <code>ansible-galaxy collection install community.general</code>. | ||
+ | |||
+ | This document provides some Ansible playbook samples and module explanations. | ||
= Details on Module Options = | = Details on Module Options = | ||
Line 8: | Line 13: | ||
== state == | == state == | ||
The 'state' option specifies what you want to do with the listed package(s) - present (installed but not upgraded), latest (installed or upgraded), absent (removed). The option defaults to 'present', so this command will not upgrade a package that is already installed if 'state' is not specified as 'latest'. | The 'state' option specifies what you want to do with the listed package(s) - present (installed but not upgraded), latest (installed or upgraded), absent (removed). The option defaults to 'present', so this command will not upgrade a package that is already installed if 'state' is not specified as 'latest'. | ||
+ | |||
+ | There is a bug for state='latest' due to [http://bugs.alpinelinux.org/issues/7531 bug #7531]. If you attempt to upgrade a package but do not also list its dependencies, the package will not be upgraded. | ||
== update_cache == | == update_cache == | ||
It is always a good idea to include the 'update_cache' option, because the command might fail otherwise if the repositories contain a newer version of the package than listed in the local package index cache. The name 'update_cache' is slightly misleading, because it actually refers to the local package index cache, not the local package cache. The system repositories are specified in the /etc/apk/repositories file (or files within /etc/apk/repositories.d/). There is a separate locally cached index for each repository specified, including the system repositories and those specified in the 'repository' option. | It is always a good idea to include the 'update_cache' option, because the command might fail otherwise if the repositories contain a newer version of the package than listed in the local package index cache. The name 'update_cache' is slightly misleading, because it actually refers to the local package index cache, not the local package cache. The system repositories are specified in the /etc/apk/repositories file (or files within /etc/apk/repositories.d/). There is a separate locally cached index for each repository specified, including the system repositories and those specified in the 'repository' option. | ||
Line 15: | Line 22: | ||
The 'available' option only applies to the 'upgrade' option. According to the documentation: "During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead of holding them) if the currently installed package is no longer available from any repository." In other words, using 'available' makes downgrades possible. | The 'available' option only applies to the 'upgrade' option. According to the documentation: "During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead of holding them) if the currently installed package is no longer available from any repository." In other words, using 'available' makes downgrades possible. | ||
== repository (Ansible 2.4) == | == repository (Ansible 2.4) == | ||
− | If the 'repository' option is not specified, 'apk' will use the system repositories specified in /etc/apk/repositories (or files within /etc/apk/repositories.d/). | + | If the 'repository' option is not specified, 'apk' will use the system repositories specified in /etc/apk/repositories (or files within /etc/apk/repositories.d/). More specifically, it will always use the local package index cache for the system repositories, and the local package index cache will be updated for the system repositories if 'update_cache' is set. If you specify the 'repository' option, 'apk' will use BOTH the system repositories AND those specified in the option. Note that 'apk' will install the newest package if multiple versions of the same package are available in the package index(es). Because the system repositories AND the specified repositories are used, it is difficult to see package downgrades in check mode. |
− | + | ||
− | + | [https://github.com/ansible/ansible/pull/32689 A pull request] has been submitted to modify the functionality so that the 'repository' option will OVERRIDE the system repositories. This will make functionality consistent across check mode and non-check mode. | |
= Basic Package Installation = | = Basic Package Installation = |
Latest revision as of 19:30, 19 December 2020
![]() Do not follow instructions here until this notice is removed. |
Alpine Linux uses APK for package management.
- Ansible 2.0 includes the APK module, which provides support for package management on Alpine Linux hosts.
- Ansible 2.10 onwards: the APK module is also available in the community.general collection, installed via:
ansible-galaxy collection install community.general
.
This document provides some Ansible playbook samples and module explanations.
Contents
Details on Module Options
name
The 'name' option can contain a single package or list of packages to install.
state
The 'state' option specifies what you want to do with the listed package(s) - present (installed but not upgraded), latest (installed or upgraded), absent (removed). The option defaults to 'present', so this command will not upgrade a package that is already installed if 'state' is not specified as 'latest'.
There is a bug for state='latest' due to bug #7531. If you attempt to upgrade a package but do not also list its dependencies, the package will not be upgraded.
update_cache
It is always a good idea to include the 'update_cache' option, because the command might fail otherwise if the repositories contain a newer version of the package than listed in the local package index cache. The name 'update_cache' is slightly misleading, because it actually refers to the local package index cache, not the local package cache. The system repositories are specified in the /etc/apk/repositories file (or files within /etc/apk/repositories.d/). There is a separate locally cached index for each repository specified, including the system repositories and those specified in the 'repository' option.
upgrade
The 'upgrade' option is a system-wide upgrade of all packages. If you want to upgrade specific packages, use 'state' = 'latest'.
available (Ansible 2.4)
The 'available' option only applies to the 'upgrade' option. According to the documentation: "During upgrade, reset versioned world dependencies and change logic to prefer replacing or downgrading packages (instead of holding them) if the currently installed package is no longer available from any repository." In other words, using 'available' makes downgrades possible.
repository (Ansible 2.4)
If the 'repository' option is not specified, 'apk' will use the system repositories specified in /etc/apk/repositories (or files within /etc/apk/repositories.d/). More specifically, it will always use the local package index cache for the system repositories, and the local package index cache will be updated for the system repositories if 'update_cache' is set. If you specify the 'repository' option, 'apk' will use BOTH the system repositories AND those specified in the option. Note that 'apk' will install the newest package if multiple versions of the same package are available in the package index(es). Because the system repositories AND the specified repositories are used, it is difficult to see package downgrades in check mode.
A pull request has been submitted to modify the functionality so that the 'repository' option will OVERRIDE the system repositories. This will make functionality consistent across check mode and non-check mode.
Basic Package Installation
Package Present
# Update repositories and install "foo" package - apk: name: foo update_cache: yes
Advanced Features
tagged repos
check doesn't do actual update
system upgrade / downgrade - Upgrades to newer repository will work (with or without update). Attempting to downgrade with the newer repository still in /etc/apk/repositories will not downgrade.
trigger service restart based upon package upgrade
tasks: - name: upgrade available apk: available: yes upgrade: yes update_cache: yes repository: '{{ REPO }}' register: result - debug: msg: "The openssh package was updated so we should restart the sshd service" notify: restart sshd changed_when: "'openssh' in result.packages" when: "'openssh' in result.packages" handlers: - name: restart sshd service: name=sshd state=restarted