Skip to content

Commit 60e3c8a

Browse files
author
Alyssa Rock
committed
Merge branch 'style_overview' into 'master'
Style alignment on Salt overview topic See merge request saltstack/open/docs/salt-user-guide!74
2 parents 8ba01c6 + a0dd89d commit 60e3c8a

File tree

1 file changed

+46
-59
lines changed

1 file changed

+46
-59
lines changed

docs/topics/overview.rst

Lines changed: 46 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Salt overview
66

77
Features of Salt
88
=================
9-
The Salt system is a Python-based open-source remote execution framework for
9+
The Salt system is a Python-based, open-source remote execution framework for
1010
configuration management, automation, provisioning, and orchestration.
1111

1212
.. image:: ../_static/img/features-of-salt.png
@@ -38,74 +38,53 @@ the State system is:
3838
* **Simple** - easy to administer and manage.
3939
* **Extensible** - easy to add custom modules, or extend existing states.
4040
* **Deterministic** - executes in the same way every time.
41-
* **Layerable** - provides layers of data abstraction (such as states call execution modules).
41+
* **Layerable** - provides layers of data abstraction (such as states calling
42+
execution modules).
4243

4344
Automation and orchestration
4445
----------------------------
4546

46-
Executing remote management and configuration on a minion is perfect when you
47-
want to ensure that the minion is configured and running the way you want.
48-
Sometimes, however, you want to configure a set of minions all at once.
49-
For example, if you want to set up a load balancer in front of a cluster of
50-
web servers, you can ensure the load balancer is set up first. You can then
51-
apply the same matching configuration consistently across the whole cluster,
52-
which is known as orchestration.
47+
Executing remote management and configuration on a system is perfect when you
48+
want to ensure that it is configured and running the way you want.
49+
Sometimes, however, you want to configure a set of systems at once. For example,
50+
if you want to set up a load balancer in front of a cluster of web servers, you
51+
can ensure the load balancer is set up first. You can then apply the same matching
52+
configuration consistently across the whole cluster, which is known as orchestration.
5353

5454
Salt management concepts
5555
========================
5656

5757
A basic Salt implementation consists of a Salt master managing one or more Salt minions.
5858

59-
* A Salt master is a server running the ``salt-master`` service that provides
60-
management to many systems.
61-
* A Salt minion is any system/device managed by Salt. A Salt minion can
62-
run the ``salt-minion`` service or can be agentless using ``salt-ssh``
63-
or ``salt-proxy``.
64-
* A Salt Proxy process can behave as a salt-minion, which in turn connects
65-
to an underlying device to execute commands or states. Salt Proxy
66-
connections are typically achieved via SSH or RESTful API calls.
67-
* Systems managed via SSH with the ``salt-ssh`` model are also considered
68-
agentless minions under the managed systems model.
69-
* A newer system in development is ``salt-bin``, which will.
70-
71-
.. image:: ../_static/img/salt-architecture.png
72-
:align: right
73-
:alt: Salt architecture
7459

7560
Salt master
7661
-----------
7762

78-
A server running the ``salt-master`` service is a Salt master. The Salt master
63+
A server running the ``salt-master`` service is a Salt master. The master
7964
provides a cohesive platform for orchestration and automation between managed systems.
8065

8166
Salt minion
8267
-----------
8368

84-
A system under control of the Salt master is considered a Salt minion.
85-
However, minions do not require a master to be managed but can run in a stand-alone
69+
A Salt minion is any system or device managed by Salt. A minion can either run the
70+
``salt-minion`` service or be agentless using ``salt-ssh`` or ``salt-proxy``.
71+
A minion running the service may execute commands without a master in stand-alone
8672
mode.
8773

88-
* The ``salt-minion`` service runs as a management agent on a system.
89-
* The ``salt-minion`` service can run pretty much anywhere you can have a
90-
Python interpreter.
91-
9274
Salt proxy
9375
----------
9476

95-
Proxy minions are a feature that enables controlling devices that,
96-
for whatever reason, cannot run a standard salt-minion. A proxy minion process
97-
is used to establish a connection to an underlying device, using methods native
98-
to that device (SSH, Rest, etc).
77+
A Salt Proxy is used to execute commmands on devices that are unable to run the
78+
minion service. The proxy minion receives commands from a master, translates
79+
and transmits the commands appropriate to the method of connection to the
80+
underlying device (SSH, REST, etc.), and relays the results back to the master.
9981

10082
Salt SSH
10183
--------
10284

103-
The Salt SSH system was added to Salt as an alternative means to communicate
104-
with minions. The Salt SSH system can be used in tandem with or as an alternative
105-
to the standard Salt system. The Salt SSH system does not require that a Salt
106-
minion be present on the target system. Only SSH needs to be running and port
107-
22 open. We introduce this capability of Salt so you can appreciate the full
108-
capability of Salt but will not be using it in this class.
85+
The Salt SSH system was added as an alternative means to communicate with minions.
86+
It does not require that a minion be present on the target system, only that the
87+
SSH service is running and port 22 is open.
10988

11089
SaltStack Config
11190
----------------
@@ -117,6 +96,10 @@ routine functions. It also allows distributing the work to other skill-level
11796
employees and teams while securing your system and guarding the environment
11897
from the misuse of powerful tools.
11998

99+
.. image:: ../_static/img/saltstack-config-architecture.png
100+
:align: right
101+
:alt: SaltStack Config architecture
102+
120103
SaltStack Config features include:
121104

122105
* A web-based user interface
@@ -129,23 +112,23 @@ SaltStack Config features include:
129112
* Reporting
130113
* An enterprise API (eAPI)
131114

132-
.. image:: ../_static/img/saltstack-config-architecture.png
115+
.. image:: ../_static/img/salt-architecture.png
133116
:align: right
134-
:alt: SaltStack Config architecture
117+
:alt: Salt architecture
135118

136119
Salt topology
137120
=============
138121

139122
Salt has two ports used by default for the minions to communicate with their
140-
Salt master/masters. These ports work in concert to receive and deliver data to the *Message
141-
Bus*. Salt’s message bus is ZeroMQ, which creates an asynchronous network topology
142-
to provide the fastest communication possible.
123+
master. These ports work in concert to receive and deliver data to
124+
the *Message Bus*. Salt’s message bus is ZeroMQ, which creates an asynchronous
125+
network topology to provide the fastest communication possible.
143126

144127
Open event system
145128
-----------------
146129

147-
The event system is used for inter-process communication between the Salt master
148-
and Salt minions:
130+
The event system is used for inter-process communication between the master
131+
and minions:
149132

150133
* Events are seen by both the master and minions.
151134
* Events can be monitored and evaluated by both.
@@ -162,16 +145,18 @@ All minions see jobs and results by subscribing to events published on the event
162145
system.
163146
Salt uses a pluggable event system:
164147

165-
* **ZeroMQ (0MQ)** - the current default socket-level library providing a flexible transport layer.
148+
* **ZeroMQ (0MQ)** - the current default socket-level library providing a flexible
149+
transport layer.
166150
* **Tornado** - full TCP-based transport layer event system.
167151

168152
High-speed communication bus
169153
----------------------------
170154

171155
One of the greatest strengths of Salt is the speed of execution. The event system’s
172-
communication bus is more efficient than running a higher-level web service (http).
173-
The remote execution system is the component that all components are built
174-
upon, allowing for decentralized remote execution to spread load across resources.
156+
communication bus is more efficient than running a higher-level web service
157+
(such as HTTP). The remote execution system is the component that all components
158+
are built upon, allowing for decentralized remote execution to spread load across
159+
resources.
175160

176161
YAML Salt configuration file format
177162
-----------------------------------
@@ -194,15 +179,19 @@ There are basic rules for creating YAML:
194179
* Data is structured in ``key: value`` pairs.
195180
* Mappings use a colon and one space (“: ”) to mark key: value pairs.
196181
* The value of keys can be in many different structures.
197-
* All keys/properties are case-sensitive. Comments begin with a hash “#”.
182+
* All keys/properties are case-sensitive.
183+
* Tabs are NOT allowed, use spaces ONLY.
184+
* Comments begin with a hash “#”.
198185

199186
YAML simple structure
200187
---------------------
201188

202189
YAML consists of three basic element types:
203190

204-
#. **Scalars** -``key: value`` mappings where the value can be a number, string, or boolean value.
205-
#. **Lists** - a ``key:`` followed by a list of values where each value is on a separate line and proceeded with two spaces and a hyphen.
191+
#. **Scalars** -``key: value`` mappings where the value can be a number, string,
192+
or boolean value.
193+
#. **Lists** - a ``key:`` followed by a list of values where each value is on a
194+
separate line and proceeded with two spaces and a hyphen.
206195
#. **Dictionaries** - a collection of ``key: value`` mappings and lists.
207196

208197
.. Note::
@@ -251,10 +240,8 @@ YAML consists of three basic element types:
251240
Lists and dictionaries - YAML block structures
252241
----------------------------------------------
253242

254-
243+
* YAML is organized into block structures.
255244
* Indentation sets the context. You MUST indent your properties and list with one
256245
or more spaces, but two spaces is standard.
257-
* Tabs are NOT allowed, use spaces ONLY.
258-
* YAML is organized into block structures.
259246
* A collection, which is a list, or dictionary block sequence, indicates each
260-
entry with a hyphen and a space ( “- ”).
247+
entry with a hyphen and a space (“- ”).

0 commit comments

Comments
 (0)