-
Notifications
You must be signed in to change notification settings - Fork 25
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
12 additions
and
60 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,30 @@ | ||
| # Foreman Ansible Modules  | ||
| # Red Hat Satellite Ansible Collection | ||
|
|
||
| Ansible modules for interacting with the Foreman API and various plugin APIs such as Katello. | ||
| Ansible modules for interacting with the Satellite API. | ||
|
|
||
| ## Documentation | ||
|
|
||
| A list of all modules and their documentation can be found at [theforeman.org/plugins/foreman-ansible-modules](https://theforeman.org/plugins/foreman-ansible-modules/). | ||
| The documentation for this collection can be found in the [Satellite documentation](https://access.redhat.com/documentation/en-us/red_hat_satellite/). | ||
|
|
||
| ## Support | ||
|
|
||
| ### Supported Foreman and plugins versions | ||
|
|
||
| Modules should support any currently stable Foreman release and the matching set of plugins. | ||
| Some modules have additional features/arguments that are only applied when the corresponding plugin is installed. | ||
|
|
||
| We actively test the modules against the latest stable Foreman release and the matching set of plugins. | ||
|
|
||
| ### Supported Ansible Versions | ||
|
|
||
| The supported Ansible versions are aligned with currently maintained Ansible versions. You can find the list of maintained Ansible versions [here](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status). Older Ansible versions (Ansible >= 2.3) should work but are not tested. | ||
|
|
||
| As we're using Ansible's [documentation fragment](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#documentation-fragments) feature, that was introduced in Ansible 2.8, `ansible-doc` prior to 2.8 won't be able to display the module documentation, but the modules will still run fine with `ansible` and `ansible-playbook`. | ||
|
|
||
| ### Supported Python Versions | ||
|
|
||
| Starting with Ansible 2.7, Ansible only supports Python 2.7 and 3.5 (and higher). These are also the only Python versions we develop and test the modules against. | ||
|
|
||
| ### Known issues | ||
|
|
||
| * Some modules, e.g. `katello_sync` and `katello_content_view_version`, trigger long running tasks on the server side. It might be beneficial to your playbook to wait for their completion in an asynchronous manner. | ||
| As Ansible has facilities to do so, the modules will wait unconditionally. See the [Ansible documentation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_async.html) for putting tasks in the background. | ||
|
|
||
| * `foreman_compute_resource` can leak sensitive data if used within a loop. According to [ansible documentation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_loops.html), using loop over Ansible resources can leak sensitive data. You can prevent this by using `no_log: yes` on the task. | ||
|
|
||
| eg: | ||
| ```yaml | ||
| - name: Create compute resources | ||
| foreman_compute_resource: | ||
| server_url: https://foreman.example.com | ||
| username: admin | ||
| password: changeme | ||
| validate_certs: yes | ||
| name: "{{ item.name }}" | ||
| organizations: "{{ item.organizations | default(omit) }}" | ||
| locations: "{{ item.locations | default(omit) }}" | ||
| description: "{{ item.description | default(omit) }}" | ||
| provider: "{{ item.provider }}" | ||
| provider_params: "{{ item.provider_params | default(omit) }}" | ||
| state: "{{ item.state | default('present') }}" | ||
| loop: "{{ compute_resources }}" | ||
| no_log: yes | ||
| ``` | ||
| For support questions around this collection, please open a ticket on the [Red Hat Customer Portal](https://access.redhat.com). | ||
|
|
||
| ## Installation | ||
|
|
||
| There are currently two ways to use the modules in your setup: install from Ansible Galaxy or via RPM. | ||
| You can install this collection directly from Automation Hub or via RPMs provided by Red Hat. | ||
|
|
||
| ### Installation from Ansible Galaxy | ||
| The GitHub repository serves as the source for the release and should not be used for direct installation and consumption of the collection. | ||
|
|
||
| You can install the collection from [Ansible Galaxy](https://galaxy.ansible.com/theforeman/foreman) by running `mazer install theforeman.foreman` (Ansible 2.8) or `ansible-galaxy collection install theforeman.foreman` (Ansible 2.9 and later). | ||
| ### Installation from Automation Hub | ||
|
|
||
| After the installation, the modules are available as `theforeman.foreman.<module_name>`. Please see the [Using Ansible collections documentation](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for further details. | ||
| You can install the collection with `ansible-galaxy collection install redhat.satellite` (Ansible 2.9 and later). | ||
|
|
||
| ### Installation via RPM | ||
|
|
||
| The collection is also available as `ansible-collection-theforeman-foreman` from the `client` repository on `yum.theforeman.org` starting with Foreman 1.24. | ||
|
|
||
| After installing the RPM, you can use the modules in the same way as when they are installed directly from Ansible Galaxy. | ||
|
|
||
| ## Dependencies | ||
| The collection is also available as `ansible-collection-redhat-satellite` in the Satellite repository. | ||
|
|
||
| These dependencies are required for the Ansible controller, not the Foreman server. | ||
| ## Upstream | ||
|
|
||
| * `PyYAML` | ||
| * [`apypie`](https://pypi.org/project/apypie/) | ||
| * [`ipaddress`](https://pypi.org/project/ipaddress/) for the `foreman_subnet` module on Python 2.7 | ||
| * `rpm` for the RPM support in the `katello_upload` module | ||
| * `debian` for the DEB support in the `katello_upload` module | ||
| This collection is based on the [`theforeman.foreman`](https://github.com/theforeman/foreman-ansible-modules) community collection for Foreman and Katello. | ||
| If possible, any contributions should go directly to `theforeman.foreman` from where they will flow back into this collection. |