README.md
1# Foreman Ansible Modules 
2
3Ansible modules for interacting with the Foreman API and various plugin APIs such as Katello.
4
5## Documentation
6
7A list of all modules and their documentation can be found at [theforeman.org/plugins/foreman-ansible-modules](https://theforeman.org/plugins/foreman-ansible-modules/).
8
9## Support
10
11### Supported Foreman and plugins versions
12
13Modules should support any currently stable Foreman release and the matching set of plugins.
14Some modules have additional features/arguments that are only applied when the corresponding plugin is installed.
15
16We actively test the modules against the latest stable Foreman release and the matching set of plugins.
17
18### Supported Ansible Versions
19
20The supported Ansible versions are aligned with currently maintained Ansible versions that support Collections (2.8+).
21You can find the list of maintained Ansible versions [here](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status).
22
23### Supported Python Versions
24
25Starting 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.
26
27### Known issues
28
29* Some modules, e.g. `repository_sync` and `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.
30 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.
31 Please make sure to set a high enough `async` value, as otherwise Ansible might abort the execution of the module while there is still a task running on the server, making status reporting fail.
32
33* According to [Ansible documentation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_loops.html), using loop over Ansible resources can leak sensitive data. This applies to all modules, but especially those which require more secrets than the API credentials (`auth_source_ldap`, `compute_resource`, `host`, `hostgroup`, `http_proxy`, `image`, `repository`, `scc_account`, `user`). You can prevent this by using `no_log: yes` on the task.
34
35 eg:
36
37 ```yaml
38 - name: Create compute resources
39 theforeman.foreman.compute_resource:
40 server_url: https://foreman.example.com
41 username: admin
42 password: changeme
43 validate_certs: yes
44 name: "{{ item.name }}"
45 organizations: "{{ item.organizations | default(omit) }}"
46 locations: "{{ item.locations | default(omit) }}"
47 description: "{{ item.description | default(omit) }}"
48 provider: "{{ item.provider }}"
49 provider_params: "{{ item.provider_params | default(omit) }}"
50 state: "{{ item.state | default('present') }}"
51 loop: "{{ compute_resources }}"
52 no_log: yes
53 ```
54
55## Installation
56
57There are currently two ways to use the modules in your setup: install from Ansible Galaxy or via RPM.
58
59### Installation from Ansible Galaxy
60
61You can install the collection from [Ansible Galaxy](https://galaxy.ansible.com/theforeman/foreman) by running `ansible-galaxy collection install theforeman.foreman` (Ansible 2.9 and later) or `mazer install theforeman.foreman` (Ansible 2.8).
62
63After 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.
64
65### Installation via RPM
66
67The collection is also available as `ansible-collection-theforeman-foreman` from the `client` repository on `yum.theforeman.org`.
68
69After installing the RPM, you can use the modules in the same way as when they are installed directly from Ansible Galaxy.
70
71## Installation From Source
72
73For development or testing purposes, you can install the collection from source git repository. For production usage, see the instructions above on installing the latest stable release.
74
75### Installation from Github Repository
76
77With Ansible >= 2.10, you can install from a Github repository (such as this one or your fork):
78
79`ansible-galaxy collection install git+https://github.com/theforeman/foreman-ansible-modules.git`
80
81If you have configured GitHub to use SSH instead of HTTPS, you can do:
82
83`ansible-galaxy collection install git@github.com/theforeman/foreman-ansible-modules.git`
84
85You can also specify a branch to use such as `devel` (below) or a feature branch that you are working with:
86
87`ansible-galaxy collection install git+https://github.com/theforeman/foreman-ansible-modules.git,devel`
88
89To install from a `requirements.yml` file (useful when installing multiple collections) add a snippet to your `requirements.yml` like
90
91```yml
92---
93collections:
94 - name: https://github.com/theforeman/foreman-ansible-modules.git
95 type: git
96 version: devel
97```
98
99And install all specified requirements with `ansible-galaxy install -r requirements.yml`
100
101### Building and Installing the Collection Locally
102
103For all currently supported versions of Ansible (i.e. Ansible >= 2.8, and particularly Ansible < 2.10 where the above approach is not yet supported), you can build the collection locally:
104
105`make dist`
106
107And install it with:
108
109`ansible-galaxy collection install ./theforeman-foreman-*.tar.gz`
110
111## Dependencies
112
113These dependencies are required for the Ansible controller, not the Foreman server.
114
115* [`PyYAML`](https://pypi.org/project/PyYAML/)
116* [`requests`](https://pypi.org/project/requests/)
117* [`ipaddress`](https://pypi.org/project/ipaddress/) for the `subnet` module on Python 2.7
118* `rpm` for the RPM support in the `content_upload` module
119* `debian` for the DEB support in the `content_upload` module
120
121# Foreman Ansible Roles
122
123Roles using the Foreman Ansible Modules to configure Foreman and its plugins.
124
125## Documentation
126
127For individual role documentation, check the README defined at `roles/rolename/README.md`.
128
129### Common Role Variables
130
131- `foreman_server_url`: URL of the Foreman server. If the variable is not specified, the value of environment variable `FOREMAN_SERVER_URL` will be used instead.
132- `foreman_username`: Username accessing the Foreman server. If the variable is not specified, the value of environment variable `FOREMAN_USERNAME` will be used instead.
133- `foreman_password`: Password of the user accessing the Foreman server. If the variable is not specified, the value of environment variable `FOREMAN_PASSWORD` will be used instead.
134- `foreman_validate_certs`: Whether or not to verify the TLS certificates of the Foreman server. If the variable is not specified, the value of environment variable `FOREMAN_VALIDATE_CERTS` will be used instead.
135- `foreman_organization`: Organization where configuration will be applied.
136
){kind=link}