1. Basics
Foreman Ansible allows you to import hosts via Ansible, along with facts about these hosts and reports of their playbook runs. This plugin 2.x series should be compatible with any version of Foreman above 1.17, including 1.17. Foreman Ansible relies on Foreman Remote Execution in order to be able to run playbooks remotely.
Every time you run a playbook or an Ansible module, Foreman will receive facts and a report for the host you have executed it on. If you ran Ansible from Foreman itself, the output of your Ansible run will be saved in our database.
You can define a list of roles to enforce and run arbitrary playbooks on the hosts.
2. Installation
2.1 Ansible callback
In order to make Ansible send us data from the hosts, we set up a callback on your host that runs Ansible. To provide specific installation instructions, please select your Ansible version:
2.2 Plugin
If this is the first plugin you’re installing, please see the plugin repository section to set up the repository first.
You can use foreman-installer to install Foreman Ansible:
# foreman-installer --enable-foreman-plugin-ansible --enable-foreman-proxy-plugin-ansible
To run Ansible playbooks as Job Templates, you will also need Remote Execution:
# foreman-installer --enable-foreman-plugin-remote-execution --enable-foreman-proxy-plugin-remote-execution-ssh
2.3 Inventory
You can use the dynamic inventories feature in Ansible to make your inventory be Foreman, and have host properties and parameters available as Ansible variables in your manifests.
The project is not packaged, but you can find the sources here at ansible/ansible. You will need to setup a config file /etc/ansible/foreman.ini, which you can find in ansible/ansible.
Check Ansible’s dynamic inventory documentation to install it.
3. Configuration
Smart proxies are authenticated by Foreman usually through certificates (found in /etc/foreman-proxy/). Therefore, when it comes to proxies, it is NOT necessary to add them to the setting trusted_hosts.
If you want to use Ansible and submit facts/reports to Foreman, through the callback, you should add whatever hosts (again, except Smart Proxies) you want to submit facts from to the setting trusted_hosts. Change it at Administer > Settings, Auth tab. e.g: If you’re running Ansible from host ‘A’, which SSHs into host ‘B’, you need to add host ‘A’
If the Foreman setting create_new_host_when_facts_are_uploaded (Puppet tab) is true, and $HOSTNAME doesn’t exist in Foreman, it will autocreate that host in Foreman. If it already exists, it will update the facts.
Similarly, the Foreman setting ignore_puppet_facts_for_provisioning (Provisioning tab) is set to false, facts related to interfaces will update the interfaces of $HOSTNAME in Foreman.
There are several Ansible options you can configure under Administer -> Settings -> Ansible.
Configuration for Ansible itself, such as ‘ansible_user’, ‘ansible_become’, etc., can be set on any host via Host parameters, Host group parameters or Global parameters by setting the attributes as explained on the settings description.
By default foreman-ansible relies on the settings of Remote Execution for SSH connection options, like SSH user and password or the SSH key passphrase.
4. Usage
Run ansible on your hosts and the callback will send everything to Foreman automatically. Here’s a quick gif of what registering a new host in Foreman looks like.
After a host is registered, you should be able to see facts and reports for a host
4.1.1 Importing Roles
Ansible roles can be imported from a smart proxy that has ‘Ansible’ feature or from ‘/etc/ansible/roles’ on your Foreman host. A list of all roles already imported into Foreman can be accessed through ‘Configure’ in the main menu. You can select the source for import from the dropdown on the right.
You will be presented with a list of possible changes. You can remove the Ansible roles from Foreman that are obsolete and you can import new ones.
4.1.2 Importing Variables
Similar to Ansible roles, variables in these roles can be imported in the same fashion. Go to ‘Configure > Ansible Variables’ to find a list of variables already imported. When you trigger a new import of Ansible variables, if the variables belong to a role that has not been imported yet, it will be automatically imported alongside the Ansible variable.
You will be presented with a list of possible changes. You can remove the Ansible roles from Foreman that are obsolete and you can import new ones.
Variables are imported into Foreman as Lookup Values, hence you may use them exactly like you use Puppet Smart Class Parameters or Smart Variables. Smart Matchers are available for use too. Find more information about how to override Ansible variables in this section of the manual.
4.2 Selecting roles for a host
Ansible roles can be assigned to a host on ‘Ansible Roles’ tab on the host’s edit page. It is also possible to inherit Ansible roles form a host group.
After your host is provisioned and calls home (by using foreman_url('built') in a template), Foreman will do an initial Ansible run to configure the host according to the applicable roles for it. Since Foreman cannot know how long it will take until the host comes back online after the OS is installed and rebooted, Foreman will make Ansible timeout for 5 minutes. This is configurable under Administer > Settings, ‘Post-provision timeout’ or on a per-host basis by overriding the setting with a parameter.
Inherited roles are added automatically upon host group change and the select interface disables direct removal of such items.
Host group edit form contains very similar tab where you can pre-configure selection of Ansible roles for hosts.
4.3 Running Ansible Roles
To run the playbook with the roles selected, click on the ‘play Ansible roles’ button and Foreman will run a playbook on the background. Logs for this playbook can be found under the regular Foreman log, usually /var/log/foreman/production.log
You can also select multiple hosts on the hosts index page, and run the playbook for their Ansible roles by clicking on this button:
Alternatively, you can run the playbook for all Ansible roles applicable to hosts in a host group by clicking on the Play roles button on the Host groups page.
4.4 Running Ansible Playbooks (Job Templates)
To run a playbook:
- On the Host page, click on Scheduled Remote Job, choose a Job Template, and submit it
- On the Host list, select multiple hosts, then click on “Select Action” -> “Scheduled Remote Job”
- On the Job Templates list, look for a Job Template and click on “Run”, then submit it
For example, here is how to run ‘yum install -y vim’ once, on one host.
And here is how to schedule a playbook run in the future on multiple hosts:
For more information about scheduled jobs, check out the Foreman Remote Execution manual
4.5 Overriding Ansible Variables
Ansible variables are referenced in playbooks and templates with the syntax “{{ myvariable }}”. For example:
template: src=foo.cfg.j2 dest={{ remote_install_path }}/foo.cfg
uses the ‘remote_install_path’ variable. You can use Foreman to override these variables. The variables will only be overridden if you run your roles from Foreman, as Foreman sends an inventory with a dictionary containing variable names and values when it runs Ansible roles.
There are three ways to override an Ansible variable:
- Import the variable following this section of the manual. Once the variable is imported, you may provide a type and a default value:
and you can also specify Smart Matchers to specify default matching values for certain Host groups, FQDNs, Operating Systems, or Domains.
-
Set the variable you want to override as a Host Parameter, Host Group Parameter, or Global Parameter. The ‘name’ of the parameter would be the name of the Ansible variable you want to override, and the ‘value’ of the parameter the value of the variable. Notice variables sent this way will always have the type String. If you want to override variables that should have other types, use method 1.
-
Another way to override the variable is to set it as a Job Template input. For example, let’s create a Job Template containing a playbook with the variable {{ command }}.
Then set a Job Template Input with the name of the variable “command”:
As you see, the variable “command” is now available to be set on every Job Template run.
You can override this variable every time you run the Job Template by setting the variable as Input. This takes precedence over Host Parameters.
5. Help
Please follow our standard procedures and contacts.
5.1 Troubleshooting
Errors regarding the import of facts and reports will show up on /var/log/foreman/production.log of your Foreman host.
If you find a bug, please file it in Redmine.
See the troubleshooting section in the Foreman manual for more info.
5.2 Contributing
Follow the same process as Foreman for contributing.
Sources at github.com/theforeman/foreman_ansible