errata-tool-ansible

Ansible modules to manage Errata Tool resources.

This is not about installing the Errata Tool. Instead, it is a way to declaratively define things within Errata Tool, where you might normally use the Errata Tool UI.

errata_tool_product

The errata_tool_product module can create or update products within the Errata Tool.

- name: Add RHCEPH product
  errata_tool_product:
    short_name: RHCEPH
    name: Red Hat Ceph Storage
    description: Red Hat Ceph Storage
    bugzilla_product_name: ""
    valid_bug_states:
      - ASSIGNED
      - MODIFIED
      - NEW
      - ON_DEV
      - ON_QA
      - POST
      - VERIFIED
    active: true
    ftp_subdir: RHCEPH
    internal: false
    default_docs_reviewer: [email protected]
    push_targets:
      - ftp
      - cdn_stage
      - cdn_docker_stage
      - cdn_docker
      - cdn
    default_solution: enterprise
    state_machine_rule_set: Default
    move_bugs_on_qe: false

errata_tool_product_version

The errata_tool_product_version module can create or update Product Versions within the Errata Tool.

- name: Add RHCEPH 4.0 RHEL 8 Product Version
  errata_tool_product_version:
    product: RHCEPH
    name: RHCEPH-4.0-RHEL-8
    description: Red Hat Ceph Storage 4.0
    default_brew_tag: ceph-4.0-rhel-8-candidate
    allow_rhn_debuginfo: false
    is_oval_product: false
    is_rhel_addon: false
    is_server_only: false
    rhel_release_name: RHEL-8
    sig_key_name: redhatrelease2
    allow_buildroot_push: false
    push_targets:
      - ftp
      - cdn_stage
      - cdn_docker_stage
      - cdn_docker
      - cdn

errata_tool_release

The errata_tool_release module can create or update Releases within the Errata Tool.

- name: Add rhceph-4.0 release
  errata_tool_release:
    product: RHCEPH
    name: rhceph-4.0
    type: QuarterlyUpdate
    description: Red Hat Ceph Storage 4.0
    product_versions:
      - RHCEPH-4.0-RHEL-8
      - RHEL-7-RHCEPH-4.0
    enabled: true
    active: true
    enable_batching: false
    program_manager: [email protected]
    blocker_flags:
      - ceph-4
    internal_target_release: ""
    zstream_target_release: null
    ship_date: '2020-01-31'
    allow_shadow: false
    allow_blocker: false
    allow_exception: false
    allow_pkg_dupes: true
    supports_component_acl: true
    limit_bugs_by_product: false
    state_machine_rule_set: null
    pelc_product_version: null
    brew_tags: []

errata_tool_variant

The errata_tool_variant module can create or update Variants within the Errata Tool.

- name: Add RHCEPH 4.0 Tools variant
  errata_tool_variant:
    name: 8Base-RHCEPH-4.0-Tools
    description: Red Hat Ceph Storage 4.0 Tools
    cpe: "cpe:/a:redhat:ceph_storage:4::el8"
    enabled: true
    buildroot: false
    product_version: RHCEPH-4.0-RHEL-8
    rhel_variant: 8Base
    push_targets: []

errata_tool_cdn_repo

The errata_tool_cdn_repo module can create or update CDN Repos within the Errata Tool.

- name: Add redhat-rhceph-rhceph-4-rhel8 cdn repo
  errata_tool_cdn_repo:
    name: redhat-rhceph-rhceph-4-rhel8
    release_type: Primary
    content_type: Docker
    variants:
      - 8Base-RHCEPH-4.0-Tools
    packages:
      rhceph-container:
        - latest
        - "{% raw %}{{version}}{% endraw %}"
        - "{% raw %}{{version}}-{{release}}{% endraw %}"

Note that if you want to use a tag string like {{version}} for your package, you must escape the double brackets for Ansible with the {% raw %} ... {% endraw %} syntax. If you pass the values into Ansible Tower's REST API, you may not need to escape the values like this.

errata_tool_user

The errata_tool_user module can create or update Users within the Errata Tool.

- name: Add program manager Errata Tool account
  errata_tool_user:
    login_name: [email protected]
    realname: Cool ProgramManager
    organization: Program Management
    receives_mail: false
    roles:
      - pm

errata_tool_request

The errata_tool_request module can perform low-level HTTP requests to Errata Tool. This exposes the entire Errata Tool REST API to you directly. It is like Ansible's core uri module, except this respects the ERRATA_TOOL_URL and ERRATA_TOOL_AUTH variables and can perform SPENEGO (GSSAPI) authentication.

Why would you use this module instead of the higher level modules like errata_tool_product, errata_tool_user, etc? This errata_tool_request module has two main uses-cases.

1. You may want to do something that the higher level modules do not yet support. It can be easier to use this module to quickly prototype out your ideas for what actions you need, and then write the Python code to do it in a better way later. If you find that you need to use errata_tool_request to achieve functionality that is not yet present in the other errata-tool-ansible modules, please file a Feature Request issue in GitHub with your use case.
2. You want to write some tests that verify ET's data at a very low level. For example, you may want to write an integration test to verify that you've set up your ET configuration in the way you expect.

Note that this module will always report "changed: true" every time, because it simply sends the request to the ET server on every ansible run. This module cannot understand if your chosen request actually "changes" anything.

- name: Make a raw HTTP API call
  errata_tool_request:
    path: /api/v1/user/cooldeveloper
  register: response

- name: show the parsed JSON in the HTTP response
  debug:
    var: response.json

- name: check one of the values in the JSON response
  assert:
    that:
      - response.json.login_name == '[email protected]'

Installing errata-tool-ansible from Ansible Galaxy

We distribute errata-tool-ansible through the Ansible Galaxy.

If you are using Ansible 2.9 or greater, you can install errata-tool-ansible like so:

ansible-galaxy collection install ktdreyer.errata_tool_ansible

This will install the latest Git snapshot automatically. Use --force upgrade your installed version to the latest version.

Python dependencies

These Ansible modules require the requests-gssapi and lxml Python libraries. You must install these libraries on the host where Ansible will execute (typically localhost).

On RHEL 7:

yum -y install python-requests-gssapi python-lxml

On RHEL 8+ and Fedora:

yum -y install python3-requests-gssapi python3-lxml

Python versions

The errata-tool-ansible modules support RHEL 7 (Python 2.7), RHEL 8 (Python 3.6), and Fedora (latest Python 3). If you are writing a patch, you can test these Python versions by running tox locally.

If you're using RHEL 7, please upgrade to RHEL 8, because it provides a much better user experience. For example, python-requests-2.6.0-10.el7 does not show URLs on failures, so it's harder to debug when things break.

Errata Tool environment

These modules operate on the production Errata Tool environment by default. You must have a valid Kerberos ticket.

You can select another environment with the ERRATA_TOOL_URL environment variable, like so:

ERRATA_TOOL_URL=https://other.env/ ansible-playbook -v my-et-playbook.yml

You can disable GSSAPI (Kerberos) authentication with the ERRATA_TOOL_AUTH environment variable:

ERRATA_TOOL_URL=https://other.env/ ERRATA_TOOL_AUTH=notkerberos ansible-playbook ...

You can use Ansible's environment setting with your tasks or playbooks. Here's an example playbook that calls a custom role with those variables set:

- name: ensure ET configuration
  gather_facts: no
  hosts: localhost
  connection: local
  environment:
    ERRATA_TOOL_URL: https://other.env/
    ERRATA_TOOL_AUTH: notkerberos
  roles:
    - my-custom-et-role

There is no support for HTTP Basic auth at this time.

SSL verification

This Ansible module verifies the ET server's HTTPS certificate by default. If you receive an SSL verification error, it's probably because you don't have the Red Hat IT CA set up for your Python environment (particularly if you're using a virtualenv). python-requests defaults to using certifi.where(), which may not point at a CA bundle that contains the RH IT CA.

You can use Ansible's environment setting with your tasks or playbooks. Here's an example playbook that calls a custom role with those variables set:

- name: ensure ET configuration
  gather_facts: no
  hosts: localhost
  connection: local
  environment:
    REQUESTS_CA_BUNDLE: /etc/pki/ca-trust/source/anchors/RH-IT-Root-CA.crt
  roles:
    - my-custom-et-role

Where RH-IT-Root-CA.crt is the public cert that signed the ET server's HTTPS certificate.

Strict user checking

For modules operating with Errata user accounts, you can optionally use ANSIBLE_STRICT_USER_CHECK_MODE environment variable to control whether the module should check that the user account exists or not during a check mode.

If ANSIBLE_STRICT_USER_CHECK_MODE is False or unset (default), modules will not validate user accounts during check mode.

If ANSIBLE_STRICT_USER_CHECK_MODE is True and check mode is on, the modules will check the user account and fail if they don't exist, are not enabled, or lack required roles.

Example of using strict user checking:

ANSIBLE_STRICT_USER_CHECK_MODE=1 ansible-playbook my-et-playbook.yml -v --check

It's also possible to set the environment variable in the playbook itself:

- name: test strict user checking
  environment:
    ANSIBLE_STRICT_USER_CHECK_MODE: true

Trying to set default_docs_reviewer in errata_tool_product, for example, for a non-existing account would produce the following error:

default_docs_reviewer noexist account not found

And trying to set default_docs_reviewer without the docs role:

User nodocsrole does not have 'docs' role in ET

File paths

These modules import common_errata_tool from the module_utils directory.

One easy way to arrange your Ansible files is to symlink the library and module_utils directories into the directory with your playbook.

For example, if you have a errata-tool.yml playbook that you run with ansible-playbook, it should live alongside these library and module_utils directories:

top
├── errata-tool.yml
├── module_utils
└── library

and you should run the playbook like so:

ansible-playbook errata-tool.yml

License

This errata-tool-ansible project is licensed under the GPLv3-or-later to match Ansible's license.

TODO

• Unit tests
• Integration tests