Skip to content
Salt plugin to automate the management and configuration of (network) devices at scale, without running (Proxy) Minions.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update question--.md Jun 26, 2019
docs Document the newly added features for Grains and auth data override f… Jun 27, 2019
examples Document alternative easy setup using Docker Jun 21, 2019
salt_sproxy Have also the pillar Roster module provide Grains and auth data Jun 27, 2019
static
.editorconfig Add .editorconfig file May 26, 2019
.gitignore Generate docs from the GitHub examples May 28, 2019
.pylintrc
.readthedocs.yml Add .readthedocs.yml file May 22, 2019
.travis.yml
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md May 26, 2019
CONTRIBUTING.md Add contributing document May 26, 2019
Dockerfile Simplify the Docker all image May 21, 2019
Dockerfile-all Update the allin Docker image to include NAPALM Jun 21, 2019
LICENSE Adding docs May 21, 2019
MANIFEST.in
Makefile Generate and include manual page on pip install Jun 14, 2019
NOTICE Add NOTICE file Jun 18, 2019
README.md Add #salt-sproxy freenode IRC Jul 7, 2019
README.rst Update README.rst Jun 18, 2019
install.sh Add install.sh script Jun 4, 2019
master
pypi.rst Adding a third RST file, for PyPI as it cannot read images :sigh: May 23, 2019
requirements-dev.txt Add test suite files May 29, 2019
requirements.txt Version 2019.1.0a2 Jan 21, 2019
roster
setup.cfg Add test suite files May 29, 2019
setup.py
tox.ini Add test suite files May 29, 2019

README.md

Salt Super-Proxy Tweet

PyPI downloads Docker pulls PyPI status PyPI versions Documentation status Code style License GitHub make-a-pull-request

Salt plugin to automate the management and configuration of network devices at scale, without running (Proxy) Minions.

Using salt-sproxy, you can continue to benefit from the scalability, flexibility and extensibility of Salt, while you don't have to manage thousands of (Proxy) Minion services. However, you are able to use both salt-sproxy and your (Proxy) Minions at the same time.

Note:

This is NOT a SaltStack product.

This package may eventually be integrated in a future version of the official Salt releases, in this form or slightly different.

Prerequisites

The package is distributed via PyPI, under the name salt-sproxy. If you would like to install it on your computer, you might want to run it under a virtual environment.

Besides the CLI, the usage remains the same as when you're running a Salt environment with Proxy or regular Minions. See the following documents on how to get started and fully unleash the power of Salt:

Install

Install this package where you would like to manage your devices from. In case you need a specific Salt version, make sure you install it beforehand, otherwise this package will bring the latest Salt version available instead.

Execute:

pip install salt-sproxy

To install a specific Salt version, execute, e.g.,

pip install salt==2018.3.4
pip install salt-sproxy

See https://salt-sproxy.readthedocs.io/en/latest/install.html for more installation details.

Documentation

The complete documentation is available at https://salt-sproxy.readthedocs.io/en/latest/.

On Unix distributions you can also check the documentation locally, by executing man salt-sproxy.

Quick Start

See this recording for a live quick start:

In the above, minion1 is a dummy Proxy Minion, that can be used for getting started and make the first steps without connecting to an actual device, but get used to the salt-sproxy methodology.

The Master configuration file is /home/mircea/master, which is why the command is executed using the -c option specifying the path to the directory with the configuration file. In this Master configuration file, the pillar_roots option points to /srv/salt/pillar which is where salt-sproxy is going to load the Pillar data from. Accordingly, the Pillar Top file is under that path, /srv/salt/pillar/top.sls:

base:
  minion1:
    - dummy

This Pillar Top file says that the Minion minion1 will have the Pillar data from the dummy.sls from the same directory, thus /srv/salt/pillar/dummy.sls:

proxy:
  proxytype: dummy

In this case, it was sufficient to only set the proxytype field to dummy.

salt-sproxy can be used in conjunction with any of the available Salt Proxy modules, or others that you might have in your own environment. See https://docs.saltstack.com/en/latest/topics/proxyminion/index.html to understand how to write a new Proxy module if you require.

For example, let's take a look at how we can manage a network device through the NAPALM Proxy:

In the same Python virtual environment as previously, make sure you have NAPALM installed, by executing pip install napalm (see https://napalm.readthedocs.io/en/latest/installation/index.html for further installation requirements, depending on the platform you're running on). The connection credentials for the juniper-router are stored in the /srv/salt/pillar/junos.sls Pillar, and we can go ahead and start executing arbitrary Salt commands, e.g., net.arp to retrieve the ARP table, or net.load_config to apply a configuration change on the router.

The Pillar Top file in this example was (under the same path as previously, as the Master config was the same):

base:
  juniper-router:
    - junos

Usage

First off, make sure you have the Salt Pillar Top file is correctly defined and the proxy key is available into the Pillar. For more in-depth explanation and examples, check this tutorial from the official SaltStack docs.

Once you have that, you can start using salt-sproxy even without any Proxy Minions or Salt Master running. To check, can start by executing:

$ salt-sproxy -L a,b,c --preview-target
- a
- b
- c

The syntax is very similar to the widely used CLI command salt, however the way it works is completely different under the hood:

salt-sproxy <target> <function> [<arguments>]

Usage Example:

$ salt-sproxy cr1.thn.lon test.ping
cr1.thn.lon:
    True

You can continue reading further details at https://salt-sproxy.readthedocs.io/en/latest/, for now, check out the following section to see how to get started with salt-sproxy straight away.

See also https://salt-sproxy.readthedocs.io/en/latest/examples/index.html for more usage examples.

Event-Driven Automation and Orchestration

It is still possible to use the salt-sproxy functionality in the event-driven context, even without running Proxy or regular Minions. To see how to achieve this, see this section of the documentation: https://salt-sproxy.readthedocs.io/en/latest/events.html.

Using the Salt REST API

Salt has natively available an HTTP API. You can read more at https://docs.saltstack.com/en/latest/ref/netapi/all/salt.netapi.rest_cherrypy.html#a-rest-api-for-salt if you haven't used it before. The usage is very simple; for salt-sproxy specifically you can follow the notes from https://salt-sproxy.readthedocs.io/en/latest/salt_api.html how to set it up and use. Usage example - apply a small configuration change on a Juniper device, by executing an HTTP request via the Salt API:

$ curl -sS localhost:8080/run -H 'Accept: application/x-yaml' \
  -d eauth='pam' \
  -d username='mircea' \
  -d password='pass' \
  -d client='runner' \
  -d fun='proxy.execute' \
  -d tgt='juniper-router' \
  -d function='net.load_config' \
  -d text='set system ntp server 10.10.10.1' \
  -d sync=True
return:
- juniper-router:
    already_configured: false
    comment: ''
    diff: '[edit system]
      +   ntp {
      +       server 10.10.10.1;
      +   }'
    loaded_config: ''
    result: true

See the documentation for explanation, and this example for a quick start.

What's included

When installing salt-sproxy, besides the core files (i.e., cli.py, parsers.py, scripts.py, and version.py), you will find the following directories and files, which provide additional features and backwards compatibility with older Salt versions:

  |-- cli.py
  |-- __init__.py
  |-- parsers.py
  |-- _roster/
  |   |-- ansible.py
  |   `-- netbox.py
  |-- _runners/
  |   |-- __init__.py
  |   `-- proxy.py
  |-- scripts.py
  `-- version.py

The extension modules under the _roster and _runner directories are documented at https://salt-sproxy.readthedocs.io/en/latest/roster/index.html and https://salt-sproxy.readthedocs.io/en/latest/runners/index.html, respectively.

Docker

A Docker image is available at https://hub.docker.com/r/mirceaulinic/salt-sproxy, and you can pull it, e.g., docker pull mirceaulinic/salt-sproxy. See https://salt-sproxy.readthedocs.io/en/latest/#docker for further usage instructions and examples.

Community

Get updates on the salt-sproxy development, and chat with the project maintainer(s) and community members:

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Acknowledgments

Thanks to Daniel Wallace for the inspiration.

You can’t perform that action at this time.