{"id":13449353,"url":"https://github.com/mirceaulinic/salt-sproxy","last_synced_at":"2025-04-06T19:13:24.031Z","repository":{"id":48061895,"uuid":"166788578","full_name":"mirceaulinic/salt-sproxy","owner":"mirceaulinic","description":"Salt plugin to automate the management and configuration of (network) devices at scale, without running (Proxy) Minions.","archived":false,"fork":false,"pushed_at":"2024-07-03T15:40:28.000Z","size":1007,"stargazers_count":118,"open_issues_count":23,"forks_count":19,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-03-30T17:11:09.455Z","etag":null,"topics":["automation","configuration-management","docker","event-driven","network","network-automation","orchestration","python","rest-api","saltstack"],"latest_commit_sha":null,"homepage":"https://salt-sproxy.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mirceaulinic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mirceaulinic"]}},"created_at":"2019-01-21T09:47:28.000Z","updated_at":"2025-01-05T15:41:31.000Z","dependencies_parsed_at":"2024-03-26T16:50:15.375Z","dependency_job_id":"1b366e86-a382-4344-9999-65dd0f04ffb7","html_url":"https://github.com/mirceaulinic/salt-sproxy","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirceaulinic%2Fsalt-sproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirceaulinic%2Fsalt-sproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirceaulinic%2Fsalt-sproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirceaulinic%2Fsalt-sproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mirceaulinic","download_url":"https://codeload.github.com/mirceaulinic/salt-sproxy/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247535520,"owners_count":20954576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","configuration-management","docker","event-driven","network","network-automation","orchestration","python","rest-api","saltstack"],"created_at":"2024-07-31T06:00:36.202Z","updated_at":"2025-04-06T19:13:24.010Z","avatar_url":"https://github.com/mirceaulinic.png","language":"Python","funding_links":["https://github.com/sponsors/mirceaulinic"],"categories":["Python","Tools","Salt"],"sub_categories":["Salt Project Package Repositories","NETCONF"],"readme":"# Salt Super-Proxy [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Get+started+with+salt-sproxy+and+automate+your+network+with+all+the+Salt+benefits%2C+without+having+to+manage+thousands+of+%28Proxy%29+MInion+processes\u0026url=https://github.com/mirceaulinic/salt-sproxy\u0026hashtags=networkAutomation,saltstack,saltSProxy)\n\n[![PyPI downloads](https://pepy.tech/badge/salt-sproxy)](https://pypi.python.org/pypi/salt-sproxy/)\n[![Docker pulls](https://img.shields.io/docker/pulls/mirceaulinic/salt-sproxy.svg)](https://hub.docker.com/r/mirceaulinic/salt-sproxy)\n[![PyPI status](https://img.shields.io/pypi/status/salt-sproxy.svg)](https://pypi.python.org/pypi/salt-sproxy/)\n[![PyPI versions](https://img.shields.io/pypi/pyversions/salt-sproxy.svg)](https://pypi.python.org/pypi/salt-sproxy/)\n![Test plugin](https://github.com/mirceaulinic/salt-sproxy/workflows/Test%20plugin/badge.svg)\n[![Documentation status](https://readthedocs.org/projects/salt-sproxy/badge/?version=latest)](http://salt-sproxy.readthedocs.io/?badge=latest)\n[![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)\n[![License](https://img.shields.io/pypi/l/salt-sproxy.svg)](https://pypi.python.org/pypi/salt-sproxy/)\n[![GitHub make-a-pull-request](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\n[Salt](https://github.com/saltstack/salt) plugin to automate the management\nand configuration of network devices at scale, without running (Proxy) Minions.\n\nUsing ``salt-sproxy``, you can continue to benefit from the scalability,\nflexibility and extensibility of Salt, while you don't have to manage thousands\nof (Proxy) Minion services. However, you are able to use both ``salt-sproxy`` \nand your (Proxy) Minions at the same time.\n\nWhy ``salt-sproxy``\n-------------------\n\n``salt-sproxy`` can be used as a standalone tool to manage your devices without\nhaving any further requirements, as well as an extension to your existing Salt\nenvironment (if you already have). In other words, if you have a Salt\ninstallation where you manage some network devices and servers, installing\n``salt-sproxy`` on your Master will allow you to run any Salt command as always,\ne.g., executing ``salt \\* test.ping`` and ``salt-sproxy \\* test.ping`` will have\nthe exact same effect, and result. On top of that, using ``salt-sproxy`` allows\nyou to manage other devices for which you don't run (Proxy) Minions for.\n\nOf course, if you don't already have Salt, no problem, you can start managing\nyour devices straight away, check out the [quick \nstart steps](https://github.com/mirceaulinic/salt-sproxy/blob/develop/docs/quick_start.rst).\n\nIn brief, here are some benefits you can get by using *salt-sproxy*:\n\n- Say goodbye to the burden of managing hundreds of system services for the\n  Proxy Minion processes.\n- Reuse your existing extension modules, templates, Pillars, States, etc., you\n  may have already developed in your Salt environment, transparently.\n- You can run it locally, on your own computer.\n- You can use *salt-sproxy* to uniformly manage network devices, servers \n  (either using regular Minions, or [SSH](\n  https://salt-sproxy.readthedocs.io/en/latest/ssh.html)), applications \n  (e.g., Docker containers, VMWare ESXi clusters and vCenters, Marathon or \n  Chronos clusters, etc.), and virtually anything that has a programmable \n  interface.\n- Python programming made a breeze - might go well with the\n  [ISalt](https://github.com/mirceaulinic/isalt) package.\n- Integrates easily with your existing Salt environment (if you have), by\n  installing the package on your Salt Master.\n- Can continue to leverage the event-driven automation and orchestration\n  methodologies.\n- Can continue using any of the usual [targeting mechanisms](\n  https://salt-sproxy.readthedocs.io/en/latest/targeting.html).\n- REST API, see also\n  [the Salt REST API](https://salt-sproxy.readthedocs.io/en/latest/salt_api.html)\n  documentation.\n- By sending events to a Salt Master, you are able to implement whatever\n  auditing you need (e.g., what command was executed by who and when, etc.).\n- Benefit from inheriting _all_ the native Salt features and integrations\n  contributed by thousands of users, and tested in hundreds of different\n  environments, over almost a decade of development.\n\nIs ``salt-sproxy`` a wrapper around ``salt-ssh``?\n-------------------------------------------------\n\nNo, nothing to do with *salt-ssh*. The core of *salt-sproxy* is a Runner loaded\ndynamically on runtime, that spins up a pool of child processes, each running\na temporary light version of the Proxy Minion underneath; as soon as the \nexecution is complete for a device, its associated Proxy Minion is shut down, \nand another one takes its place into the child processes bucket.\n\nA source of confusion may also be the usage of the [Roster](\nhttps://salt-sproxy.readthedocs.io/en/latest/roster.html) interface, which,\nhistorically has only been used by *salt-ssh*, although the Roster is not \ntightly coupled with *salt-ssh*: it just happened to be the only use case so \nfar. Essentially, the Roster simply provides a list of devices together with \ntheir credentials (e.g., similar to the *inventory* as dubbed in other\nautomation frameworks) - and now has another use case in *salt-sproxy*.\n\nPrerequisites\n-------------\n\nThe package is distributed via PyPI, under the name ``salt-sproxy``. If you \nwould like to install it on your computer, you might want to run it under a\n[virtual environment](https://docs.python-guide.org/dev/virtualenvs/).\n\nBesides the CLI, the usage remains the same as when you're running a Salt \nenvironment with Proxy or regular Minions. See the following documents on how\nto get started and fully unleash the power of Salt:\n\n- [Salt in 10 minutes](https://docs.saltstack.com/en/latest/topics/tutorials/walkthrough.html).\n- [Salt fundamentals](https://docs.saltstack.com/en/getstarted/fundamentals/).\n- [Salt configuration management](https://docs.saltstack.com/en/getstarted/config/).\n- [Network Automation features available in Salt](https://docs.saltstack.com/en/develop/topics/network_automation/index.html).\n- [Network Automation at Scale: up and running in 60 minutes](https://ripe74.ripe.net/presentations/18-RIPE-74-Network-automation-at-scale-up-and-running-in-60-minutes.pdf).\n- [Network Automation at Scale (free e-book)](https://www.oreilly.com/library/view/network-automation-at/9781491992524/).\n\nInstall\n-------\n\nInstall this package where you would like to manage your devices from. In case\nyou need a specific Salt version, make sure you install it beforehand, \notherwise this package will bring the latest Salt version available instead.\n\nExecute:\n\n```bash\npip install salt-sproxy\n```\n\nTo install a specific Salt version, execute, e.g.,\n\n```bash\npip install salt==2018.3.4\npip install salt-sproxy\n```\n\nSee [https://salt-sproxy.readthedocs.io/en/latest/install.html](https://salt-sproxy.readthedocs.io/en/latest/install.html)\nfor more installation details.\n\nDocumentation\n-------------\n\nThe complete documentation is available at \n[https://salt-sproxy.readthedocs.io/en/latest/](https://salt-sproxy.readthedocs.io/en/latest/).\n\nOn Unix distributions you can also check the documentation locally, by \nexecuting ``man salt-sproxy``.\n\nQuick Start\n-----------\n\nSee this recording for a live quick start:\n\n\u003ca href=\"https://asciinema.org/a/247697?autoplay=1\" target=\"_blank\"\u003e\u003cimg src=\"static/247697.svg\" /\u003e\u003c/a\u003e\n\nIn the above, ``minion1`` is \na [dummy](https://docs.saltstack.com/en/latest/ref/proxy/all/salt.proxy.dummy.html)\nProxy Minion, that can be used for getting started and make the first steps \nwithout connecting to an actual device, but get used to the ``salt-sproxy``\nmethodology.\n\nThe Master configuration file is ``/home/mircea/master``, which is why the\ncommand is executed using the ``-c`` option specifying the path to the directory\nwith the configuration file. In this Master configuration file, the\n``pillar_roots`` option points to ``/srv/salt/pillar`` which is where \n``salt-sproxy`` is going to load the Pillar data from. Accordingly, the Pillar \nTop file is under that path, ``/srv/salt/pillar/top.sls``:\n\n```yaml\nbase:\n  minion1:\n    - dummy\n```\n\nThis Pillar Top file says that the Minion ``minion1`` will have the Pillar data \nfrom the ``dummy.sls`` from the same directory, thus \n``/srv/salt/pillar/dummy.sls``:\n\n```yaml\nproxy:\n  proxytype: dummy\n```\n\nIn this case, it was sufficient to only set the ``proxytype`` field to \n``dummy``.\n\n``salt-sproxy`` can be used in conjunction with any of the available [Salt \nProxy modules](https://docs.saltstack.com/en/latest/ref/proxy/all/index.html),\nor others that you might have in your own environment. See \n[https://docs.saltstack.com/en/latest/topics/proxyminion/index.html](https://docs.saltstack.com/en/latest/topics/proxyminion/index.html)\nto understand how to write a new Proxy module if you require.\n\nFor example, let's take a look at how we can manage a network device through \nthe [NAPALM Proxy](https://docs.saltstack.com/en/latest/ref/proxy/all/salt.proxy.napalm.html):\n\n\u003ca href=\"https://asciinema.org/a/247726?autoplay=1\" target=\"_blank\"\u003e\u003cimg src=\"static/247726.svg\" /\u003e\u003c/a\u003e\n\nIn the same Python virtual environment as previously, make sure  you have\n``NAPALM`` installed, by executing ``pip install napalm`` (see\n[https://napalm.readthedocs.io/en/latest/installation/index.html](https://napalm.readthedocs.io/en/latest/installation/index.html)\nfor further  installation requirements, depending on the platform you're running on). The \nconnection credentials for the ``juniper-router`` are stored in the \n``/srv/salt/pillar/junos.sls`` Pillar, and we can go ahead and start executing\narbitrary Salt commands, e.g.,\n[net.arp](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.napalm_network.html#salt.modules.napalm_network.arp)\nto retrieve the ARP table, or\n[net.load_config](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.napalm_network.html#salt.modules.napalm_network.load_config)\nto apply a configuration change on the router.\n\nThe Pillar Top file in this example was (under the same path as previously, as \nthe Master config was the same):\n\n```yaml\nbase:\n  juniper-router:\n    - junos\n```\n\nUsage\n-----\n\nFirst off, make sure you have the Salt\n[Pillar Top file](https://docs.saltstack.com/en/latest/ref/states/top.html) is\ncorrectly defined and the ``proxy`` key is available into the Pillar. For more\nin-depth explanation and examples, check\n[this](https://docs.saltstack.com/en/latest/topics/proxyminion/index.html) \ntutorial from the official SaltStack docs.\n\nOnce you have that, you can start using ``salt-sproxy`` even without any Proxy\nMinions or Salt Master running. To check, can start by executing:\n\n```bash\n$ salt-sproxy -L a,b,c --preview-target\n- a\n- b\n- c\n```\n\nThe syntax is very similar to the widely used CLI command ``salt``, however the\nway it works is completely different under the hood:\n\n``salt-sproxy \u003ctarget\u003e \u003cfunction\u003e [\u003carguments\u003e]``\n\nUsage Example:\n\n\n```bash\n$ salt-sproxy cr1.thn.lon test.ping\ncr1.thn.lon:\n    True\n```\n\nYou can continue reading further details at \n[https://salt-sproxy.readthedocs.io/en/latest/](https://salt-sproxy.readthedocs.io/en/latest/),\nfor now, check out the following section to see how to get started with\n``salt-sproxy`` straight away.\n\nSee also [https://salt-sproxy.readthedocs.io/en/latest/examples/index.html](https://salt-sproxy.readthedocs.io/en/latest/examples/index.html)\nfor more usage examples.\n\nEvent-Driven Automation and Orchestration\n-----------------------------------------\n\nIt is still possible to use the salt-sproxy functionality in the event-driven\ncontext, even without running Proxy or regular Minions. To see how to achieve \nthis, see this section of the documentation: \n[https://salt-sproxy.readthedocs.io/en/latest/events.html](https://salt-sproxy.readthedocs.io/en/latest/events.html).\n\nUsing the Salt REST API\n-----------------------\n\nSalt has natively available an HTTP API. You can read more at\n[https://docs.saltstack.com/en/latest/ref/netapi/all/salt.netapi.rest_cherrypy.html#a-rest-api-for-salt](\nhttps://docs.saltstack.com/en/latest/ref/netapi/all/salt.netapi.rest_cherrypy.html#a-rest-api-for-salt)\nif you haven't used it before. The usage is very simple; for salt-sproxy \nspecifically you can follow the notes from [https://salt-sproxy.readthedocs.io/en/latest/salt_sapi.html](\nhttps://salt-sproxy.readthedocs.io/en/latest/salt_sapi.html) how to set it up and \nuse. Usage example - apply a small configuration change on a Juniper device, by \nexecuting an HTTP request via the Salt API:\n\n```bash\n$ curl -sS localhost:8080/run -H 'Accept: application/x-yaml' \\\n  -d eauth='pam' \\\n  -d username='mircea' \\\n  -d password='pass' \\\n  -d client='sproxy' \\\n  -d tgt='juniper-router' \\\n  -d fun='net.load_config' \\\n  -d text='set system ntp server 10.10.10.1'\nreturn:\n- juniper-router:\n    already_configured: false\n    comment: ''\n    diff: '[edit system]\n      +   ntp {\n      +       server 10.10.10.1;\n      +   }'\n    loaded_config: ''\n    result: true\n```\n\nSee the [documentation](https://salt-sproxy.readthedocs.io/en/latest/salt_sapi.html)\nfor explanation, and [this example](https://salt-sproxy.readthedocs.io/en/latest/examples/salt_sapi.html)\nfor a quick start.\n\nWhat's included\n---------------\n\nWhen installing ``salt-sproxy``, besides the core files (i.e., ``cli.py``, \n``parsers.py``, ``scripts.py``, and ``version.py``), you will find the \nfollowing directories and files, which provide additional features and \nbackwards compatibility with older Salt versions:\n\n```\n  |-- cli.py\n  |-- parsers.py\n  |-- _roster/\n  |   |-- ansible.py\n  |   |-- file.py\n  |   |-- netbox.py\n  |   `-- pillar.py\n  |-- _runners/\n  |   `-- proxy.py\n  |-- scripts.py\n  `-- version.py\n```\n\nThe extension modules under the ``_roster`` and ``_runner`` directories are \ndocumented at [https://salt-sproxy.readthedocs.io/en/latest/roster/index.html](\nhttps://salt-sproxy.readthedocs.io/en/latest/roster/index.html)\nand [https://salt-sproxy.readthedocs.io/en/latest/runners/index.html](\nhttps://salt-sproxy.readthedocs.io/en/latest/runners/index.html),\nrespectively.\n\nDocker\n------\n\nA Docker image is available at \n[https://github.com/mirceaulinic/salt-sproxy/pkgs/container/salt-sproxy](https://github.com/mirceaulinic/salt-sproxy/pkgs/container/salt-sproxy),\nand you can pull it, e.g., ``docker pull ghcr.io/mirceaulinic/salt-sproxy:master``. See \n[https://salt-sproxy.readthedocs.io/en/latest/#docker](https://salt-sproxy.readthedocs.io/en/latest/#docker)\nfor further usage instructions and examples.\n\nCommunity\n---------\n\nGet updates on the ``salt-sproxy`` development, and chat with the project \nmaintainer(s) and community members:\n\n- Follow [@mirceaulinic](https://twitter.com/mirceaulinic)\n- [Google Groups](https://groups.google.com/forum/#!forum/salt-sproxy)\n- Use the ``salt-sproxy`` tag on [Stack Overflow](https://stackoverflow.com/).\n- The ``#salt-sproxy`` IRC channel on [freenode.net](https://webchat.freenode.net/).\n- The *#saltstack* channel under the\n  [networktocode Slack](https://networktocode.slack.com/messages/C0NL8RRMX/).\n\nLicense\n-------\n\nThis project is licensed under the Apache 2.0 License - see the\n[LICENSE](https://github.com/mirceaulinic/salt-sproxy/blob/master/LICENSE)\nfile for details.\n\nAcknowledgments\n---------------\n\nThanks to [Daniel Wallace](https://github.com/gtmanfred) for the \ninspiration.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirceaulinic%2Fsalt-sproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmirceaulinic%2Fsalt-sproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirceaulinic%2Fsalt-sproxy/lists"}