ansible.builtin.apt_key module – Add or remove an apt key

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name apt_key even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.apt_key for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

• Add or remove an apt key, optionally downloading it.

Requirements

The below requirements are needed on the host that executes this module.

• gpg

Parameters

Parameter	Comments
data string	The keyfile contents to add to the keyring.
file path	The path to a keyfile on the remote server to add to the keyring.
id string	The identifier of the key. Including this allows check mode to correctly report the changed state. If specifying a subkey’s id be aware that apt-key does not understand how to remove keys via a subkey id. Specify the primary key’s id instead. This parameter is required when state is set to absent.
keyring path	The full path to specific keyring file in /etc/apt/trusted.gpg.d/.
keyserver string	The keyserver to retrieve key from.
state string	Ensures that the key is present (added) or absent (revoked). Choices: "absent" "present" ← (default)
url string	The URL to retrieve key from.
validate_certs boolean	If false, SSL certificates for the target url will not be validated. This should only be used on personally controlled sites using self-signed certificates. Choices: false true ← (default)

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: debian	Target OS/families that can be operated against

Notes

Note

• The apt-key command used by this module has been deprecated. See the Debian wiki for details. This module is kept for backwards compatibility for systems that still use apt-key as the main way to manage apt repository keys.

• As a sanity check, downloaded key id must match the one specified.

• Use full fingerprint (40 characters) key ids to avoid key collisions. To generate a full-fingerprint imported key: apt-key adv --list-public-keys --with-fingerprint --with-colons.

• If you specify both the key id and the URL with state=present, the task can verify or add the key as needed.

• Adding a new key requires an apt cache update (e.g. using the ansible.builtin.apt module’s update_cache option).

See Also

See also

ansible.builtin.deb822_repository

Add and remove deb822 formatted repositories.

Examples

- name: One way to avoid apt_key once it is removed from your distro, armored keys should use .asc extension, binary should use .gpg
  block:
    - name: somerepo | no apt key
      ansible.builtin.get_url:
        url: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x36a1d7869245c8950f966e92d8576a8ba88d21e9
        dest: /etc/apt/keyrings/myrepo.asc
        checksum: sha256:bb42f0db45d46bab5f9ec619e1a47360b94c27142e57aa71f7050d08672309e0

    - name: somerepo | apt source
      ansible.builtin.apt_repository:
        repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
        state: present

- name: Add an apt key by id from a keyserver
  ansible.builtin.apt_key:
    keyserver: keyserver.ubuntu.com
    id: 36A1D7869245C8950F966E92D8576A8BA88D21E9

- name: Add an Apt signing key, uses whichever key is at the URL
  ansible.builtin.apt_key:
    url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
    state: present

- name: Add an Apt signing key, will not download if present
  ansible.builtin.apt_key:
    id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
    url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
    state: present

- name: Remove a Apt specific signing key, leading 0x is valid
  ansible.builtin.apt_key:
    id: 0x9FED2BCBDCD29CDF762678CBAED4B06F473041FA
    state: absent

# Use armored file since utf-8 string is expected. Must be of "PGP PUBLIC KEY BLOCK" type.
- name: Add a key from a file on the Ansible server
  ansible.builtin.apt_key:
    data: "{{ lookup('ansible.builtin.file', 'apt.asc') }}"
    state: present

- name: Add an Apt signing key to a specific keyring file
  ansible.builtin.apt_key:
    id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
    url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
    keyring: /etc/apt/trusted.gpg.d/debian.gpg

- name: Add Apt signing key on remote server to keyring
  ansible.builtin.apt_key:
    id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
    file: /tmp/apt.gpg
    state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
after list / elements=string	List of apt key ids or fingerprints after any modification Returned: on change Sample: ["D8576A8BA88D21E9", "3B4FE6ACC0B21F32", "D94AA3F0EFE21092", "871920D1991BC93C"]
before list / elements=string	List of apt key ids or fingprints before any modifications Returned: always Sample: ["3B4FE6ACC0B21F32", "D94AA3F0EFE21092", "871920D1991BC93C"]
fp string	Fingerprint of the key to import Returned: always Sample: "D8576A8BA88D21E9"
id string	key id from source Returned: always Sample: "36A1D7869245C8950F966E92D8576A8BA88D21E9"
key_id string	calculated key id, it should be same as ‘id’, but can be different Returned: always Sample: "36A1D7869245C8950F966E92D8576A8BA88D21E9"
short_id string	calculated short key id Returned: always Sample: "A88D21E9"

Authors

• Jayson Vantuyl (@jvantuyl)

Collection links

• Issue Tracker
• Repository (Sources)
• Communication