SaltStack state management enables declarative infrastructure configuration through reusable, version-controlled SLS files. This guide demonstrates core patterns including package installation, service orchestration, file distribution, dependency chaining, and reactive service handling.

Environment Setup

Begin by configuring environment-specific file roots in /etc/salt/master:

file_roots:
  base:
    - /srv/salt/base
  development:
    - /srv/salt/development
  production:
    - /srv/salt/production

Create the directory structure and restart the master:

mkdir -p /srv/salt/{base,development,production}
systemctl restart salt-master

Basic Web Server Deployment

Define an Apache deployment in /srv/salt/base/web/server.sls:

install_httpd_package:
  pkg.installed:
    - name: httpd

ensure_httpd_service:
  service.running:
    - name: httpd
    - enable: true

Apply the state to a target minion:

salt 'web-node-01' state.apply web.server

The output confirms both package installation and service activation, with clear change tracking per state ID.

Directory Organization and Modular States

Organize states into subdirectories for scalability:

mkdir -p /srv/salt/base/web/{files,templates}
mv /srv/salt/base/web/server.sls /srv/salt/base/web/

Reference nested states using dot notation:

salt 'web-node-01' state.apply web.server

Highstate Orchestration

Create /srv/salt/base/top.sls to map minions to states:

base:
  'web-node-*':
    - web.server
  'db-node-*':
    - database.postgres

Deploy all assigned states globally:

salt '*' state.highstate

LAMP Stack Configuration

Build a multi-component LAMP stack in /srv/salt/base/web/lamp.sls:

install_lamp_packages:
  pkg.installed:
    - pkgs:
      - httpd
      - php
      - php-pdo
      - php-mysql

manage_httpd_main_config:
  file.managed:
    - name: /etc/httpd/conf/httpd.conf
    - source: salt://web/files/httpd.conf
    - user: root
    - group: root
    - mode: '0644'

manage_httpd_includes:
  file.recurse:
    - name: /etc/httpd/conf.d
    - source: salt://web/files/conf.d
    - clean: true

manage_php_config:
  file.managed:
    - name: /etc/php.ini
    - source: salt://web/files/php.ini
    - user: root
    - group: root
    - mode: '0644'

ensure_web_service:
  service.running:
    - name: httpd
    - enable: true

Populate /srv/salt/base/web/files/ with required configuration files and include directories before execution.

State Dependencies

Enforce execution order using require. The following ensures configuration only applies if packages install successfully:

manage_httpd_main_config:
  file.managed:
    - name: /etc/httpd/conf/httpd.conf
    - source: salt://web/files/httpd.conf
    - require:
      - pkg: install_lamp_packages

Reactive Service Management

Automatically reload services when watched files change using watch:

ensure_web_service:
  service.running:
    - name: httpd
    - enable: true
    - reload: true
    - watch:
      - file: manage_httpd_main_config
      - file: manage_httpd_includes
      - file: manage_php_config

This triggers a graceful reload of Apache whenever any managed confiugration file is modified during a state run.

Appending Content to Files

Add lines to system files idempotently:

/etc/profile:
  file.append:
    - text:
      - '# Managed by SaltStack'
      - 'export PATH="/opt/bin:$PATH"'

Apply with salt '*' state.apply web.append.