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.4

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.4
File Size Uploaded Provenance Actions
salt_bundle-2.0.4.tar.gz 122.0 kB Without provenance Details for salt_bundle-2.0.4.tar.gz

Built distribution (wheel)

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

Total release size: 309.9 kB

Release files / salt_bundle-2.0.4.tar.gz

Download URL salt_bundle-2.0.4.tar.gz
Size 122.0 kB
Tags Source
SHA-256 checksum
How to use checksums
aeb3c374d984a99aa116215a1bdd0963cfe282b467e6136da06fb84f0e6e2e5a
BLAKE2b-256 checksum
How to use checksums
9fa38d55a5982898fbfff898addd26ca58fb451ef6394d95285916329435e1aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / salt_bundle-2.0.4-py3-none-any.whl

Download URL salt_bundle-2.0.4-py3-none-any.whl
Size 187.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79fd63e12749046def03221bf7dff72525ce9bfccf2c0e545ed89bd9f5d6a78f
BLAKE2b-256 checksum
How to use checksums
8c716efab6de3b47026d5af62ec3312e0dab2635458ee859ed6ffba0a349e5cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for salt-bundle 2.0.4

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