No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-21 01:07:31 +01:00
defaults Initial commit 2026-11-21 01:07:31 +01:00
files/ca-certificates Initial commit 2026-11-21 01:07:31 +01:00
handlers Initial commit 2026-11-21 01:07:31 +01:00
meta Initial commit 2026-11-21 01:07:31 +01:00
tasks Initial commit 2026-11-21 01:07:31 +01:00
vars Initial commit 2026-11-21 01:07:31 +01:00
.ansible-lint Initial commit 2026-11-21 01:07:31 +01:00
.gitignore Initial commit 2026-11-21 01:07:31 +01:00
.yamllint Initial commit 2026-11-21 01:07:31 +01:00
LICENSE Initial commit 2026-11-21 01:07:31 +01:00
README.md Initial commit 2026-11-21 01:07:31 +01:00

Ansible role: ca_certificates

Installs locally trusted CA certificates on Debian 13 (trixie), rebuilds the system CA bundle, and supports certificates shipped with the role as well as certificates supplied by the caller.

Features

  • Ships a set of CA certificates and installs a configurable subset by default.
  • Installs additional bundled certificates selected by file name.
  • Installs caller supplied certificates from the inventory using either inline content or a source file.
  • Removes certificates from the local trust store when they are no longer required.
  • Validates all input with meta/argument_specs.yml and explicit assertions before changing the target.
  • Refreshes the system trust store with update-ca-certificates --fresh and flushes the handler before the role completes.
  • Is idempotent and supports check mode.

Requirements

  • Debian 13 (trixie). Other Debian releases may work but are not tested.
  • Ansible core 2.16 or newer.
  • become: true (or equivalent privileges) to write to the trust store and run update-ca-certificates.
  • The ca-certificates package, which the role ensures is installed.

Installation

Install the role with ansible-galaxy or vendor it in your repository:

ansible-galaxy role install git+https://git.bluemedia.dev/infrastructure/ansible-role-ca-certificates.git,main

The role is then available as ca_certificates.

Bundled certificates

The role carries the following example CA certificates in files/ca-certificates/:

File name Installed by default Subject
example-internal-root-ca.crt yes Example Internal Root CA
example-internal-issuing-ca.crt no Example Internal Issuing CA
example-lab-ca.crt no Example Lab Root CA
example-partner-ca.crt no Example Partner Root CA

These certificates are placeholders for development and testing. They are self-signed or issued by the example root, contain no private keys, and must be replaced with your organisation's CA material before production use. To replace them, add your own .crt files to files/ca-certificates/ and adjust ca_certificates_defaults.

Role variables

Variable Default Description
ca_certificates_defaults [example-internal-root-ca.crt] Bundled certificates installed by default. Override, for example with [], to change the default set.
ca_certificates_bundled [] Additional bundled certificate file names to install. Each name must exist under files/ca-certificates/.
ca_certificates_extra [] Caller supplied certificates. See below.
ca_certificates_absent [] Certificate file names to remove from the trust store.
ca_certificates_trust_store /usr/local/share/ca-certificates Directory scanned by update-ca-certificates. Must be an absolute path.
ca_certificates_package_state present Package state for ca-certificates; present or latest.
ca_certificates_update_cache false Refresh the apt package index before installing the package.

Every entry in ca_certificates_extra is a dictionary with the following keys:

Key Required Description
name yes Destination file name in the trust store. Must be unique and end in .crt.
src one of Path to a certificate on the controller. Resolved using the same rules as ansible.builtin.copy.
content one of Inline PEM certificate content.

Exactly one of src and content must be provided for every entry.

Usage

Install the default bundled certificates

---
- name: Trust internal CA certificates
  hosts: all
  become: true
  roles:
    - role: ca_certificates

Install additional bundled certificates

---
- name: Trust internal and laboratory CA certificates
  hosts: all
  become: true
  roles:
    - role: ca_certificates
      vars:
        ca_certificates_bundled:
          - example-lab-ca.crt
          - example-partner-ca.crt

Install certificates from the inventory

Certificates can be supplied from group_vars, host_vars, or directly in the play. Using src is recommended for larger certificate files:

---
ca_certificates_extra:
  - name: corp-root-ca.crt
    src: "{{ playbook_dir }}/files/corp-root-ca.crt"
  - name: partner-root-ca.crt
    content: "{{ lookup('ansible.builtin.file', playbook_dir ~ '/files/partner-root-ca.crt') }}"
---
- name: Trust organisation and partner CA certificates
  hosts: all
  become: true
  roles:
    - role: ca_certificates

Install only caller supplied certificates

Set ca_certificates_defaults to an empty list to opt out of the bundled defaults:

---
- name: Trust only caller supplied CA certificates
  hosts: all
  become: true
  roles:
    - role: ca_certificates
      vars:
        ca_certificates_defaults: []
        ca_certificates_extra:
          - name: corp-root-ca.crt
            src: /srv/pki/corp-root-ca.crt

Remove certificates

List the file names to delete from the trust store:

---
- name: Remove a retired CA certificate
  hosts: all
  become: true
  roles:
    - role: ca_certificates
      vars:
        ca_certificates_defaults:
          - example-internal-root-ca.crt
        ca_certificates_absent:
          - retired-root-ca.crt

Removing a certificate that is still part of the installed set is rejected. Adjust ca_certificates_defaults or ca_certificates_bundled first.

Behaviour

  • All managed file names are validated: they must be plain names ending in .crt without path separators or ...
  • Names must be unique across the installed set. The defaults and additional bundled names are de-duplicated.
  • Requested bundled certificates must exist in the role before any change is made.
  • Installed certificates are copied with owner root, group root, and mode 0644 into ca_certificates_trust_store.
  • Removing a certificate is performed after installing new certificates. Install and removal sets may not overlap.
  • Any change notifies the Update CA certificate trust store handler, which runs update-ca-certificates --fresh. The role flushes handlers at the end so the system bundle is current before the role returns.
  • The role does not remove certificates it does not manage. Only names listed in ca_certificates_absent are removed.
  • The ca_certificates_trust_store variable exists for compatible trust store layouts. update-ca-certificates scans /usr/local/share/ca-certificates by default, so change this only when the target is configured accordingly.

License

MIT. See LICENSE.