saltstack / saltstack/salt

[DOCS] Improve scalability documentation

Open
#62,085 2 comments 21 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation security and optimization severity-medium time-estimate-long-term
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description
One of the main selling points of SaltStack is scalability.

SaltStack is supposed to be able to work for thousands of nodes at once. That is something that none of the SaltStack competitors could do and it should be marketed heavily.

But current scalability and performance docs are lacking.

Suggested Fix
Here is what we have now:
https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html

  1. That doc doesn't give any hardware references, like "for managing 100, 1000, 5000 minions you need approximately this hardware." Etc.
  2. That doc doesn't include information regarding these Master tunes:
    https://docs.saltproject.io/en/latest/ref/configuration/master.html#worker-threads
    https://docs.saltproject.io/en/latest/ref/configuration/master.html#pub-hwm
    https://docs.saltproject.io/en/latest/ref/configuration/master.html#zmq-backlog
    https://docs.saltproject.io/en/latest/ref/configuration/master.html#cython-enable
  3. Those Master tunes are not well documented and it's very hard to reason about them. What should I do with them and in which scenarios?
  4. That doc doesn't include information regarding all types of caches and when to use them. It's especially important for the Pillar cache.
  5. That doc doesn't include information regarding HA configuration's effect on scalability and performance.
  6. That doc doesn't explain how to profile Saltstack for performance issues.
  7. That doc doesn't explain how syndic could help with scalability
  8. That doc doesn't explain performance difference between 0mq and TCP transport

Type of documentation
Scalability and Performance

Location or format of documentation
https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with topics/tutorials/intro_scale.html and review the master configuration entries for worker-threads, pub-hwm, zmq-backlog, and cython-enable. Expand the scalability documentation with hardware references, tuning guidance, cache usage, HA effects, profiling, syndic, and ZeroMQ-versus-TCP performance information; completion means each requested area is covered with actionable guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.