From 9ff9de4bd762f2faf160267edb24b795b7c68ab6 Mon Sep 17 00:00:00 2001 From: Dusan Matejka Date: Wed, 10 Jun 2020 15:28:50 +0200 Subject: [PATCH] reflected collection documentation with now included roles --- CHANGELOG.md | 2 + CODE_OF_CONDUCT.md | 10 +- CONTRIBUTING.md | 169 +++++++++++++++++++++-------- README.md | 201 ++++++++++++++--------------------- docs/PUBLISHING_TO_GALAXY.md | 15 +++ galaxy.yml | 1 + 6 files changed, 233 insertions(+), 165 deletions(-) create mode 100644 docs/PUBLISHING_TO_GALAXY.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 825608569..c2a324c86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Zabbix Collection Changes +## devel + ## 0.1.0 - Initial migration of Zabbix content from Ansible core (2.9 / devel), including content: - **Connection Plugins**: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 26e4badb1..4fa46f96c 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -55,8 +55,14 @@ further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at github@werner-dijkerman.nl. All -complaints will be reviewed and investigated and will result in a response that +reported by contacting one of the project maintainers at: +* d3defi@gmail.com +* sky.jokerxx@gmail.com +* github@werner-dijkerman.nl + +Or Ansible project directly at codeofconduct@ansible.com. + +All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1571f1fcf..e3bf8bc67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,77 +1,156 @@ -# Contributing to this role +# Contribution guidelines **Table of contents** -- [Contributing to this role](#contributing-to-this-role) +- [Contribution guidelines](#contribution-guidelines) * [Contributing](#contributing) - * [(local) Development](#-local--development) - + [Requirements](#requirements) - + [Execution](#execution) -- [Other](#other) + * [Coding guidelines](#coding-guidelines) + + [Zabbix roles](#zabbix-roles) + + [Zabbix modules](#zabbix-modules) + * [Testing and Development](#testing-and-development) + + [Testing Zabbix roles](#testing-zabbix-roles) + + [Testing Zabbix modules](#testing-zabbix-modules) +- [Additional information](#additional-information) * [Virtualenv](#virtualenv) * [Links](#links) -Thank you very much for making time to improve this Ansible role. +Thank you very much for taking time to improve this Ansible collection. We appreciate your every contribution. Please make sure you are familiar with the content presented in this document to avoid any delays during reviews or merge. + +Please note that this project is released with following codes of conduct and by participating in the project you agree to abide by them: +* [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md) +* [Community Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html) + +If you are interested in joining us as a maintainer, please open an issue. ## Contributing -Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. [Contributor Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html). +1. Fork this repository with community Zabbix collection. +2. Create a new branch and apply your changes to it. In addition to that: + 1. Ensure that any changes you introduce to this collection are reflected in the documentation. + 2. Should your change introduce a new feature, module or bug fix, note it under `devel` section in [CHANGELOG](CHANGELOG.md). + 3. Include tests with your contribution to ensure that future pull requests will not break your functionality. + 4. Make sure that tests succeed. +3. Push the branch to your forked repository. +4. Submit a new pull request into this collection. -1. Fork the repo +*Notes:* +* Pull requests that fail during the tests will not be merged. If you have trouble narrowing down cause of a failure and would like some help, do not hesitate to ask for it in comments. +* If you plan to propose an extensive feature or breaking change, please open an issue first. This allows collection maintainers to comment on such change in advance and avoid possible rejection of such contribution. -2. Create a branch and apply your changes to this branch. +## Coding guidelines - a. Make sure you have updated the documentation when adding new variables; - - b. Don't forget to add/update tests so we can test the functionality during each Pull Request; - - c. Make sure the tests succeed. +Style guides are important because they ensure consistency in the content, look, and feel of a book or a website. Any contributions to this collection must adhere to the following rules: -3. Push the branch to your fork and submit a pull request. +* [Ansible style guide](http://docs.ansible.com/ansible/latest/dev_guide/style_guide/). +* Use "Ansible" when referring to the product and ``ansible`` when referring to the command line tool, package and so on. -**Note** +### Zabbix roles -Pull Requests that fail during the tests will not be merged. +* Playbooks should be written in multi-line YAML format using ``key: value``. + * The form ``key=value`` is suitable for ``ansible`` ad-hoc execution, not for ``ansible-playbook``. +* Every task should always have a ``name:`` keyword associated with it. -## Coding Guidelines +### Zabbix modules -Style guides are important because they ensure consistency in the content, look, and feel of a book or a website. +These rules are required for any contributions proposing a new Zabbix module or updating an existing one. Modules should: -* [Ansible Style Guide](http://docs.ansible.com/ansible/latest/dev_guide/style_guide/) -* It's "Ansible" when referring to the product and ``ansible`` when referring to the command line tool, package, etc -* Playbooks should be written in multi-line YAML with ``key: value``. The form ``key=value`` is only for ``ansible`` ad-hoc, not for ``ansible-playbook``. -* Tasks should always have a ``name:`` +* Be compatible with [currently supported Zabbix releases](https://www.zabbix.com/life_cycle_and_release_policy). +* Include the same set of general options as other Zabbix modules: + * In `DOCUMENTATION` block via `extends_documentation_fragment` keyword. + * In module `argument_spec` as a set of module parameters. +* Implement proper logout mechanism as other modules do. +* Use the same version of `zabbix-api` library as defined in collection requirements. +* Comply with [Ansible module best practices](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html). -## (local) Development +## Testing and Development -This role makes use of Molecule to test the execution of the role and verify it. In the root of the repository https://github.com/dj-wasabi/ansible-ci-base, a file named `requirements.txt` exists and contains the versions used by the tests. +It is recommended to use Docker for the testing as this repository is utilizing it for its own CI. Read [Docker installation guide](https://docs.docker.com/install/) for more information. -### Requirements +Make sure you start your work on the current state of the repository with `master` branch up to date. The best way to both try new changes and run shipped tests is by cloning the repository to Ansible project: -You can install them with the following command: +```bash +cd / +mkdir -p collections/ansible_collections/community +git clone git@github.com:/community.zabbix.git collections/ansible_collections/community/zabbix +``` +Functionality can be verified by looking at the documentation of a module: +```bash +ansible-doc community.zabbix.zabbix_host ``` -pip install -r requirements.txt + +Once this is done, you can reference modules and roles from testing playbook likes this: + +```yaml +- hosts: myserver + roles: + - role: community.zabbix.zabbix_agent + zabbix_agent_server: 10.0.0.1 + ... + + tasks: + - name: Configure Zabbix host + community.zabbix.zabbix_host: + server_url: http://10.0.0.1/ + ... + delegate_to: localhost ``` -Once the dependencies are installed, please install Docker as Molecule is configured in this repository to create Docker containers. See [this](https://docs.docker.com/install/) link to install Docker on your system. +### Testing Zabbix roles + +*This section is subject to change as our CI regarding roles is being reworked and may not work for you right now!* -### Execution +Roles make use of [Molecule](https://molecule.readthedocs.io/en/latest/) to verify and test the execution of each role. In order to start testing with Molecule, you need to install the required dependencies. Requirements file can be found in the root of the [dj-wasabi/ansible-ci-base](https://github.com/dj-wasabi/ansible-ci-base) repository. -Once everything is installed, you can validate your changes by executing: +It is recommended to create a [new Python virtual environment](#virtualenv) for this to not clutter your global Python installation. First, install the dependencies: + +```bash +pip install -r requirements.txt ``` + +Note that Docker is required when testing roles as Molecule is configured to use it. Once everything is installed, validate your role changes with: + +```bash molecule test ``` -It should run without any issues. +### Testing Zabbix modules + +Modules are tested via `ansible-test` command. Configurations for integration and sanity tests for the command are contained within `tests` directory. Refer to the [official documentation](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html) for introduction to module integration testing within Ansible. Please note that this may fail if you get your directory structure wrong. If this happens, please see the start of [Testing and Development](#testing-and-development) regarding the placement of the collection. -# Other +Running test suites locally requires a few dependencies to be installed. Same as for the roles, it is recommended to use [Python virtual environment](#virtualenv): + +```bash +pip install docker-compose zabbix-api +``` + +Integration test suite for modules can be run with the commands below: + +```bash +export zabbix_version=X.Y +export zabbix_port=XY +docker-compose up -d +ansible-test integration -v --color --retry-on-error --continue-on-error --diff +docker-compose down +``` +*Notes*: +* `zabbix_version=X.Y` will be expanded to Docker image `ubuntu-X.Y-latest` +* `zabbix_port=XY` is the mapping port for the container (local port 8080 will be mapped to port XY on the zabbix-web container). As of now, this needs to be set explicitly as different versions of zabbix-web docker images are exposing different ports. +* Details for both variables and values that are in use can be read from [ansible-test.yml](.github/workflows/ansible-test.yml). + +Sanity test suite for the modules can be run with the commands: + +```bash +ansible-test sanity -v --color --docker --python 3.6 +``` + +# Additional information ## Virtualenv -Suggestion is to create a virtualenv so you won't have issues with other projects. +It is recommended to use virtualenv for development and testing work to prevent any conflicting dependencies with other projects. -Some web pages describing virtualenvs: +A few resources describing virtualenvs: * http://thepythonguru.com/python-virtualenv-guide/ * https://realpython.com/python-virtual-environments-a-primer/ @@ -79,10 +158,14 @@ Some web pages describing virtualenvs: ## Links -[Molecule](https://molecule.readthedocs.io/) - -[Ansible](https://www.ansible.com/) - -[Molecule V2 with your own role](https://werner-dijkerman.nl/2017/09/05/using-molecule-v2-to-test-ansible-roles/) - -**End note**: Have fun making changes. If a feature helps you, then others find it helpful too and I will happily have it merged. +* [Ansible](https://www.ansible.com/) +* [Ansible style guide](http://docs.ansible.com/ansible/latest/dev_guide/style_guide/) +* [Ansible module best practices](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html) +* [Integration testing with `ansible-test`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html) +* [Docker installation guide](https://docs.docker.com/install/) +* [Molecule](https://molecule.readthedocs.io/) +* [Molecule V2 with your own role](https://werner-dijkerman.nl/2017/09/05/using-molecule-v2-to-test-ansible-roles/) +* [dj-wasabi/ansible-ci-base](https://github.com/dj-wasabi/ansible-ci-base) +* [Current Zabbix releases](https://www.zabbix.com/life_cycle_and_release_policy) + +**End note**: Have fun making changes. If a feature helps you, others may find it useful as well and we will be happy to merge it. diff --git a/README.md b/README.md index 6d8db2412..d5cd5e7b9 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,64 @@ # Zabbix collection for Ansible -![](https://github.com/ansible-collections/community.zabbix/workflows/CI/badge.svg) +![CI](https://github.com/ansible-collections/community.zabbix/workflows/CI/badge.svg) This repo hosts the `community.zabbix` Ansible Collection. The collection includes a variety of Ansible content to help automate the management of resources in Zabbix. -## Supported Zabbix versions - -As a main priority, this collection aims to cover all of the currently supported Zabbix releases, which are noted on the [Zabbix Life Cycle & Release Policy](https://www.zabbix.com/life_cycle_and_release_policy) page. -Other versions are supported too, but not as strictly (e.g. we won't be testing new changes against them). - -If you find any inconsistencies with the version of Zabbix you are using, feel free to open a pull request or an issue and we will try to address it as soon as possible. -In case of pull requests, please make sure that your changes won't break any existing functionality for currently supported Zabbix releases. - ## Included content Click on the name of a plugin or module to view that content's documentation: - - **Connection Plugins**: - - **Filter Plugins**: - **Inventory Source**: - - [zabbix](https://github.com/ansible-collections/community.zabbix/blob/master/scripts/inventory/zabbix.py) - - **Callback Plugins**: - - **Lookup Plugins**: + - [zabbix](scripts/inventory/zabbix.py) - **Modules**: - - [zabbix\_action](https://docs.ansible.com/ansible/latest/modules/zabbix_action_module.html) - - [zabbix\_group\_info](https://docs.ansible.com/ansible/latest/modules/zabbix_group_info_module.html) - - [zabbix\_group](https://docs.ansible.com/ansible/latest/modules/zabbix_group_module.html) - - zabbix\_host\_events\_info - - [zabbix\_host\_info](https://docs.ansible.com/ansible/latest/modules/zabbix_host_info_module.html) - - [zabbix\_hostmacro](https://docs.ansible.com/ansible/latest/modules/zabbix_hostmacro_module.html) - - [zabbix\_host](https://docs.ansible.com/ansible/latest/modules/zabbix_host_module.html) - - [zabbix\_maintenance](https://docs.ansible.com/ansible/latest/modules/zabbix_maintenance_module.html) - - [zabbix\_map](https://docs.ansible.com/ansible/latest/modules/zabbix_map_module.html) - - [zabbix\_mediatype](https://docs.ansible.com/ansible/latest/modules/zabbix_mediatype_module.html) - - [zabbix\_proxy](https://docs.ansible.com/ansible/latest/modules/zabbix_proxy_module.html) - - [zabbix\_screen](https://docs.ansible.com/ansible/latest/modules/zabbix_screen_module.html) - - zabbix\_service - - zabbix\_template\_info - - [zabbix\_template](https://docs.ansible.com/ansible/latest/modules/zabbix_template_module.html) - - zabbix\_user\_info - - zabbix\_user - - zabbix\_valuemap - -## Installation and Usage + - [zabbix_action](https://docs.ansible.com/ansible/latest/modules/zabbix_action_module.html) + - [zabbix_group_info](https://docs.ansible.com/ansible/latest/modules/zabbix_group_info_module.html) + - [zabbix_group](https://docs.ansible.com/ansible/latest/modules/zabbix_group_module.html) + - [zabbix_host_events_info](plugins/modules/zabbix_host_events_info.py) + - [zabbix_host_info](https://docs.ansible.com/ansible/latest/modules/zabbix_host_info_module.html) + - [zabbix_hostmacro](https://docs.ansible.com/ansible/latest/modules/zabbix_hostmacro_module.html) + - [zabbix_host](https://docs.ansible.com/ansible/latest/modules/zabbix_host_module.html) + - [zabbix_maintenance](https://docs.ansible.com/ansible/latest/modules/zabbix_maintenance_module.html) + - [zabbix_map](https://docs.ansible.com/ansible/latest/modules/zabbix_map_module.html) + - [zabbix_mediatype](https://docs.ansible.com/ansible/latest/modules/zabbix_mediatype_module.html) + - [zabbix_proxy](https://docs.ansible.com/ansible/latest/modules/zabbix_proxy_module.html) + - [zabbix_screen](https://docs.ansible.com/ansible/latest/modules/zabbix_screen_module.html) + - [zabbix_service](plugins/modules/zabbix_service.py) + - [zabbix_template_info](plugins/modules/zabbix_template_info.py) + - [zabbix_template](https://docs.ansible.com/ansible/latest/modules/zabbix_template_module.html) + - [zabbix_user_info](plugins/modules/zabbix_user_info.py) + - [zabbix_user](plugins/modules/zabbix_user.py) + - [zabbix_valuemap](plugins/modules/zabbix_valuemap.py) + - **Roles**: + - [zabbix_agent](docs/ZABBIX_AGENT_ROLE.md) + - [zabbix_javagateway](docs/ZABBIX_JAVAGATEWAY_ROLE.md) + - [zabbix_proxy](docs/ZABBIX_PROXY_ROLE.md) + - [zabbix_server](docs/ZABBIX_SERVER_ROLE.md) + - [zabbix_web](docs/ZABBIX_WEB_ROLE.md) + +## Installation + +### Requirements + +Each component in this collection requires additional dependencies. Review components you are interested in by visiting links present in the [Included content](#included-content) section. + +This is especially important for some of the Zabbix roles that require you to **install additional standalone roles** from Ansible Galaxy. + +For the majority of modules, however, you can get away with just: + +```bash +pip install zabbix-api +``` ### Installing the Collection from Ansible Galaxy Before using the Zabbix collection, you need to install it with the Ansible Galaxy CLI: - ansible-galaxy collection install community.zabbix +```bash +ansible-galaxy collection install community.zabbix +``` You can also include it in a `requirements.yml` file and install it via `ansible-galaxy collection install -r requirements.yml`, using the format: @@ -61,110 +69,63 @@ collections: version: v0.1.0 ``` -### Using modules from the Zabbix Collection in your playbooks +## Usage -You can either call modules by their Fully Qualified Collection Namespace (FQCN), like `community.zabbix.zabbix_host`, or you can call modules by their short name if you list the `community.zabbix` collection in the playbook's `collections`, like so: +*Please note that these are not working examples. For documentation on how to use content included in this collection, refer to the links in the [Included content](#included-content) section.* + +To use a module or role from this collection, reference them with their Fully Qualified Collection Namespace (FQCN) like so: ```yaml --- -- hosts: localhost - gather_facts: false - connection: local - - collections: - - community.zabbix +- name: Using Zabbix collection + hosts: localhost + roles: + - role: community.zabbix.zabbix_agent + zabbix_agent_server: zabbix.example.com + ... tasks: - - name: Ensure host is monitored by Zabbix. - zabbix_host: + - name: Ensure host is monitored by Zabbix + community.zabbix.zabbix_host: server_url: https://zabbix.example.com - login_user: username - login_password: password - host_name: '{{ inventory_hostname }}' - host_groups: - - Linux servers - link_templates: - - Template Module ICMP Ping - status: enabled - state: present - interfaces: - - type: 1 - main: 1 - dns: '{{ inventory_hostname }}' - proxy: zbx-proxy.example.com - macros: - - macro: SITE - value: '{{ ansible_domain }}' - delegate_to: localhost + ... ``` -For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README. - -## Testing and Development - -### Testing with `ansible-test` - -As of right now, `ansible-test` will fail unless executed in a path containing a specific component. Easiest way to start working on this collection is to clone it to the `~/ansible_collections/community/zabbix` directory. To use this modified version of the collection in playbooks, set [`COLLECTIONS_PATHS`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths) to the `~/ansible_collections` directory. - -Running test suites locally requires few dependencies (use virtualenv): - - pip install docker-compose zabbix-api - -The `tests` directory contains configuration for running sanity and integration tests using [`ansible-test`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html). - -Collection's integration test suite can be run with the commands. -`zabbix_version=X.Y` will be expanded to X.Y-latest and `zabbix_port=XY` is the mapping port for the container. -The port number that can be specified for `zabbix_port` depends on the version of Zabbix. -Check the [ansible-test](https://github.com/ansible-collections/community.zabbix/blob/master/.github/workflows/ansible-test.yml) for details on the port numbers that can be specified for `zabbix_port`. +Or you include collection name `community.zabbix` in the playbook's `collections` element, like this: - export zabbix_version=X.Y - export zabbix_port=XY - docker-compose up -d - ansible-test integration -v --color --retry-on-error --continue-on-error --diff - docker-compose down - -Collection's sanity test suite can be run with the commands: - - ansible-test sanity -v --color --docker --python 3.6 - -### Developing new Zabbix modules +```yaml +--- +- name: Using Zabbix collection + hosts: localhost + collections: + - community.zabbix -New modules must adhere to these rules: + roles: + - role: zabbix_agent + zabbix_agent_server: zabbix.example.com + ... -* Features and modules must be compatible with [currently supported Zabbix releases](https://www.zabbix.com/life_cycle_and_release_policy). -* New logic for existing modules or new modules are submitted with integration tests included. -* Must include the same set of general options as other zabbix modules both in `DOCUMENTATION` block (via document fragment) and `argument_spec`. -* Must implement proper logout mechanism. -* Use the same version of `zabbix-api` library as the other modules. -* Comply with [Ansible module best practices](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html). + tasks: + - name: Ensure host is monitored by Zabbix + zabbix_host: + server_url: https://zabbix.example.com + ... +``` -## Publishing New Versions +## Supported Zabbix versions -The current process for publishing new collection versions is manual, and requires a user who has access to the `community.zabbix` namespace on Ansible Galaxy to publish the build artifact. +As a main priority, this collection aims to cover all of the currently supported Zabbix releases, which are noted on the [Zabbix Life Cycle & Release Policy](https://www.zabbix.com/life_cycle_and_release_policy) page. +Other versions are supported too, but not as strictly (changes would not be actively tested against them). - 1. Ensure `CHANGELOG.md` contains all the latest changes. - 2. Update `galaxy.yml` and this README's `requirements.yml` example with the new `version` for the collection. - 3. Tag the version in Git and push to GitHub. - 4. Run the following commands to build and release the new version on Galaxy: +If you find any inconsistencies with the version of Zabbix you are using, feel free to open a pull request or an issue and we will try to address it as soon as possible. +In case of pull requests, please make sure that your changes will not break any existing functionality for currently supported Zabbix releases. - ``` - ansible-galaxy collection build - ansible-galaxy collection publish ./community-zabbix-$VERSION_HERE.tar.gz - ``` +## Contributing -After the version is published, verify it exists on the [Zabbix Collection Galaxy page](https://galaxy.ansible.com/community/zabbix). +See [CONTRIBUTING](CONTRIBUTING.md) for more information about how to contribute to this repository. ## License GNU General Public License v3.0 or later -See LICENCE to see the full text. - -## Contributing - -Any contribution is welcome and we only ask contributors to: - -* Provide at least integration tests for any contribution. -* Create an issues for any significant contribution that would change a large portion of the code base. - -If you are interested in joining us as a maintainer, either open an issue or contact @D3DeFi or @sky-joker directly :) +See [LICENSE](LICENSE) to see the full text. diff --git a/docs/PUBLISHING_TO_GALAXY.md b/docs/PUBLISHING_TO_GALAXY.md new file mode 100644 index 000000000..b0dae6b85 --- /dev/null +++ b/docs/PUBLISHING_TO_GALAXY.md @@ -0,0 +1,15 @@ +# Publishing New Versions + +The current process for publishing new collection versions is manual, and requires a user who has access to the `community.zabbix` namespace on Ansible Galaxy to publish the build artifact. + + 1. Ensure `CHANGELOG.md` contains all the latest changes. + 2. Update `galaxy.yml` file and `requirements.yml` example in `README.md` with the new `version` for the collection. + 3. Tag the version in Git and push to GitHub. + 4. Run the following commands to build and release the new version on Galaxy: + + ``` + ansible-galaxy collection build + ansible-galaxy collection publish ./community-zabbix-$VERSION_HERE.tar.gz + ``` + +After the version is published, verify it exists on the [Zabbix Collection Galaxy page](https://galaxy.ansible.com/community/zabbix). diff --git a/galaxy.yml b/galaxy.yml index 824266292..acc1315f2 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -5,6 +5,7 @@ readme: README.md authors: - Dusan Matejka (@D3DeFi) - sky-joker (@sky-joker) +- Werner Dijkerman (@dj-wasabi) description: Collection allowing to configure resources in Zabbix monitoring system license_file: LICENSE tags: