Salt Workspace

A learning workspace for SaltStack configuration management, developed alongside a blog series.

Quick Start

New to this project? Start with QUICKSTART.md for step-by-step setup instructions.

# Clone and build
git clone https://github.com/BadgerOps/salt-workspace.git
cd salt-workspace
make

# Run tests
make test

# Start VMs
vagrant up

Project Structure

salt-workspace/
├── salt/               # Salt states
│   ├── top.sls         # State assignments
│   └── roles/          # Role-based states
├── formulas/           # Reusable Salt formulas
│   ├── motd/           # Message of the Day
│   ├── packages/       # Package management
│   └── users/          # User management
├── pillar/             # Configuration data
├── config/             # Salt master/minion configs
├── tests/              # Test scripts
├── .devcontainer/      # VS Code / Codespaces config
└── .github/workflows/  # CI/CD pipeline

Prerequisites

Option A: Use Nix (recommended) - All tools included automatically:

nix develop  # or: direnv allow

Option B: Manual installation:

Tool	Purpose
VirtualBox	VM hypervisor
Vagrant	VM management
Docker	Formula testing
Python 3 + PyYAML	Lint scripts

# Install Vagrant plugin
vagrant plugin install vagrant-hostmanager

Make Commands

Command	Description
make	Build dist/ directory
make test	Run full test suite, including package layout validation
make lint	Linting checks only
make docker	Docker formula tests
make coverage	Test coverage report
make package	Create tarball
make package-smoke	Validate tarball layout against MANIFEST
make clean	Remove dist/
make help	Show all commands

Development

Workflow

1. Make changes in salt/, formulas/, or pillar/
2. Build: make
3. Test: make test
4. Apply in VM: vagrant ssh linux-1 → sudo salt-call state.highstate

Release Packages

make package creates dist/salt_config-<sha>.tgz. The archive is built from inside dist/, so its root contains salt/, formulas/, pillar/, SHA, MANIFEST, and MANIFEST.sha256 directly. Extract the tarball into /srv to match the /srv/... paths recorded in MANIFEST.

Run make package-smoke to verify that the archive has no extra dist/ prefix and that every /srv/... path in MANIFEST has a matching tar entry.

Environment Variables

Variable	Default	Description
LINUX_DISTRO	almalinux	OS distribution
LINUX_VERSION	8	OS version
LINUX_MINION_COUNT	1	Number of minions
LINUX_BOX_RAM	1024	RAM per VM (MB)
SALT_VERSION	3006.7	Salt version

Multiple Minions

export LINUX_MINION_COUNT=3
vagrant up /linux/

Different Distributions

# Ubuntu
export LINUX_DISTRO=ubuntu LINUX_VERSION=22.10 && vagrant up

# AlmaLinux 9
export LINUX_DISTRO=almalinux LINUX_VERSION=9 && vagrant up

Creating Formulas

Every formula needs:

formulas/myformula/
├── init.sls          # Main state file
├── pillar.example    # Example configuration
└── tests/
    └── init.yaml     # Test definitions

See the packages and users formulas for examples.

Testing Roles

1. SSH into a minion: vagrant ssh linux-1
2. Edit grains: sudo vim /etc/salt/grains

   roles:
     - base
     - your_role

3. Apply: sudo salt-call state.highstate

Encrypting Secrets

Use GPG for sensitive pillar data:

# Generate key (one-time setup)
gpg --gen-key --homedir /etc/salt/gpgkeys

# Encrypt a value
echo -n 'mysecret' | gpg --armor --encrypt -r 'Salt Master'

Add #!yaml|gpg shebang to pillar files with encrypted values.

Contributing

See CONTRIBUTING.md for guidelines.

Development Environment

Nix (Recommended)

This project includes a Nix flake for reproducible development environments. All dependencies are pinned and isolated from your system.

Available shells:

Shell	Command	Description
Default	nix develop	Docker-based testing (works everywhere)
Vagrant	nix develop .#withVagrant	Full VMs (requires VirtualBox)
Lima	nix develop .#withLima	Lightweight VMs (macOS/Linux)

Quick start:

# Default shell (Docker-based, recommended for most users)
nix develop

# Run tests directly
nix develop --command make test

# If you need full VMs for testing
nix develop .#withLima        # Lightweight VMs, no VirtualBox needed
nix develop .#withVagrant     # Traditional Vagrant VMs

Lima VM templates (with Salt pre-installed):

# Start a Salt-ready VM (Ubuntu)
limactl start ./lima/salt.yaml
limactl shell salt

# Or AlmaLinux (RHEL-compatible, like the Vagrant setup)
limactl start ./lima/salt-almalinux.yaml
limactl shell salt-almalinux

# Inside the VM: sync workspace and test
sudo rsync -av ~/salt-workspace/dist/ /srv/
sudo salt-call state.highstate

With nix-shell (legacy):

nix-shell                              # Default
nix-shell --arg withLima true          # With Lima
nix-shell --arg withVagrant true       # With Vagrant

With direnv (automatic activation):

direnv allow    # One-time setup, then auto-activates on cd

What's included:

Tool	Purpose
Python 3.11 + PyYAML	Scripts and linting
Docker + docker-compose	Container-based testing
yamllint, shellcheck	Linting and validation
make, rsync, git	Build tools
jq, yq	YAML/JSON utilities
Lima (optional)	Lightweight Linux VMs
Vagrant (optional)	Full VM management

Installing Nix:

# Linux/macOS (multi-user installation)
sh <(curl -L https://nixos.org/nix/install) --daemon

# Enable flakes (add to ~/.config/nix/nix.conf)
experimental-features = nix-command flakes

See the Nix installation guide for more options.

VS Code / GitHub Codespaces

This project includes a Dev Container configuration for instant development environments:

• VS Code: Install the Dev Containers extension, then "Reopen in Container"
• Codespaces: Click "Code" → "Codespaces" → "Create codespace"

Local Setup

Follow the instructions in QUICKSTART.md.

Resources

• Blog Series - Tutorials and guides
• Salt Documentation - Official docs
• Salt Formulas - Community formulas

License

MIT License - see LICENSE file for details.