Skip to main content

Master-servers

Integrating an existing Salt Master server with Salt.Box​

This instruction is intended for users who want to connect an existing Salt Master server to the deployed Salt.Box software suite.

note

It is assumed that Salt.Box is deployed in Docker application containerizer as per the online documentation section "Deploying Salt.Box Server".

Prerequisites​

  • Salt Master server (host with the SaltStack server component installed from the official repository - the salt-master package version 3006.9 or higher).

  • Salt.Box server with access to its Redis instance from the local network.

Checking the availability of the Redis server​

It is recommended to check the availability of the Redis server on the Salt.Box server before integration.

Perform a connection test to the Redis server (to the TCP/6379 port) from the Salt.Box server's command shell:

nc -vz <IP_or_HOSTNAME_of_Salt_Box> 6379

Make sure that the command output does not contain any error messages, such as "Connection refused", "No route to host", etc.

1. Cloning the Salt.Box Bridge Repository​

On the Salt Master server, run:

git clone https://dev.saltbox.pro/salt.box/salt-box-bridge.git

2. Getting a Redis Certificate​

On the Salt.Box server, run:

sudo docker compose cp redis-salt:/etc/redis/certs/ca.crt ./redis-ca.crt

Copy the redis-ca.crt file to the /etc/salt/ssl/ directory of the Salt Master server.

3. Creating the necessary directories​

On the Salt Master server, execute the following commands in sequence:

sudo mkdir -p /srv/salt_extmod/engines
sudo mkdir -p /srv/salt_extmod/runners
sudo mkdir -p /etc/salt/salt_box.d
sudo mkdir -p /etc/salt/ssl

4. Copying Bridge module files​

Copy all files with the .py extension from the engines/ and runners/ directories of the salt-box-bridge repository to the corresponding directories on the Salt Master server:

  • engines/ → /srv/salt_extmod/engines/
  • runners/ → /srv/salt_extmod/runners/

Make sure the files are owned by the root user.

5. Installing the Bridge service module​

Install the salt_box_bridge_service module using the pip utility corresponding to the Python version of your Salt Master server:

sudo /opt/saltstack/salt/bin/pip3.10 install /path/to/salt-box-bridge/salt_box_bridge_service

6. Setting up Salt Master configuration​

Create a file /etc/salt/master.d/master.conf with the following contents:

salt_master_id: UNIQUE_NAME       # Unique Salt Master server identifier

module_dirs:
  - /srv/salt_extmod/             # Path to directories with custom modules (engines and runners)

auto_accept: true                 # Automatically accept minion keys

presence_events: True             # Sending minion presence events

engines:
  - salt_box_redis_bridge:        # Engine for interaction via Redis
      salt_box_env_file: '/etc/salt/salt_box.d/.env'
  - salt_box_service:             # Engine for registering a master in SaltBox
      salt_box_env_file: '/etc/salt/salt_box.d/.env'

schedule:
  salt_box_redis_bridge_cleanup:  # Periodic clean up stale tasks in Redis
    hours: 3
    function: salt_box_redis_bridge.cleanup_expired_jobs
    kwargs:
      expire: 604800              # The lifetime of a task before it is cleaned up
      redis_host: redis-salt      # Redis host (may be left as is if configured via .env)

7. Creating a .env file​

Create a file /etc/salt/salt_box.d/.env with the following contents:

REDIS_HOST="Salt_Box_IP_or_hostname" # IP address or hostname where Salt.Box and Redis are installed
REDIS_USERNAME="Redis_user"     # Redis username (REDIS_SALT_USERNAME variable on Salt.Box server)
REDIS_PASSWORD="Redis_password" # Redis user password (from the file 'secrets/redis_salt_password')

REDIS_SSL_USE=True              # Whether to use TLS connection to Redis
REDIS_SSL_CA_CERTS="/etc/salt/ssl/redis-ca.crt" # Path to Redis CA certificate obtained from Salt.Box

EXPIRE=604800                   # Redis command lifetime (in seconds)
MASTER_SECRET="Unique_secret"   # Master's unique secret key (can be generated by pwgen)
note

Make sure the variable values ​​match your Salt.Box server settings.

8. Generate a unique Master Server ID​

info

This step is optional.

Run this script to generate a unique identifier:

./make_master_id.sh > /etc/salt/salt_box.d/master_id.txt

Then specify the file with the unique identifier in the master.conf file:

salt_master_id: /etc/salt/salt_box.d/master_id.txt

9. Restarting Salt Master server​

Apply the changes by restarting the salt-master service:

sudo systemctl restart salt-master.service

After completing all the steps, your Salt Master server will be integrated with Salt.Box and will be able to interact with the latter's components via the Redis server.