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
make lint	Linting checks only
make docker	Docker formula tests
make coverage	Test coverage report
make package	Create tarball
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

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.