Distributed-CI (DCI) is a platform that allows a company to extend its CI coverage beyond its own walls; allowing them to let third-party partners contribute back their CI results into the platform.
DCI comes as a webservice that exposes its resources via a REST API. The dci-ansible project aims to map each of those REST resources to an Ansible module.
- Get Started
There are two ways to install dci-ansible, either via rpm packages or directly via Github source code.
Unless you are looking to contribute to this project, we recommend you use the rpm packages.
Officially supported platforms:
- CentOS (latest version)
- RHEL (latest version)
- Fedora (latest version)
If you're looking to install those modules on a different Operating System, please install it from source
First, you need to install the official Distributed-CI package repository
#> yum install https://packages.distributed-ci.io/dci-release.el7.noarch.rpm
Then, install the package
#> yum install dci-ansible
Define a folder where you would like to checkout the code and clone the repository.
#> cd /usr/share/dci && git clone https://github.com/redhat-cip/dci-ansible.git
The modules provided by this project covers all the endpoints Distributed-CI offers.
This means that this project allows one to interact with Distributed-CI for various use-cases:
- To act as an agent: Scheduling jobs, uploading logs and tests results.
- To act as a feeder: Creating Topics, Components and uploading Files.
- To complete adminitrative tasks: Creating Teams, Users, RemoteCIs.
- And more...
For any of the modules made available to work with the Distributed-CI API, one needs to authenticate itself first.
Each module relies on 3 environment variables to authenticate the author of the query:
DCI_CLIENT_ID: The ID of the resource that wish to authenticate (RemoteCI, User, Feeder)
DCI_API_SECRET: The API Secret of the resource that wish to authenticate
DCI_CS_URL: The API address (default to https://api.distributed-ci.io)
The recommended way is to retrieve the
dcirc.sh file directly from the https://www.distributed-ci.io or create it yourself in the same folder as your playbook:
#> cat > dcirc.sh <<EOF export DCI_CLIENT_ID=<resource_id> export DCI_API_SECRET=<resource_api_secret> export DCI_CS_URL=https://api.distributed-ci.io EOF
And then run the playbook the following way:
#> source dcirc.sh && ansible-playbook playbook.yml
By now my
dci-test/ folder looks like this:
#> ls -l dci-test/ total 837 -rw-rw-r--. 1 jdoe jdoe 614 Oct 19 14:51 dcirc.sh -rw-rw-r--. 1 jdoe jdoe 223 Oct 19 14:51 playbook.yml
Since the modules of dci-ansible are not part of Ansible, one needs to tell Ansible where to look for the extra modules and callbacks this project is providing. This is done via the Ansible configuratin file.
The Distributed-CI team recommends that you place an
ansible.cfg file in the same folder as your playbook with the following content:
[defaults] library = /usr/share/dci/modules/ module_utils = /usr/share/dci/module_utils/ callback_whitelist = dci callback_plugins = /usr/share/dci/callback/
Note: If you installed the modules from source, please update the pathes accordingly.
By now my
dci-test/ folder looks like this:
#> ls -l dci-test/ total 1014 -rw-rw-r--. 1 jdoe jdoe 177 Oct 19 14:51 ansible.cfg -rw-rw-r--. 1 jdoe jdoe 614 Oct 19 14:51 dcirc.sh -rw-rw-r--. 1 jdoe jdoe 223 Oct 19 14:51 playbook.yml
The following examples will highlight how to interact with a resource. The remoteci resource will be taken as an example. The same pattern applies to all Distributed-CI resources,
- Create a RemoteCI
--- - hosts: localhost tasks: - name: Create a RemoteCI dci_remoteci: name: MyRemoteCI
- List all RemoteCI
--- - hosts: localhost tasks: - name: List all RemoteCIs dci_remoteci:
- Update a RemoteCI
--- - hosts: localhost tasks: - name: Update a RemoteCIs dci_remoteci: id: <remoteciid> name: NewName
- Delete a RemoteCI
--- - hosts: localhost tasks: - name: Delete a RemoteCIs dci_remoteci: id: <remoteciid> state: absent
Real life scenarios examples are available in the samples/ directory.
We'd love to get contributions from you!
If you'd like to report a bug or suggest new ideas you can do it here.
If you'd like to contribute code back to dci-ansible, our code is hosted on Software Factory and then mirrored on Github. Software Factory is Gerrit based, if you don't feel comfortable with the workflow or have any question, feel free to ping someone on IRC.
Before you can run test you need to get familiarized with the dci-dev-env project.
dci-dev-env is a Docker based environment that will deploy a Distributed-CI Control Server API, the UI and more. Once deployed locally, you'll be able to run the test suite against this deployment.
To run the test, ensure the api is running by running
docker ps and then simply run
./run_tests.sh in the tests/ folder
Apache License, Version 2.0 (see LICENSE file)
Email: Distributed-CI Team firstname.lastname@example.org
IRC: #distributed-ci on Freenode