Skip to content

QUICKSTART.md

Latest commit

 

History

History
197 lines (147 loc) · 3.83 KB

QUICKSTART.md

File metadata and controls

197 lines (147 loc) · 3.83 KB
Raw

Quick Start Guide

Get up and running with Salt Workspace in minutes.

Prerequisites

Option A: Nix (Recommended)

If you have Nix installed, all dependencies are provided automatically:

# Enter the development environment (all tools included)
nix develop

# Or with direnv for automatic activation
direnv allow

Skip to Clone & Build if using Nix.

Option B: Manual Installation

Install these tools before starting:

Tool macOS Ubuntu/Debian Purpose
VirtualBox brew install virtualbox Download VM hypervisor
Vagrant brew install vagrant apt install vagrant VM management
Docker brew install docker apt install docker.io Test runner
Python 3 brew install python3 apt install python3 python3-pip Scripts
PyYAML pip3 install pyyaml pip3 install pyyaml YAML parsing

After installing Vagrant, add the hostmanager plugin:

vagrant plugin install vagrant-hostmanager

1. Clone & Build

git clone https://github.com/BadgerOps/salt-workspace.git
cd salt-workspace
make

2. Run Tests

make test

3. Start VMs

vagrant up

This starts:

  • saltmaster - Salt master server
  • linux-1 - Test minion (AlmaLinux 8 by default)

4. Connect to Minion

vagrant ssh linux-1
sudo salt-call state.highstate

Common Tasks

Test a Role

Edit /etc/salt/grains on the minion:

roles:
  - base
  - your_role

Then apply:

sudo salt-call state.highstate

Multiple Minions

export LINUX_MINION_COUNT=3
vagrant up

Different OS

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

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

More Memory

export LINUX_BOX_RAM=2048
vagrant up

Makefile Commands

Command Description
make Build dist/ directory
make test Run all tests
make lint Run linting only
make docker Run Docker tests
make coverage Show test coverage
make clean Remove dist/
make help Show all commands

Project Structure

salt-workspace/
├── salt/           # Salt states
│   ├── top.sls     # State assignments
│   └── roles/      # Role definitions
├── formulas/       # Reusable formulas
├── pillar/         # Configuration data
├── config/         # Salt master/minion configs
├── tests/          # Test scripts
└── dist/           # Built output (generated)

Creating a Formula

  1. Create formula directory:

    mkdir -p formulas/myformula/tests

  2. Add state file formulas/myformula/init.sls:

    myformula_package:
  pkg.installed:
    - name: mypackage

  3. Add pillar example formulas/myformula/pillar.example:

    myformula:
  enabled: true

  4. Add test formulas/myformula/tests/init.yaml:

    myformula:
  package:
    installed: true
    name: mypackage

  5. Build and test:

    make test

Troubleshooting

make test fails with YAML errors:

pip3 install pyyaml

Vagrant can't find boxes:

vagrant box update

Salt commands fail:

vagrant provision  # Re-run provisioning

Next Steps