This release is a pre-release and may not be stable for production use.
Salt Bundle is a package manager for Salt formulas, similar to pip, npm, or Helm. It allows you to version, publish, and install Salt formulas with dependency management and reproducible builds.
Quick Links
For Formula Publishers
- Publishing Guide - How to create and publish formulas
- Formula Configuration -
FORMULAformat for formulas - Repository Setup - Setting up your own repository
For Formula Consumers
- Installation Guide - Installing and using formulas
- Project Configuration -
FORMULAformat for projects - Version Constraints - Semantic versioning and dependency resolution
Reference
- CLI Reference - Complete command-line interface documentation
- File Formats - All configuration file formats
- CI/CD Integration - GitHub Actions and GitLab CI examples
Overview
What is Salt Bundle?
Salt Bundle provides:
- Version Management - Use semantic versioning for Salt formulas
- Dependency Resolution - Declare and automatically resolve formula dependencies
- Package Distribution - Publish formulas to HTTP or local repositories
- Reproducible Builds - Lock files ensure consistent deployments
- Automatic Integration - Salt loader plugin auto-discovers formulas (no config changes needed)
- Manual Integration - Also works with existing Salt setups via
file_roots
Key Concepts
- Formula - A Salt state directory with
.slsfiles and metadata - Package - A versioned
.tgzarchive of a formula - Repository - HTTP/file location containing packages and an index
- Project - Your infrastructure code that depends on formulas
- Vendor Directory - Local folder where dependencies are installed
- Salt Loader Plugin - Automatic integration with Salt without config changes
Quick Start
Publishing a Formula
# Initialize formula metadata
cd my-formula
salt-bundle package init
# Edit FORMULA with your metadata
# Pack the formula
salt-bundle package pack
# Creates: my-formula-1.0.0.tgz
# Generate repository index
mkdir -p /srv/salt-repo
cp my-formula-1.0.0.tgz /srv/salt-repo/
cd /srv/salt-repo
salt-bundle repo index
# Creates: index.yaml
Using a Formula
# Initialize project
mkdir my-project
cd my-project
salt-bundle project init
# Add repository (global config)
salt-bundle repo add --name main --url https://example.com/salt-repo/
# Edit Saltfile to add dependencies
# dependencies:
# - name: my-formula
# version: "^1.0.0"
# source: https://example.com/salt-repo/
# Resolve and install dependencies
salt-bundle project update
# Installs to: vendor/my-formula/
# Use in Salt
salt-call --local \
--file-root=/path/to/my-project/salt:/path/to/my-project/vendor \
state.apply
Installation
Integration tests
Salt loader integration tests run in the Docker image from test/docker through
Test Kitchen. Build the image, then run the default suite:
test/docker/build.sh
bundle install
bundle exec kitchen test
The suite installs the local package into Salt's Python environment, stages the
foo example package as a project dependency, and verifies its loader modules
with salt-call --local. Remove the test container with bundle exec kitchen destroy when running individual Kitchen lifecycle commands.
From PyPI (when published)
pip install salt-bundle
From Source
git clone https://github.com/SomeBlackMagic/salt-bundle.git
cd salt-bundle
pip install -e .
Verify Installation
salt-bundle --help
Basic Workflow
For Publishers
- Create a formula with Salt states
- Add
FORMULAmetadata - Pack into versioned archive
- Publish to repository
- Update repository index
See Publishing Guide for details.
For Consumers
- Initialize project with
FORMULA - Add repositories
- Declare dependencies with version constraints
- Install dependencies (creates lock file)
- Integrate with Salt via
file_roots
See Installation Guide for details.
Architecture
Publishers Repository Consumers
────────── ────────── ─────────
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Formula │ │ index.yaml │ │ .saltbundle│
│ Directory │──pack─────▶ │ │ │ .yaml │
│ │ │ formula- │ │ │
│ - init.sls │ │ 1.0.0.tgz │◀────fetch────│ dependencies│
│ - .saltbundle │ │ │ │
│ .yaml │ │ formula- │ └─────────────┘
└─────────────┘ │ 1.0.1.tgz │ │
└─────────────┘ install
│
▼
┌─────────────┐
│ vendor/ │
│ formula/ │
│ - init.sls │
└─────────────┘
Features
Semantic Versioning
- Full semver support:
1.2.3,1.2.3-beta.1 - Version constraints:
^1.0.0,~1.2.3,>=1.0,<2.0 - Automatic resolution to latest compatible version
Dependency Management
- Declare dependencies in
FORMULA - Automatic resolution across repositories
- Lock file for reproducible installations
- Per-dependency
sourcerepositories containingindex.yaml
Repository Management
- HTTP/HTTPS repositories
- Local file:// repositories
- Multiple repository support
- Package caching
CI/CD Integration
- Automated release workflows
- GitHub Releases support
- GitHub Pages for index hosting
- GitLab CI compatible
Configuration Files
Formula: FORMULA
name: my-formula
version: 1.0.0
description: My Salt formula
formula_path: formula # Optional: package files from this relative subdirectory
maintainers:
- name: Developer Name
email: dev@example.com
salt:
min_version: "3006"
max_version: "3009"
dependencies:
- name: common
version: "^1.0"
Project: Saltfile
vendor_dir: vendor
dependencies:
- name: nginx
version: "^2.0.0"
source: https://salt-formulas.example.com/
- name: mysql
version: "~5.7.0"
Lock File: Saltfile.lock
dependencies:
nginx:
version: 2.1.0
repository: https://salt-formulas.example.com/
url: https://salt-formulas.example.com/nginx-2.1.0.tgz
digest: sha256:abc123...
type: formula
Common Use Cases
Monorepo with Multiple Formulas
formulas/
├── nginx/
│ ├── FORMULA
│ └── init.sls
├── mysql/
│ ├── FORMULA
│ └── init.sls
└── redis/
├── FORMULA
└── init.sls
# Release all formulas
cd formulas
salt-bundle repo release --formulas-dir . --provider local --pkg-storage-dir ../repo
Single Formula Repository
# In formula repository
salt-bundle repo release --formulas-dir . --single --provider github
# With GitHub:
export GITHUB_TOKEN=ghp_xxx
export GITHUB_REPOSITORY=owner/repo
salt-bundle repo release --formulas-dir . --single --provider github
Private Repository
# Add private repository
salt-bundle repo add --name private --url https://private.example.com/repo/
# Use in project
dependencies:
private/internal-formula: "^1.0.0"
Integration with Salt
Option 1: Automatic Salt Loader Plugin (Recommended)
After pip install salt-bundle, Salt automatically discovers formulas in your project's vendor/ directory.
No configuration changes needed!
# Install salt-bundle
pip install salt-bundle
# Navigate to project with FORMULA
cd my-project
# Run Salt commands - formulas auto-discovered from vendor/
salt-call state.apply nginx
salt-ssh '*' state.apply mysql
# Verify loader is working
salt-call pillar.get saltbundle
How it works:
- Salt automatically loads the plugin via entry points
- Plugin searches for
FORMULAin current directory - Reads
vendor_dirfrom config - Automatically adds formulas to
file_roots
See examples/project/README.md for detailed examples.
Option 2: Wrapper Script
#!/usr/bin/env bash
PROJECT_ROOT="$(cd "$(dirname "$0")" && pwd)"
VENDOR_DIR="${PROJECT_ROOT}/vendor"
SALT_DIR="${PROJECT_ROOT}/salt"
salt-call --local \
--file-root="${SALT_DIR}:${VENDOR_DIR}" \
"$@"
Option 3: Salt Master Config
# /etc/salt/master
file_roots:
base:
- /srv/salt
- /srv/my-project/vendor
Option 4: Salt Minion Config
# /etc/salt/minion
file_roots:
base:
- /srv/salt
- /srv/my-project/vendor
Support and Contributing
- Issues: Report bugs and request features on GitHub Issues
- Documentation: This documentation is in the
docs/directory - Contributing: Pull requests welcome!
License
Apache License 2.0
Next Steps
- Publishers: Read the Publishing Guide
- Consumers: Read the Installation Guide
- CI/CD: Check CI/CD Integration
- Reference: See CLI Reference
TODO
Dependency Resolution
- Conflict resolution — when two packages require incompatible versions of the same dependency, resolution silently picks the first-resolved version (
if pkg_name in resolved_packages: continueincli/project/update.py). A proper conflict detection and error reporting mechanism is needed. - Version compatibility check —
# TODO: Check version compatibilitycomment exists incli/project/update.py; Saltmin_version/max_versionfields in formula metadata are parsed but never enforced at install time. - Dependency graph output — no command to visualize or inspect the resolved dependency graph; useful for debugging complex dependency trees.
Pillar Support
- Auto-discovery of pillar data — the
ext_pillarplugin currently returns only project metadata (project_dir,vendor_dir,formulas,formula_paths). Pillar data files (pillar/*.sls) from individual formulas are not automatically merged into the pillar namespace.
Platform Integration
- GitLab full support — the
GitLabReleaseProvideris partially implemented; package release to GitLab Package Registry and index publishing to GitLab Pages need to be completed and tested. - salt-ssh stability — the loader plugin is bypassed by salt-ssh's thin-client bundling path. A workaround exists (duplicated entry-point registrations with a
# TODO black magiccomment), but a proper solution is needed.
Security
- GPG signature verification — packages are currently verified only by SHA256 digest. GPG signing of packages and signature verification on install would improve supply chain security.
UX / DX
- Dry-run for
project update— show what would change without modifying the lock file or vendor directory (mentioned in version-constraints.md as a planned feature). -
--timeoutflag — mentioned in cicd-integration.md but not implemented in CLI code. -
formula syncimprovements —formula synccopies modules to the Salt cache for use without the loader plugin; integration with salt-ssh thin client needs hardening.
Metadata
Release files for salt-bundle 2.0.0rc3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| salt_bundle-2.0.0rc3.tar.gz | 116.3 kB | Without provenance | Details for salt_bundle-2.0.0rc3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| salt_bundle-2.0.0rc3-py3-none-any.whl | Python 3 | none | any | Details for salt_bundle-2.0.0rc3-py3-none-any.whl |
Total release size: 297.3 kB
Release files / salt_bundle-2.0.0rc3.tar.gz
| Download URL | salt_bundle-2.0.0rc3.tar.gz |
|---|---|
| Size | 116.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f1985ba18a35932cb92e1074946b194140d57c5117b415aae44d8ec2abaa337
|
|
BLAKE2b-256 checksum How to use checksums |
442740a42755206e900a23d18f9d0c60d8024b4f627701df9df443814b99aafa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / salt_bundle-2.0.0rc3-py3-none-any.whl
| Download URL | salt_bundle-2.0.0rc3-py3-none-any.whl |
|---|---|
| Size | 181.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f713ee84c78faf5732268f5d0d52e13f92783661b49eb91d9588b942c6d33945
|
|
BLAKE2b-256 checksum How to use checksums |
474668b8259b4807243b06f111c1582c3382306d0235ff9f604807551168622f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Security for salt-bundle 2.0.0rc3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.