Skip to main content
Salt Bandle Logo

PyPI - Version

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.

For Formula Publishers

For Formula Consumers

Reference

Overview

What is Salt Bundle?

Salt Bundle provides:

  1. Version Management - Use semantic versioning for Salt formulas
  2. Dependency Resolution - Declare and automatically resolve formula dependencies
  3. Package Distribution - Publish formulas to HTTP or local repositories
  4. Reproducible Builds - Lock files ensure consistent deployments
  5. Automatic Integration - Salt loader plugin auto-discovers formulas (no config changes needed)
  6. Manual Integration - Also works with existing Salt setups via file_roots

Key Concepts

  • Formula - A Salt state directory with .sls files and metadata
  • Package - A versioned .tgz archive 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

  1. Create a formula with Salt states
  2. Add FORMULA metadata
  3. Pack into versioned archive
  4. Publish to repository
  5. Update repository index

See Publishing Guide for details.

For Consumers

  1. Initialize project with FORMULA
  2. Add repositories
  3. Declare dependencies with version constraints
  4. Install dependencies (creates lock file)
  5. 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 source repositories containing index.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

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:

  1. Salt automatically loads the plugin via entry points
  2. Plugin searches for FORMULA in current directory
  3. Reads vendor_dir from config
  4. 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

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: continue in cli/project/update.py). A proper conflict detection and error reporting mechanism is needed.
  • Version compatibility check — # TODO: Check version compatibility comment exists in cli/project/update.py; Salt min_version / max_version fields 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_pillar plugin 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 GitLabReleaseProvider is 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 magic comment), 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).
  • --timeout flag — mentioned in cicd-integration.md but not implemented in CLI code.
  • formula sync improvements — formula sync copies 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.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for salt-bundle 2.0.3
File Size Uploaded Provenance Actions
salt_bundle-2.0.3.tar.gz 120.5 kB Without provenance Details for salt_bundle-2.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for salt-bundle 2.0.3
File Interpreter ABI Platform Actions
salt_bundle-2.0.3-py3-none-any.whl Python 3 none any Details for salt_bundle-2.0.3-py3-none-any.whl

Total release size: 306.6 kB

Release files / salt_bundle-2.0.3.tar.gz

Download URL salt_bundle-2.0.3.tar.gz
Size 120.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d3c479b77d70145f6dd62eac3efb39f75268aa42053e8df3cfe9c751f20d6953
BLAKE2b-256 checksum
How to use checksums
e9c2c46322739496e633e35bea533d9806ff602330743bf99e2c316aacc0f7f4
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.3-py3-none-any.whl

Download URL salt_bundle-2.0.3-py3-none-any.whl
Size 186.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8bae009f9bd701648d0ce7c88a5304955ef231392a08f8e4de605b6ab3ffaf31
BLAKE2b-256 checksum
How to use checksums
d6daa95ff01079b425b771d0291cf6aba3103adc2fb741771239a2bc88d49ac1
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.3

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.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page