crungehottman / koji-ansible

Ansible modules to manage Koji resources

koji-ansible

Ansible modules to manage Koji resources.

This is not about installing Koji. Instead, it is a way to declaratively define things within Koji, where you might normally use the koji CLI.

koji_tag

The koji_tag module can create, update, and delete tags within Koji. It can also manage tag inheritance, packages list and group list for a tag.

- name: Create a koji tag for the ceph product
  koji_tag:
    name: ceph-3.1-rhel-7
    arches: x86_64
    state: present
    packages:
      kdreyer:
        - ansible
        - ceph
        - ceph-ansible
    groups:
      srpm-build:
        - rpm-build
        - fedpkg

koji_target

The koji_target module can create, update, and delete targets within Koji.

- name: Create a koji build target for Fedora 29
  koji_target:
    name: f29-candidate
    build_tag: f29-build
    dest_tag: f29-updates-candidate
    state: present

koji_external_repo

The koji_external_repo module can create, update, and delete external repositories within Koji.

- name: Create an external repo for CentOS "CR"
  koji_external_repo:
    name: centos7-cr
    url: http://mirror.centos.org/centos/7/cr/$arch/
    state: present

You can then configure these repositories (and their priorities) on each of your Koji tags with the external_repos parameter to the koji_tag module.

koji_cg

The koji_cg module can grant or revoke access to a content generator for a user account.

This user account must already exist in Koji's database. For example, you may run an authenticated koji hello command to create the account database entry.

- name: Grant access to the rcm/debbuild account
  koji_cg:
    koji: mykoji
    name: debian
    user: rcm/debbuild
    state: present

Your Koji Hub must be version 1.19 or newer in order to use the new listCGs RPC.

koji_btype

The koji_btype module can add new build types. These are typically in support of content generators.

(Koji only supports adding new build types, not deleting them.)

- name: Add debian build type to Koji
  koji_btype:
    koji: mykoji
    name: debian
    state: present

koji_archivetype

The koji_archivetype module can add new archive types. This allows Koji to recognize new build archive files, for example .deb files. These are typically in support of content generators.

(Koji only supports adding new archive types, not deleting them.)

Your Koji Hub must be version 1.20 or newer in order to use the new addArchiveType RPC.

- name: Add deb archive type
  koji_archivetype:
    name: deb
    description: Debian packages
    extensions: deb
    state: present

koji_host

The koji_host module can add new hosts and manage existing hosts.

Koji only supports adding new hosts, not deleting them. Once they're defined, you can enable or disable the hosts with state: enabled or state: disabled.

- name: Add new builder1 host
  koji_host:
    name: builder1.example.com
    arches: [x86_64]
    state: enabled
    channels:
      - default
      - createrepo

If you specify channels that do not yet exist, Ansible will create them. For example, if you are setting up a new builder host for OSBS, you can specify container in the list of channels, and Ansible will automatically create that new "container" channel when it configures the host.

koji_user

The koji_user module can add new users and manage existing users and permissions.

Koji only supports adding new users, not deleting them. Once they're defined, you can enable or disable the users with state: enabled or state: disabled.

- name: Add new kdreyer user
  koji_user:
    name: kdreyer
    state: enabled
    permissions: [admin]

koji_tag_inheritance

The koji_tag module (above) is all-or-nothing when it comes to managing tag inheritance. When you set inheritance with koji_tag, the module will delete any inheritance relationships that are not defined there.

In some cases you may want to declare some inheritance relationships within Ansible without clobbering other existing inheritance relationships. For example, MBS will dynamically manage some inheritance relationships of tags, and you do not want Ansible to fight MBS.

To declare inheritance relationships with finer granularity, you may use the koji_tag_inheritance module.

- name: set devtoolset-7 as a parent of ceph nautilus
  koji_tag_inheritance:
    parent_tag: sclo7-devtoolset-7-rh-release
    child_tag: storage7-ceph-nautilus-el7-build
    priority: 25

This will only mange that single parent-child relationship between the two tags, and it will not delete any other inheritance relationships.

koji_call

The koji_call module allows you to send raw RPCs to the Koji hub. This exposes the entire Koji API to you directly.

Why would you use this module instead of the higher level modules like koji_tag, koji_target, etc? This koji_call 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 koji_call to achieve functionality that is not yet present in the other koji-ansible modules, please file a Feature Request issue in GitHub with your use case.
2. You want to write some tests that verify Koji'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 Koji configuration in the way you expect.

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

- name: make a raw API call:
  koji_call:
    name: getTag
    args: [f29-build]
  register: call_result

- debug:
    var: call_result.data

This will print the tag information for the Fedora 29 -build tag. It is similar to running koji taginfo f29-build on the command-line.

Koji profiles

You must tell koji-ansible which Koji client profile to use.

Here is an example of setting a profile explicitly on the task:

- name: Create a koji tag for the ceph product
  koji_tag:
    koji: kojidev
    name: ceph-3.1-rhel-7
    arches: x86_64
    state: present

The koji: kojidev setting means Ansible will search ~/.koji/config.d/*.conf and /etc/koji.conf.d/*.conf for the [kojidev] config section and perform the tag management on that Koji hub listed there.

To avoid specifying this koji: argument on every task, you can set the KOJI_PROFILE environment variable when running ansible-playbook. koji-ansible will fall back to using KOJI_PROFILE for the tasks that have no explicit koji: argument:

KOJI_PROFILE=kojidev ansible-playbook -v my-koji-playbook.yaml

File paths

These modules import common_koji 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 koji.yml playbook that you run with ansible-playbook, it should live alongside these library and module_utils directories:

top
├── koji.yml
├── module_utils
└── library

and you should run the playbook like so:

ansible-playbook koji.yml

Investigating changes that happened outside Ansible

Koji tracks a history of everything in its database. You can view this history with the koji list-history and koji list-tag-history sub-commands.

For example, let's say that you wake up one morning to find that your Ansible playbook for your tags no longer matches up with what is configured live in Koji. Did someone else on your team make a change with the CLI without editing the playbook or notifying you? Who did it, and when? Use koji list-history --tag=my-tag to see the entire list of changes for your tag in the database. After a friendly chat with the person who made the change, you can work together to record the change within your Ansible playbook so your sources of truth remain consistent.

TODO

• Unit tests

• The long-term goal of this project is to merge into ansible itself so that the modules are built in. To that end, this koji-ansible project is licensed under the GPLv3 to match Ansible's license.

  Given some recent changes in Ansible upstream, it's possible that Collections would be a good option for distributing this instead. This is evolving as the Ansible community tries to decide the best way to distribute and share ownership over modules.