1. Introduction to Salt
This guide describes how to use Salt for configuration management in Foreman. This guide contains information about how to install the Salt plugin, how to integrate Foreman with an existing Salt Master, and how to configure hosts with Salt.
Note
|
Salt offers two distinct modes of operation: Clientless by using SSH or the Salt Minion client software. |
-
The official Salt documentation is a good entry point when starting with Salt.
-
You can download the Salt packages from the official Salt package repository.
2. Salt architecture
You need a Salt Master that either runs on your Foreman server or Smart Proxy server with the Salt plugin enabled. You can also use an existing Salt Master by installing and configuring the relevant Smart Proxy features on the existing Salt Master host.
For more information on installing a Salt Master, consult the official Salt documentation. Alternatively, use the bootstrap instructions found in the official Salt package repository.
-
Hosts are referred to as Salt Minions.
-
Information in form of key-value pairs gathered from Salt Minions is referred to as Salt Grains.
-
Configuration templates are referred to as Salt States.
-
Bundles of Salt States are referred to as Salt Environments.
Use the same Salt version on the Salt Master as you are using on your Salt Minions. You can use content management in Foreman to provide hosts with the correct version of the Salt Minion client software.
Port | Protocol | Service | Required For |
---|---|---|---|
4505 and 4506 |
TCP |
HTTPS |
Salt Master to Salt Minions |
9191 |
TCP |
HTTPS |
Salt API |
3. Installing the Salt plugin
To configure hosts with Salt, you must install the Salt plugin.
-
On your Foreman server, install the Salt plugin:
# foreman-installer \ --enable-foreman-plugin-salt \ --enable-foreman-proxy-plugin-salt
4. Configuring Salt
After you have installed the Salt plugin, you need to connect it to a Salt Master. This is required when adding Salt support to an existing Foreman installation, when adding an existing Salt Master to Foreman, or when setting up Salt on Smart Proxy.
Perform all actions on your Salt Master unless noted otherwise. This is either your Foreman server or Smart Proxy server with Salt enabled.
4.1. Configuring Salt on Foreman server
You need to configure Foreman server to use the Salt plugin.
-
On your Foreman server, extend the
/etc/sudoers
file to allow theforeman-proxy
user to run Salt:Cmd_Alias SALT = /usr/bin/salt, /usr/bin/salt-key foreman-proxy ALL = NOPASSWD: SALT Defaults:foreman-proxy !requiretty
-
On your Foreman server, add a user called
saltuser
to access the Salt API:# adduser --no-create-home --shell /bin/false --home-dir / saltuser # passwd saltuser
Enter the password for the Salt user twice.
NoteThe command
adduser saltuser -p password
does not work. Using it prevents you from importing Salt States.
4.2. Authenticating Salt Minions using Salt autosign Grains
Configure Foreman to automatically accept Salt Minions using Salt autosign Grains.
-
Add the reactor to the
salt/auth
event. -
Copy the Salt runners into your
file_roots
runners directory. The directory depends on your/etc/salt/master
config. If it is configured to use/srv/salt
, create the runners folder/srv/salt/_runners
and copy the Salt runners into it.# mkdir -p /srv/salt/_runners # cp /usr/share/foreman-proxy/salt/runners/* /srv/salt/_runners/
-
Restart the Salt Master service:
# systemctl restart salt-master
-
Enable the Salt reactors and runners in your Salt Environment:
# salt-run saltutil.sync_all
4.3. Authenticating Salt Minions using host names
Configure Foreman to authenticate Salt Minions based on their host names.
This relies on the autosign.conf
file that stores the host names of Salt Minions the Salt Master accepts.
-
On your Salt Master, add the
foreman-proxy
user that is running Salt to theroot
user group:# usermod -a -G foreman-proxy root
-
On your Salt Master, enable the
autosign.conf
file in/etc/salt/master
:autosign_file: /etc/salt/autosign.conf permissive_pki_access: True
-
On your Salt Master, create the
/etc/salt/autosign.conf
file and set appropriate ownership and permissions:# touch /etc/salt/autosign.conf # chown root:foreman-proxy /etc/salt/autosign.conf # chmod 660 /etc/salt/autosign.conf
4.4. Enabling Salt Grain uploads
Hosts running the Salt Minion client software can upload Salt Grains to Foreman server or Smart Proxy server. Salt Grains are collected system properties, for example the operating system or IP address of a Salt Minion.
-
On your Salt Master, edit
/etc/salt/foreman.yaml
::proto: https :host: foreman.example.com :port: 443 :ssl_ca: "/etc/puppetlabs/puppet/ssl/ssl_ca.pem" :ssl_cert: "/etc/puppetlabs/puppet/ssl/client_cert.pem" :ssl_key: "/etc/puppetlabs/puppet/ssl/client_key.pem" :timeout: 10 :salt: /usr/bin/salt :upload_grains: true
4.5. Configuring the Salt API
Configure the Salt API on your Salt Master.
-
On your Salt master, edit
/etc/foreman-proxy/settings.d/salt.yml
::use_api: true :api_auth: pam :api_url: https://foreman.example.com:9191 :api_username: saltuser :api_password: password
Ensure to use the password of the previously created
saltuser
.
4.6. Activating Salt
Use this procedure to activate Salt plugin on your Foreman.
-
On your Salt Master, restart all Salt services:
# systemctl restart salt-master salt-api
-
On your Foreman server, restart all Foreman services:
# foreman-maintain service restart
-
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
-
Click Refresh for the relevant Smart Proxy.
5. Setting up Salt Minions
Salt Minions require the Salt Minion client software to interact with your Salt Master.
5.1. Creating a host group with Salt
You can create a host group with Salt enabled to bundle provisioning and configuration settings for hosts.
-
In the Foreman web UI, navigate to Configure > Host Groups.
-
Click Create Host Group.
-
Click the Host Group tab and select a Salt Environment and a Salt Master.
-
Click the Salt States tab and assign Salt States to your host group.
-
Click Submit to save your host group.
For more information, see Creating a Host Group Managing hosts.
5.2. Deploying Salt Minion hosts
Deploy hosts that are fully provisioned and configured for Salt usage.
-
A Salt Master
-
A Salt Environment
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
Select the previously created host group with Salt enabled.
-
Click Submit to deploy a host.
5.3. Verifying the connection between Salt Master and Salt Minions
Verify the connection between your Salt Master and Salt Minions.
-
Connect to your Salt Master using SSH:
# ssh root@salt-master.example.com
-
Ping your Salt Minions:
# salt "*" test.ping
-
Display all Salt Grains of all connected Salt Minions:
# salt "*" grains.items
6. Using Salt
Salt Minions managed by Foreman are associated with a Salt Master and a Salt Environment.
The associated Salt Environment within Foreman must match the actual Salt Environment from the file_roots
option in the /etc/salt/master
file.
You can configure hosts with Salt after they are associated with your Foreman server or Smart Proxy server and the Salt Minion client software is installed.
6.1. Using the Salt Hammer CLI
You can use Hammer CLI to configure hosts using Salt.
Run hammer --help
for more information.
-
Install
hammer_cli_foreman_salt
on your Foreman server
-
Creating a Salt State:
# hammer salt-state create \ --name My_Salt_State
-
Viewing information about a Salt Minion:
# hammer salt-minion info \ --name salt-minion.example.com
-
Adding Salt States to a Salt Minion:
# hammer salt-minion update \ --name salt-minion.example.com \ --salt-states My_Salt_State
6.2. Using the Salt API
Foreman Salt extends the Foreman REST API with Salt-specific features.
View the full API documentation on your Foreman server at http://foreman.example.com/apidoc/v2.html
.
-
Use
curl
to get a list of keys from smartproxy.example.com:# curl -u My_User_Name:My_Password \ -H "Accept: version=2,application/json" \ https://foreman.example.com/salt/api/v2/salt_keys/smartproxy.example.com
6.3. Importing Salt States
A Salt State configures parts of a host, for example, a service or the installation of a package.
You can import Salt States from your Salt Master to Foreman.
The Salt Master configuration in this guide uses a Salt Environment called base
that includes the Salt States stored in /srv/salt/
.
-
In the Foreman web UI, navigate to Configure > Salt > States.
-
Click Import from FQDN.
-
Optional: Click Edit to assign Salt States to Salt Environments.
-
Optional: Click Delete to remove a Salt State from your Foreman. This only removes the Salt State from Foreman, not from the disk of your Salt Master.
-
Click Submit to import the Salt States.
After you have imported Salt States, you can assign them to hosts or Host Groups.
Salt applies these Salt States to any hosts they are assigned to every time you run state.highstate
.
For more information, see Running Salt.
Note
|
Configure the paths for Salt States and Salt Pillars in |
6.4. Viewing Salt autosign keys
The Salt Keys page lists hosts and their Salt keys. You can manually accept, reject, or delete keys.
Use the Salt Autosign feature to automatically accept signing requests from hosts. By default, hosts are supplied with a Salt key during host provisioning.
Note
|
This feature only covers the Salt Autosign using the |
-
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
-
Select a Smart Proxy.
-
In the Actions drop down menu, click Salt Keys.
6.5. Enabling Salt report uploads
The Salt Master can directly upload Salt reports to Foreman.
-
Connect to your Salt Master using SSH:
# ssh root@salt-master.example.com
-
Ensure that the Salt reactor is present:
# file /usr/share/foreman-proxy/salt/reactors/foreman_report_upload.sls
-
Copy report upload script:
# cp /usr/share/foreman-proxy/salt/runners/foreman_report_upload.py /srv/salt/_runners/
-
Restart the Salt Master service:
# systemctl restart salt-master
-
Enable the new runner:
# salt-run saltutil.sync_all
-
If you use a cron job to upload facts from your Salt Master to Foreman, disable the cron job:
# rm -f /etc/cron.d/smart_proxy_salt
Alternatively, you can upload Salt reports from your Salt Master to Foreman manually:
# /usr/sbin/upload-salt-reports
6.6. Viewing Salt reports
You can view uploaded Salt reports from Salt Minions in Foreman.
-
To view all Salt reports, in the Foreman web UI, navigate to Monitor > Reports > Config Management.
-
To view Salt reports associated with a host, in the Foreman web UI, navigate to Hosts > All Hosts, select a host, and click the Reports tab.
6.7. Salt variables
You can configure Salt Variables within Foreman. The configured values are available as Salt Pillar data.
6.8. Viewing ENC parameters
You can use Foreman as an external node classifier for Salt. Click Salt ENC on the host overview page to view assigned Salt States. This shows a list of parameters that are made available for Salt usage as Salt Pillar data.
You can check what parameters are truly available on the Salt side by completing the following procedure.
-
Connect to your Salt Master using SSH:
# ssh root@salt-master.example.com
-
View available ENC parameters:
# salt '*' pillar.items
-
Optional: Refresh the Salt Pillar data if a parameter is missing:
# salt '*' saltutil.refresh_pillar
6.9. Running Salt
You can run arbitrary Salt functions, such as salt.highstate
, using remote execution on one or more Salt Minions.
This applies all relevant Salt States on your hosts.
-
In the Foreman web UI, navigate to Monitor > Jobs and click Run job.
-
If you want to run Salt highstate, select Salt as Job category and Salt Run state.highstate – Salt default as Job template and click Next.
-
If you want to run a Salt function, select Salt-Call as Job category and Salt Run function – SSH default as Job template and click Next.
In the Function field, enter the name of the function that you want to trigger, for example,
pillar.items
ortest.ping
.
-
-
Select hosts on which you want to run the job. If you do not select any hosts, the job will run on all hosts you can see in the current context.
-
Click Next.
-
Optional: To configure advanced settings for the job, fill in the Advanced fields. To learn more about advanced settings, see Advanced Settings in the Job Wizard in Managing hosts.
-
Click Next.
-
Select Immediate execution to execute the job immediately and click Next.
-
Review job details. You have the option to return to any part of the job wizard and edit the information.
-
Click Run to schedule the job for execution.
Alternatively, you can define recurrent actions using the native Salt way.
For example, you can schedule hourly state.highstate
runs on individual Salt Minions by extending /etc/salt/minion
:
schedule: highstate: function: state.highstate minutes: 60
7. Salt example
This example uses a Salt State to manage the /etc/motd
file on one or more Salt Minions.
It demonstrates the use of Foreman as an external node classifier and the use of Salt Grains.
-
Create a global parameter called
vendor_name
with the stringForeman
as its value. -
Add a new Salt State called
motd
to your Salt Master. -
Create the
/srv/salt/motd/
directory:# mkdir -p /srv/salt/motd/
-
Create
/srv/salt/motd/init.sls
as a Salt State file:/etc/motd: file.managed: - user: root - group: root - mode: 0644 - source: salt://motd/motd.template - template: jinja
-
Create
/srv/salt/motd/motd.template
as a template referenced by the Salt State file:Welcome to {{ grains['fqdn'] }} Powered by {{ salt['pillar.get']('vendor_name') }}
Access the
fqdn
Salt Grain from within this template and retrieve thevendor_name
parameter from the Salt Pillar. -
Import the
motd
Salt State into Foreman. For more information, see Importing Salt States. -
Verify that Salt has been given access to the
vendor_name
parameter by running either of the following commands on your Salt Master:# salt '*' pillar.items | grep -A 1 vendor_name # salt '*' pillar.get vendor_name
If the output does not include the value of the
vendor_name
parameter, you must refresh the Salt Pillar data first:# salt '*' saltutil.refresh_pillar
For information about how to refresh Salt Pillar data, see Viewing ENC parameters.
-
Add the
motd
Salt State to your Salt Minions or a host group. -
Run
state.highstate
to apply the Salt State. For more information, see Running Salt. -
Optional: Verify the contents of
/etc/motd
on a Salt Minion.