blob: 84c1cf9fc199eb16aa15c7d1046f1264d559d251 [file] [log] [blame]
Filip Pytlounb4b80592015-10-06 16:28:32 +02001
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03002=====
3Usage
4=====
Filip Pytlounb4b80592015-10-06 16:28:32 +02005
Ales Komarek54740682017-05-15 07:16:23 +02006Salt is a new approach to infrastructure management. Easy enough to get
7running in minutes, scalable enough to manage tens of thousands of servers,
8and fast enough to communicate with them in seconds.
Filip Pytlounb4b80592015-10-06 16:28:32 +02009
Ales Komarek54740682017-05-15 07:16:23 +020010Salt delivers a dynamic communication bus for infrastructures that can be used
11for orchestration, remote execution, configuration management and much more.
Filip Pytlounb4b80592015-10-06 16:28:32 +020012
Ales Komarek54740682017-05-15 07:16:23 +020013Sample Metadata
14===============
15
Ales Komarekd768f1c2018-01-30 22:37:18 +010016Salt Master
Filip Pytlounb4b80592015-10-06 16:28:32 +020017-----------
18
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030019Salt master with base formulas and pillar metadata back end:
Filip Pytlounb4b80592015-10-06 16:28:32 +020020
Ales Komarek8ba9c0b2016-02-21 14:59:59 +010021.. literalinclude:: tests/pillar/master_single_pillar.sls
22 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +020023
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030024Salt master with reclass ENC metadata back end:
Filip Pytlounb4b80592015-10-06 16:28:32 +020025
Ales Komarek8ba9c0b2016-02-21 14:59:59 +010026.. literalinclude:: tests/pillar/master_single_reclass.sls
27 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +020028
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030029Salt master with Architect ENC metadata back end:
Ales Komarek459407b2018-01-18 17:16:31 +010030
31.. code-block:: yaml
32
33 salt:
34 master:
35 enabled: true
36 pillar:
37 engine: architect
38 project: project-name
39 host: architect-api
40 port: 8181
41 username: salt
42 password: password
43
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030044Salt master with multiple ``ext_pillars``:
Petr Michalec1f541c42017-08-17 13:30:37 +020045
Dzmitry Stremkouski7b15d8a2018-08-11 22:02:45 +020046.. code-block:: yaml
47
48 salt:
49 master:
50 enabled: true
51 pillar:
52 engine: salt
53 source:
54 engine: local
55 ext_pillars:
56 1:
57 module: cmd_json
58 params: '"echo {\"arg\": \"val\"}"'
59 2:
60 module: cmd_yaml
61 params: /usr/local/bin/get_yml.sh
Petr Michalec1f541c42017-08-17 13:30:37 +020062
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030063Salt master with API:
Filip Pytlounb4b80592015-10-06 16:28:32 +020064
Ales Komarekb2c8ff62016-08-22 00:20:01 +020065.. literalinclude:: tests/pillar/master_api.sls
66 :language: yaml
Ales Komarekcdb280f2016-07-27 15:37:51 +020067
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030068Salt master with defined user ACLs:
Ales Komarekcdb280f2016-07-27 15:37:51 +020069
Ales Komarekb2c8ff62016-08-22 00:20:01 +020070.. literalinclude:: tests/pillar/master_acl.sls
71 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +020072
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030073Salt master with preset minions:
Filip Pytlounb4b80592015-10-06 16:28:32 +020074
75.. code-block:: yaml
76
77 salt:
78 master:
79 enabled: true
Filip Pytlounb4b80592015-10-06 16:28:32 +020080 minions:
81 - name: 'node1.system.location.domain.com'
82
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030083Salt master with pip based installation (optional):
Adam Tenglercaedd972016-05-04 16:44:00 +020084
85.. code-block:: yaml
86
87 salt:
88 master:
89 enabled: true
90 ...
91 source:
92 engine: pip
93 version: 2016.3.0rc2
94
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +030095Install formula through system package management:
Adam Tengler3eb85ad2016-05-06 02:52:40 +020096
97.. code-block:: yaml
98
99 salt:
100 master:
101 enabled: true
102 ...
103 environment:
104 prd:
Petr Michalec7a2f1d22017-05-17 22:08:32 +0200105 keystone:
Adam Tengler3eb85ad2016-05-06 02:52:40 +0200106 source: pkg
107 name: salt-formula-keystone
Petr Michalec7a2f1d22017-05-17 22:08:32 +0200108 nova:
109 source: pkg
110 name: salt-formula-keystone
111 version: 0.1+0~20160818133412.24~1.gbp6e1ebb
112 postresql:
113 source: pkg
114 name: salt-formula-postgresql
115 version: purged
116
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300117Formula keystone is installed latest version and the formulas
118without version are installed in one call to aptpkg module.
119If the version attribute is present sls iterates over formulas
120and take action to install specific version or remove it.
121The version attribute may have these values
122``[latest|purged|removed|<VERSION>]``.
Adam Tengler3eb85ad2016-05-06 02:52:40 +0200123
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300124Clone master branch of keystone formula as local feature branch:
Adam Tengler3eb85ad2016-05-06 02:52:40 +0200125
126.. code-block:: yaml
127
128 salt:
129 master:
130 enabled: true
131 ...
132 environment:
133 dev:
134 formula:
135 keystone:
136 source: git
137 address: git@github.com:openstack/salt-formula-keystone.git
138 revision: master
139 branch: feature
140
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300141Salt master with specified formula refs (for example, for Gerrit
142review):
Adam Tengler3eb85ad2016-05-06 02:52:40 +0200143
144.. code-block:: yaml
145
146 salt:
147 master:
148 enabled: true
149 ...
150 environment:
151 dev:
152 formula:
153 keystone:
154 source: git
155 address: https://git.openstack.org/openstack/salt-formula-keystone
156 revision: refs/changes/56/123456/1
157
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300158Salt master logging configuration:
Oleksii Chupryn7b7102a2018-05-11 10:32:11 +0300159
160.. code-block:: yaml
161
162 salt:
163 master:
164 enabled: true
165 log:
166 level: warning
167 file: '/var/log/salt/master'
168 level_logfile: warning
169
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300170Salt minion logging configuration:
Oleksii Chupryn7b7102a2018-05-11 10:32:11 +0300171
172.. code-block:: yaml
173
174 salt:
175 minion:
176 enabled: true
177 log:
178 level: info
179 file: '/var/log/salt/minion'
180 level_logfile: warning
181
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300182Salt master with logging handlers:
Filip Pytlounb4b80592015-10-06 16:28:32 +0200183
184.. code-block:: yaml
185
186 salt:
187 master:
188 enabled: true
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100189 handler:
190 handler01:
191 engine: udp
192 bind:
193 host: 127.0.0.1
194 port: 9999
Filip Pytlounb4b80592015-10-06 16:28:32 +0200195 minion:
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100196 handler:
197 handler01:
198 engine: udp
199 bind:
200 host: 127.0.0.1
201 port: 9999
202 handler02:
203 engine: zmq
204 bind:
205 host: 127.0.0.1
206 port: 9999
207
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300208Salt engine definition for saltgraph metadata collector:
Ales Komareka9fc6e72017-09-06 15:02:40 +0200209
210.. code-block:: yaml
211
212 salt:
213 master:
214 engine:
215 graph_metadata:
216 engine: saltgraph
217 host: 127.0.0.1
218 port: 5432
219 user: salt
220 password: salt
221 database: salt
222
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300223Salt engine definition for Architect service:
Ales Komarek459407b2018-01-18 17:16:31 +0100224
225.. code-block:: yaml
226
227 salt:
228 master:
229 engine:
230 architect:
231 engine: architect
232 project: project-name
233 host: architect-api
234 port: 8181
235 username: salt
236 password: password
237
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300238Salt engine definition for sending events from docker events:
Ales Komareka9fc6e72017-09-06 15:02:40 +0200239
240.. code-block:: yaml
241
242 salt:
243 master:
244 engine:
245 docker_events:
246 docker_url: unix://var/run/docker.sock
247
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300248Salt master peer setup for remote certificate signing:
Jakub Pavlikd4859842016-05-23 10:48:04 +0200249
250.. code-block:: yaml
251
252 salt:
253 master:
254 peer:
255 ".*":
256 - x509.sign_remote_certificate
Filip Pytlounb4b80592015-10-06 16:28:32 +0200257
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300258Salt master backup configuration:
Ales Komarekb2ada522017-12-07 11:31:32 +0100259
260.. code-block:: yaml
261
262 salt:
263 master:
264 backup: true
265 initial_data:
266 engine: backupninja
Jiri Broulik3e281642018-03-02 18:17:21 +0100267 home_dir: remote-backup-home-dir
Ales Komarekb2ada522017-12-07 11:31:32 +0100268 source: backup-node-host
269 host: original-salt-master-id
270
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300271Configure verbosity of state output (used for :command:`salt`
272command):
Tomáš Kukrál8922aef2017-05-10 10:27:04 +0200273
274.. code-block:: yaml
275
276 salt:
277 master:
Tomáš Kukrál044667b2017-05-11 10:12:15 +0200278 state_output: changes
Tomáš Kukrál8922aef2017-05-10 10:27:04 +0200279
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300280Pass pillar render error to minion log:
Ales Komarekd768f1c2018-01-30 22:37:18 +0100281
282.. note:: When set to `False` this option is great for debuging.
283 However it is not recomended for any production environment as it may contain
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300284 templating data as passwords, and so on, that minion should not expose.
Ales Komarekd768f1c2018-01-30 22:37:18 +0100285
286.. code-block:: yaml
287
288 salt:
289 master:
290 pillar_safe_render_error: False
291
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300292Enable Windows repository support:
Ales Komarekf44e64c2018-05-29 10:22:31 +0200293
294.. code-block:: yaml
295
296 salt:
297 master:
298 win_repo:
299 source: git
300 address: https://github.com/saltstack/salt-winrepo-ng
301 revision: master
302
Ivan Suzdal7e2a2ca2018-08-23 12:31:19 +0400303Configure a gitfs_remotes resource:
304
305.. code-block:: yaml
306
307 salt:
308 master:
309 gitfs_remotes:
310 salt_formula:
Pavel Cizinsky6b67f5f2018-12-12 12:03:18 +0100311 url: https://gerrit.mcp.mirantis.com/salt-formulas/salt.git
Ivan Suzdal7e2a2ca2018-08-23 12:31:19 +0400312 enabled: true
313 params:
314 base: master
315
316Read more about gitfs resource options in the official Salt documentation.
317
318
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300319Event/Reactor systems
Ales Komarekd768f1c2018-01-30 22:37:18 +0100320~~~~~~~~~~~~~~~~~~~~~
Petr Michalec1f541c42017-08-17 13:30:37 +0200321
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300322Salt to synchronize node pillar and modules after start:
Ales Komarek54740682017-05-15 07:16:23 +0200323
324.. code-block:: yaml
325
326 salt:
327 master:
328 reactor:
329 salt/minion/*/start:
Ales Komareke7844d12017-06-08 12:00:01 +0200330 - salt://salt/reactor/node_start.sls
Ales Komarek54740682017-05-15 07:16:23 +0200331
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300332Trigger basic node install:
Ales Komareke7844d12017-06-08 12:00:01 +0200333
334.. code-block:: yaml
335
336 salt:
337 master:
338 reactor:
339 salt/minion/install:
340 - salt://salt/reactor/node_install.sls
341
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300342Sample event to trigger the node installation:
Ales Komareke7844d12017-06-08 12:00:01 +0200343
344.. code-block:: bash
345
346 salt-call event.send 'salt/minion/install'
347
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300348Run any defined orchestration pipeline:
Ales Komarek5c58de32017-06-06 11:49:32 +0200349
350.. code-block:: yaml
351
352 salt:
353 master:
354 reactor:
355 salt/orchestrate/start:
356 - salt://salt/reactor/orchestrate_start.sls
357
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300358Event to trigger the orchestration pipeline:
Ales Komarek5c58de32017-06-06 11:49:32 +0200359
360.. code-block:: bash
361
Ales Komareke7844d12017-06-08 12:00:01 +0200362 salt-call event.send 'salt/orchestrate/start' "{'orchestrate': 'salt/orchestrate/infra_install.sls'}"
Ales Komarek5c58de32017-06-06 11:49:32 +0200363
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300364Synchronise modules and pillars on minion start:
Ales Komarek3ed7c432017-08-24 16:15:49 +0200365
366.. code-block:: yaml
367
368 salt:
369 master:
370 reactor:
371 'salt/minion/*/start':
372 - salt://salt/reactor/minion_start.sls
373
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300374Add and/or remove the minion key:
Ales Komarek5c58de32017-06-06 11:49:32 +0200375
376.. code-block:: yaml
377
378 salt:
379 master:
380 reactor:
Ales Komarek213fbe02017-08-21 16:39:05 +0200381 salt/key/create:
382 - salt://salt/reactor/key_create.sls
383 salt/key/remove:
384 - salt://salt/reactor/key_remove.sls
Ales Komarek5c58de32017-06-06 11:49:32 +0200385
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300386Event to trigger the key creation:
Ales Komarek5c58de32017-06-06 11:49:32 +0200387
388.. code-block:: bash
389
Adam Tengler62188962017-09-04 13:34:44 +0000390 salt-call event.send 'salt/key/create' \
391 > "{'node_id': 'id-of-minion', 'node_host': '172.16.10.100', 'orch_post_create': 'kubernetes.orchestrate.compute_install', 'post_create_pillar': {'node_name': 'id-of-minion'}}"
Ales Komarek5c58de32017-06-06 11:49:32 +0200392
Ales Komarek213fbe02017-08-21 16:39:05 +0200393.. note::
394
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300395 You can add pass additional ``orch_pre_create``, ``orch_post_create``,
396 ``orch_pre_remove`` or ``orch_post_remove`` parameters to the event
397 to call extra orchestrate files. This can be useful for example for
Ales Komarek213fbe02017-08-21 16:39:05 +0200398 registering/unregistering nodes from the monitoring alarms or dashboards.
399
400 The key creation event needs to be run from other machine than the one
401 being registered.
402
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300403Event to trigger the key removal:
Ales Komarek213fbe02017-08-21 16:39:05 +0200404
405.. code-block:: bash
406
407 salt-call event.send 'salt/key/remove'
Ales Komarek54740682017-05-15 07:16:23 +0200408
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300409Control VM provisioning:
Dzmitry Stremkouski7ee23402018-04-10 00:43:48 +0200410
411.. code-block:: yaml
412
Dzmitry Stremkouski97927ee2018-08-23 23:20:38 +0200413 _param:
Dzmitry Stremkouski30c7d2f2019-01-16 23:40:36 +0100414 vcp_links: &vcp_links
415 - type: phy
416 id: ens2
417 name: ens2
Dzmitry Stremkouski97927ee2018-08-23 23:20:38 +0200418 private-ipv4: &private-ipv4
419 - id: private-ipv4
420 type: ipv4
421 link: ens2
422 netmask: 255.255.255.0
423 routes:
424 - gateway: 192.168.0.1
425 netmask: 0.0.0.0
426 network: 0.0.0.0
Dzmitry Stremkouski7ee23402018-04-10 00:43:48 +0200427 virt:
428 disk:
429 three_disks:
430 - system:
431 size: 4096
432 image: ubuntu.qcow
433 - repository_snapshot:
434 size: 8192
435 image: snapshot.qcow
436 - cinder-volume:
437 size: 2048
Ondrej Smolae6bcb292018-04-13 10:56:39 +0200438 nic:
439 control:
440 - name: nic01
441 bridge: br-pxe
442 model: virtio
443 - name: nic02
444 bridge: br-cp
445 model: virtio
446 - name: nic03
447 bridge: br-store-front
448 model: virtio
449 - name: nic04
450 bridge: br-public
451 model: virtio
Dzmitry Stremkouskib8acf1f2018-06-28 12:56:23 +0200452 - name: nic05
453 bridge: br-prv
454 model: virtio
455 virtualport:
456 type: openvswitch
Ondrej Smolae6bcb292018-04-13 10:56:39 +0200457
Dzmitry Stremkouski7ee23402018-04-10 00:43:48 +0200458 salt:
459 control:
460 enabled: true
461 virt_enabled: true
462 size:
463 medium_three_disks:
464 cpu: 2
465 ram: 4
466 disk_profile: three_disks
467 cluster:
468 mycluster:
469 domain: neco.virt.domain.com
470 engine: virt
Martin Horak9e11aa22018-09-17 06:46:59 +0200471 # Cluster global settings
Ondrej Smolac7f6cfc2018-05-21 15:55:08 +0200472 rng: false
Martin Horak9e11aa22018-09-17 06:46:59 +0200473 enable_vnc: True
Andrei Danin996e2092018-09-10 21:58:23 -0700474 seed: cloud-init
Dzmitry Stremkouski97927ee2018-08-23 23:20:38 +0200475 cloud_init:
476 user_data:
477 disable_ec2_metadata: true
478 resize_rootfs: True
479 timezone: UTC
480 ssh_deletekeys: True
481 ssh_genkeytypes: ['rsa', 'dsa', 'ecdsa']
482 ssh_svcname: ssh
483 locale: en_US.UTF-8
484 disable_root: true
485 apt_preserve_sources_list: false
486 apt:
487 sources_list: ""
488 sources:
489 ubuntu.list:
490 source: ${linux:system:repo:ubuntu:source}
491 mcp_saltstack.list:
492 source: ${linux:system:repo:mcp_saltstack:source}
Dzmitry Stremkouski7ee23402018-04-10 00:43:48 +0200493 node:
494 ubuntu1:
495 provider: node01.domain.com
496 image: ubuntu.qcow
497 size: medium
498 img_dest: /var/lib/libvirt/ssdimages
Martin Horak9e11aa22018-09-17 06:46:59 +0200499 # Node settings override cluster global ones
500 enable_vnc: False
Dzmitry Stremkouski7ee23402018-04-10 00:43:48 +0200501 rng:
502 backend: /dev/urandom
503 model: random
504 rate:
505 period: '1800'
506 bytes: '1500'
Alexandru Avadanii00f187a2018-06-24 20:36:44 +0200507 # Custom per-node loader definition (e.g. for AArch64 UEFI)
508 loader:
509 readonly: yes
510 type: pflash
511 path: /usr/share/AAVMF/AAVMF_CODE.fd
512 machine: virt-2.11 # Custom per-node virt machine type
513 cpu_mode: host-passthrough
Pavel Cizinskyf03c4e82018-09-10 14:56:11 +0200514 cpuset: '1-4'
Ondrej Smolae6bcb292018-04-13 10:56:39 +0200515 mac:
516 nic01: AC:DE:48:AA:AA:AA
517 nic02: AC:DE:48:AA:AA:BB
Dzmitry Stremkouski97927ee2018-08-23 23:20:38 +0200518 # netconfig affects: hostname during boot
519 # manual interfaces configuration
520 cloud_init:
521 network_data:
Dzmitry Stremkouski30c7d2f2019-01-16 23:40:36 +0100522 links: *vcp_links
Dzmitry Stremkouski97927ee2018-08-23 23:20:38 +0200523 networks:
524 - <<: *private-ipv4
525 ip_address: 192.168.0.161
Andrei Danin996e2092018-09-10 21:58:23 -0700526 user_data:
527 salt_minion:
528 conf:
529 master: 10.1.1.1
530 ubuntu2:
531 seed: qemu-nbd
532 cloud_init:
533 enabled: false
534
535There are two methods to seed an initial Salt minion configuration to
536Libvirt VMs: mount a disk and update a filesystem or create a ConfigDrive with
537a Cloud-init config. This is controlled by the "seed" parameter on cluster and
538node levels. When set to _True_ or "qemu-nbd", the old method of mounting a disk
539will be used. When set to "cloud-init", the new method will be used. When set
540to _False_, no seeding will happen. The default value is _True_, meaning
541the "qemu-nbd" method will be used. This is done for backward compatibility
542and may be changed in future.
543
544The recommended method is to use Cloud-init.
545It's controlled by the "cloud_init" dictionary on cluster and node levels.
546Node level parameters are merged on top of cluster level parameters.
547The Salt Minion config is populated automatically based on a VM name and config
548settings of the minion who is actually executing a state. To override them,
549add the "salt_minion" section into the "user_data" section as shown above.
550It is possible to disable Cloud-init by setting "cloud_init.enabled" to _False_.
Ondrej Smolae6bcb292018-04-13 10:56:39 +0200551
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300552To enable Redis plugin for the Salt caching subsystem, use the
553below pillar structure:
Oleh Hryhorovca6b9172018-06-21 14:21:35 +0000554
555.. code-block:: yaml
556
557 salt:
558 master:
559 cache:
560 plugin: redis
561 host: localhost
562 port: 6379
563 db: '0'
564 password: pass_word
565 bank_prefix: 'MCP'
566 bank_keys_prefix: 'MCPKEY'
567 key_prefix: 'KEY'
568 separator: '@'
Ondrej Smolae6bcb292018-04-13 10:56:39 +0200569
Petr Michalecdf75d682018-02-07 13:43:53 +0100570Jinja options
571-------------
572
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300573Use the following options to update default Jinja renderer options.
574Salt recognize Jinja options for templates and for the ``sls`` files.
Petr Michalecdf75d682018-02-07 13:43:53 +0100575
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300576For full list of options, see Jinja documentation:
577http://jinja.pocoo.org/docs/api/#high-level-api
Petr Michalecdf75d682018-02-07 13:43:53 +0100578
579.. code-block:: yaml
580
Petr Michalecdf75d682018-02-07 13:43:53 +0100581 salt:
582 renderer:
583 # for templates
584 jinja: &jina_env
585 # Default Jinja environment options
586 block_start_string: '{%'
587 block_end_string: '%}'
588 variable_start_string: '{{'
589 variable_end_string: '}}'
590 comment_start_string: '{#'
591 comment_end_string: '#}'
592 keep_trailing_newline: False
593 newline_sequence: '\n'
594
595 # Next two are enabled by default in Salt
596 trim_blocks: True
597 lstrip_blocks: True
598
599 # Next two are not enabled by default in Salt
600 # but worth to consider to enable in future for salt-formulas
601 line_statement_prefix: '%'
602 line_comment_prefix: '##'
603
604 # for .sls state files
605 jinja_sls: *jinja_env
606
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300607With the ``line_statement/comment* _prefix`` options enabled following
608code statements are valid:
Petr Michalecdf75d682018-02-07 13:43:53 +0100609
610.. code-block:: yaml
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300611
Petr Michalecdf75d682018-02-07 13:43:53 +0100612 %- set myvar = 'one'
613
614 ## You can mix even with '{%'
615 {%- set myvar = 'two' %} ## comment
616 %- set mylist = ['one', 'two', 'three'] ## comment
617
618 ## comment
619 %- for item in mylist: ## comment
620 {{- item }}
621 %- endfor
622
Ivan Berezovskiy8aee9922019-07-15 18:21:22 +0400623Provision VM with secured image source.
624
625.. code-block:: yaml
626
627 salt:
628 control:
629 cluster:
630 mycluster:
631 domain: mydomain.com
632 engine: virt
633 node:
634 ubuntu01:
635 image_source:
636 secured: true
637 protocol: http
638 user: foo
639 password: bar
640 url_prefix: mirror.com
641 url_path: xenial/image.qcow2
642
643Provision several VMs with same secured image source.
644
645 salt:
646 control:
647 common_image_source:
648 protocol: https
649 user: foo
650 password: bar
651 url_prefix: mirror.com
652 cluster:
653 mycluster:
654 domain: mydomain.com
655 engine: virt
656 node:
657 ubuntu01:
658 image_source:
659 secured: true
660 url_path: xenial/ubuntu.qcow2
661 debian01:
662 image_source:
663 secured: true
664 url_path: stretch/debian.qcow2
665
Dzmitry Stremkouskib71ada92019-04-05 22:37:59 +0200666MCP Cluster health checks
667~~~~~~~~~~~~~~~~~~~~~~~~~
668
669Swiss army knife toolset for verifying MCP cluster health.
670
671.. note:: Health checks are tested with salt modules >= 2017.7.
672
673Install health_checks module:
674
675.. code-block:: bash
676
677 cp health_checks.py /usr/share/salt-formulas/env/_modules/health_checks.py
678 salt -C '*' saltutil.sync_all
679
680Usually exit codes are not catched and salt-call for a module
681will always return exit 0 regardless of errors in output.
682If you want control exit code for scripting, you should pass
683**--retcode-passthrough** to each salt call:
684
685.. code-block:: bash
686
687 salt-call health_checks.minions_check --retcode-passthrough
688
689Verify if minions are online.
690Use it to determine which minions are offline.
691
692.. code-block:: bash
693
694 salt-call health_checks.minions_check
695
696Verify time diff on your minions:
697
698.. code-block:: bash
699
700 salt-call health_checks.time_diff_check
701
702In case of failure, dump diff JSON:
703
704.. code-block:: bash
705
706 salt-call health_checks.time_diff_check debug=True --out=json
707
708Get JSON stats from ntpq:
709
710.. code-block:: bash
711
712 salt-call health_checks.ntp_status
713
714Verify NTP peers status on the environment:
715
716.. code-block:: bash
717
718 salt-call health_checks.ntp_check
719 salt-call health_checks.ntp_check min_peers=2 max_stratum=2
720
721Verify contrail nodes contrail-status output:
722
723.. code-block:: bash
724
725 salt-call health_checks.contrail_check debug=True
726
727Verify galera cluster status:
728
729.. code-block:: bash
730
731 salt-call health_checks.galera_check debug=True
732 salt-call health_checks.galera_check cluster_size=3 debug=True
733
734Verify rabbitmq cluster status:
735
736.. code-block:: bash
737
738 salt-call health_checks.mysql_check debug=True
739
740Get rabbitmq json objects on command execution.
741
742.. warning:: This code is experimental. It is a hack to convert erlang object to JSON. May fail.
743
744.. code-block:: bash
745
746 salt-call health_checks.rabbitmq_cmd status
747 salt-call health_checks.rabbitmq_cmd cluster_status
748 salt-call health_checks.rabbitmq_cmd list_hashes
749 salt-call health_checks.rabbitmq_cmd list_ciphers
750
Dzmitry Stremkouskif1bcbb52019-04-11 15:48:24 +0200751Get rabbitmq json dict of queues on the node (vhost '/' by default)
752
753.. code-block:: bash
754
755 salt -C 's-msg01*' health_checks.rabbitmq_list_queues
756 salt -C 's-msg01*' health_checks.rabbitmq_list_queues /openstack
757
Dzmitry Stremkouskib71ada92019-04-05 22:37:59 +0200758Verify haproxy upstream status:
759
760.. code-block:: bash
761
762 salt-call health_checks.haproxy_check debug=True
763 salt-call health_checks.haproxy_check ignore_no_upstream=True
764
765Get haproxy JSON stats (native python calls to socket):
766
767.. code-block:: bash
768
769 salt-call health_checks.haproxy_status
770 salt-call health_checks.haproxy_status socket_path='/var/run/haproxy/admin.sock' stats_filter=['status']
771
772Verify disk space usage:
773
774.. code-block:: bash
775
776 salt-call health_checks.df_check
777 salt-call health_checks.df_check verify=space space_limit=90 ignore_partitions=['/']
778
779Verify disk inodes usage:
780
781.. code-block:: bash
782
783 salt-call health_checks.df_check verify=inodes
784 salt-call health_checks.df_check verify=inodes inode_limit=10
785
786Verify load average on the environment:
787
788.. code-block:: bash
789
790 salt-call health_checks.load_check
791 salt-call health_checks.load_check la1=4 la5=1 la15=1
792
793Verify ifaces rx/tx drops:
794
795.. code-block:: bash
796
797 salt-call health_checks.netdev_check
798 salt-call health_checks.netdev_check rx_drop_limit=0 tx_drop_limit=0
799
800Verify memory usage:
801
802.. code-block:: bash
803
804 salt-call health_checks.mem_check
805 salt-call health_checks.mem_check used_limit=50
806
Dzmitry Stremkouskif1bcbb52019-04-11 15:48:24 +0200807Verify ceph health status:
808
809.. code-block:: bash
810
811 salt-call health_checks.ceph_health_check
812 salt-call health_checks.ceph_health_check target=s-mon01* target_type=glob debug=True
813
814Execute arbitrary ceph command and get JSON output:
815
816.. code-block:: bash
817
818 salt -C 'cmn01*' health_checks.ceph_cmd 'osd tree'
819
820Retrieve docker registry recursively:
821
822.. code-block:: bash
823
824 salt-call health_checks.docker_registry_list s-apt01:5000
825 salt-call health_checks.docker_registry_list http://127.0.0.1:5000
826
Dzmitry Stremkouski7cd10fc2019-04-17 11:51:59 +0200827Retrieve docker containers list on target server:
828
829.. code-block:: bash
830
831 salt -C 'cid01*' health_checks.docker_ps
832 salt -C 'cid01*' health_checks.docker_ps list_all=1
833
Dzmitry Stremkouskif1bcbb52019-04-11 15:48:24 +0200834Retrieve glusterfs pool list:
835
836.. code-block:: bash
837
838 salt -C 'I@glusterfs:server and *02*' health_checks.gluster_pool_list
839
840Retrieve glusterfs volumes status:
841
842.. code-block:: bash
843
844 salt -C 'I@glusterfs:server and *02*' health_checks.gluster_volume_status
845
846Check glusterfs pool health and size:
847
848.. code-block:: bash
849
850 salt-call health_checks.gluster_pool_check
851 salt-call health_checks.gluster_pool_check expected_size=5
852
853Check glusterfs volumes bricks health and size:
854
855.. code-block:: bash
856
857 salt-call health_checks.gluster_volumes_check
858 salt-call health_checks.gluster_volumes_check expected_size=1 ignore_volumes=['/srv/volumes/aptly']
859
Dzmitry Stremkouski7cd10fc2019-04-17 11:51:59 +0200860Retrieve entropy size for host:
861
862.. code-block:: bash
863
864 salt -C 'msg02*' health_checks.get_entropy
865
866Check entropy size on all nodes:
867
868.. code-block:: bash
869
870 salt-call health_checks.entropy_check
871 salt-call health_checks.entropy_check minimum_bits=1000
872
Dzmitry Stremkouskib71ada92019-04-05 22:37:59 +0200873
Dzmitry Stremkouski2c709f22019-04-22 02:27:54 +0200874Execute zookeeper cmds via socket:
875
876.. code-block:: bash
877
878 salt -C s-ntw01* health_checks.zookeeper_cmd conf
879 salt -C s-ntw01* health_checks.zookeeper_cmd envi
880
881Retrieve zookeeper stats:
882
883.. code-block:: bash
884
885 salt -C s-ntw01* health_checks.zookeeper_stats
886
887Retrieve zookeeper leader:
888
889.. code-block:: bash
890
891 salt-call health_checks.get_zookeeper_leader
892
893Fetch contrail vrouter list from control node
894
895.. code-block:: bash
896
897 salt -C s-ntw01* health_checks.contrail_vrouter_list
898
899Fetch contrail vrouter summary from control node
900
901.. code-block:: bash
902
903 salt -C s-ntw01* health_checks.contrail_vrouter_show <vr_uuid>
904
905Fetch contrail vrouter agent connections from compute node
906
907.. code-block:: bash
908
909 salt -C cmp001* health_checks.contrail_vrouter_agent_status
910
Dzmitry Stremkouski36290202019-05-05 21:26:25 +0200911Retrieve contrail vrouter agent status from analyticsdb
912
913.. code-block:: bash
914
915 salt-call health_checks.contrail_collector_agent_status
916
917Retrieve filtered contrail vrouter agent info from analyticsdb
918
919.. code-block:: bash
920
921 salt-call health_checks.contrail_vrouter_agent_info cmp001
922
Dzmitry Stremkouskia78a04d2019-07-13 11:05:03 +0200923Retrieve contrail control peers summary
924
925.. code-block:: bash
926
927 salt -C s-ntw01* health_checks.contrail_control_peers_summary
928
929Retrieve contrail control filtered peers info
930
931.. code-block:: bash
932
933 salt -C s-ntw03* health_checks.contrail_control_peer_status
934
Dzmitry Stremkouski2c709f22019-04-22 02:27:54 +0200935Fetch libvirt supported machine types for compute node
936
937.. code-block:: bash
938
939 salt -C 'I@opencontrail:compute' health_checks.libvirt_capabilities
940
Dzmitry Stremkouski88275d32019-07-23 19:42:42 +0200941Check keystone fernet keys are in sync
942
943.. code-block:: bash
944
945 salt-call health_checks.keystone_keys_check
946 salt-call health_checks.keystone_keys_check keys_dir='/var/lib/keystone/fernet-keys'
947
948Check keystone credential keys are in sync
949
950.. code-block:: bash
951
952 salt-call health_checks.keystone_keys_check keys_type='credential'
953
Dzmitry Stremkouski2c709f22019-04-22 02:27:54 +0200954
Petr Michalecdf75d682018-02-07 13:43:53 +0100955Encrypted pillars
Ales Komarekd768f1c2018-01-30 22:37:18 +0100956~~~~~~~~~~~~~~~~~
Petr Michalec1f541c42017-08-17 13:30:37 +0200957
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300958.. note:: NACL and the below configuration will be available in Salt > 2017.7.
Petr Michalec1f541c42017-08-17 13:30:37 +0200959
960External resources:
961
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300962- Tutorial to configure the Salt and Reclass ``ext_pillar`` and NACL:
963 http://apealive.net/post/2017-09-salt-nacl-ext-pillar/
964- SaltStack documentation:
965 https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.nacl.html
Petr Michalec1f541c42017-08-17 13:30:37 +0200966
967Configure salt NACL module:
968
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300969.. code-block:: bash
Petr Michalec1f541c42017-08-17 13:30:37 +0200970
971 pip install --upgrade libnacl===1.5.2
972 salt-call --local nacl.keygen /etc/salt/pki/master/nacl
973
974 local:
975 saved sk_file:/etc/salt/pki/master/nacl pk_file: /etc/salt/pki/master/nacl.pub
976
Petr Michalec1f541c42017-08-17 13:30:37 +0200977.. code-block:: yaml
978
979 salt:
980 master:
981 pillar:
982 reclass: *reclass
983 nacl:
984 index: 99
985 nacl:
986 box_type: sealedbox
987 sk_file: /etc/salt/pki/master/nacl
988 pk_file: /etc/salt/pki/master/nacl.pub
989 #sk: None
990 #pk: None
991
992NACL encrypt secrets:
993
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +0300994.. code-block:: bash
995
Petr Michalec1f541c42017-08-17 13:30:37 +0200996 salt-call --local nacl.enc 'my_secret_value' pk_file=/etc/salt/pki/master/nacl.pub
997 hXTkJpC1hcKMS7yZVGESutWrkvzusXfETXkacSklIxYjfWDlMJmR37MlmthdIgjXpg4f2AlBKb8tc9Woma7q
998 # or
999 salt-run nacl.enc 'myotherpass'
1000 ADDFD0Rav6p6+63sojl7Htfrncp5rrDVyeE4BSPO7ipq8fZuLDIVAzQLf4PCbDqi+Fau5KD3/J/E+Pw=
1001
Petr Michalec1f541c42017-08-17 13:30:37 +02001002NACL encrypted values on pillar:
1003
1004Use Boxed syntax `NACL[CryptedValue=]` to encode value on pillar:
1005
1006.. code-block:: yaml
1007
1008 my_pillar:
1009 my_nacl:
1010 key0: unencrypted_value
1011 key1: NACL[hXTkJpC1hcKMS7yZVGESutWrkvzusXfETXkacSklIxYjfWDlMJmR37MlmthdIgjXpg4f2AlBKb8tc9Woma7q]
1012
1013NACL large files:
1014
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001015.. code-block:: bash
1016
Petr Michalec1f541c42017-08-17 13:30:37 +02001017 salt-call nacl.enc_file /tmp/cert.crt out=/srv/salt/env/dev/cert.nacl
1018 # or more advanced
1019 cert=$(cat /tmp/cert.crt)
1020 salt-call --out=newline_values_only nacl.enc_pub data="$cert" > /srv/salt/env/dev/cert.nacl
1021
Petr Michalec1f541c42017-08-17 13:30:37 +02001022NACL within template/native pillars:
1023
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001024.. code-block:: yaml
1025
Petr Michalec1f541c42017-08-17 13:30:37 +02001026 pillarexample:
1027 user: root
1028 password1: {{salt.nacl.dec('DRB7Q6/X5gGSRCTpZyxS6hlbWj0llUA+uaVyvou3vJ4=')|json}}
1029 cert_key: {{salt.nacl.dec_file('/srv/salt/env/dev/certs/example.com/cert.nacl')|json}}
1030 cert_key2: {{salt.nacl.dec_file('salt:///certs/example.com/cert2.nacl')|json}}
1031
Ales Komarekd768f1c2018-01-30 22:37:18 +01001032Salt Syndic
Ales Komarek54740682017-05-15 07:16:23 +02001033-----------
1034
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001035The master of masters:
Ales Komarek54740682017-05-15 07:16:23 +02001036
1037.. code-block:: yaml
1038
1039 salt:
1040 master:
1041 enabled: true
1042 order_masters: True
1043
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001044Lower syndicated master:
Ales Komarek54740682017-05-15 07:16:23 +02001045
1046.. code-block:: yaml
1047
1048 salt:
1049 syndic:
1050 enabled: true
1051 master:
1052 host: master-of-master-host
1053 timeout: 5
1054
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001055Syndicated master with multiple master of masters:
Ales Komarek54740682017-05-15 07:16:23 +02001056
1057.. code-block:: yaml
1058
1059 salt:
1060 syndic:
1061 enabled: true
1062 masters:
1063 - host: master-of-master-host1
1064 - host: master-of-master-host2
1065 timeout: 5
1066
Ales Komarekd768f1c2018-01-30 22:37:18 +01001067Salt Minion
1068-----------
1069
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001070Minion ID by default triggers dependency on Linux formula, as it uses fqdn
1071configured from `linux.system.name` and `linux.system.domain` pillar.
1072To override, provide exact minion ID you require. The same can be set for
1073master ID rendered at ``master.conf``.
Petr Michaleccfd93e12018-06-26 18:11:44 +02001074
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001075 .. code-block:: yaml
Petr Michaleccfd93e12018-06-26 18:11:44 +02001076
1077 salt:
1078 minion:
1079 id: minion1.production
1080 master:
1081 id: master.production
1082
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001083Simplest Salt minion setup with central configuration node:
Ales Komarekd768f1c2018-01-30 22:37:18 +01001084
1085.. literalinclude:: tests/pillar/minion_master.sls
1086 :language: yaml
1087
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001088Multi-master Salt minion setup:
Ales Komarekd768f1c2018-01-30 22:37:18 +01001089
1090.. literalinclude:: tests/pillar/minion_multi_master.sls
1091 :language: yaml
1092
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001093Salt minion with salt mine options:
Ales Komarekd768f1c2018-01-30 22:37:18 +01001094
1095.. literalinclude:: tests/pillar/minion_mine.sls
1096 :language: yaml
1097
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001098Salt minion with graphing dependencies:
Ales Komarekd768f1c2018-01-30 22:37:18 +01001099
1100.. literalinclude:: tests/pillar/minion_graph.sls
1101 :language: yaml
1102
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001103Salt minion behind HTTP proxy:
Ales Komarekd768f1c2018-01-30 22:37:18 +01001104
1105.. code-block:: yaml
1106
1107 salt:
1108 minion:
1109 proxy:
1110 host: 127.0.0.1
1111 port: 3128
1112
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001113Salt minion to specify non-default HTTP backend. The default
1114tornado backend does not respect HTTP proxy settings set as
1115environment variables. This is useful for cases where you need
1116to set no_proxy lists.
Ales Komarekd768f1c2018-01-30 22:37:18 +01001117
1118.. code-block:: yaml
1119
1120 salt:
1121 minion:
1122 backend: urllib2
1123
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001124Salt minion with PKI certificate authority (CA):
Ales Komarekd768f1c2018-01-30 22:37:18 +01001125
1126.. literalinclude:: tests/pillar/minion_pki_ca.sls
1127 :language: yaml
1128
1129Salt minion using PKI certificate
1130
1131.. literalinclude:: tests/pillar/minion_pki_cert.sls
1132 :language: yaml
1133
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001134Salt minion trust CA certificates issued by salt CA on a
1135specific host (ie: salt-master node):
Ales Komarekd768f1c2018-01-30 22:37:18 +01001136
1137.. code-block:: yaml
1138
1139 salt:
1140 minion:
1141 trusted_ca_minions:
1142 - cfg01
1143
Ales Komarekd768f1c2018-01-30 22:37:18 +01001144Salt Minion Proxy
1145~~~~~~~~~~~~~~~~~
Jiri Broulika0f46682017-04-20 22:45:01 +02001146
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001147Salt proxy pillar:
Jiri Broulika0f46682017-04-20 22:45:01 +02001148
1149.. code-block:: yaml
1150
1151 salt:
1152 minion:
Jiri Broulik88275242017-05-24 17:21:17 +02001153 proxy_minion:
Jiri Broulika0f46682017-04-20 22:45:01 +02001154 master: localhost
1155 device:
1156 vsrx01.mydomain.local:
1157 enabled: true
1158 engine: napalm
1159 csr1000v.mydomain.local:
1160 enabled: true
1161 engine: napalm
1162
1163.. note:: This is pillar of the the real salt-minion
1164
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001165Proxy pillar for IOS device:
Jiri Broulika0f46682017-04-20 22:45:01 +02001166
1167.. code-block:: yaml
1168
1169 proxy:
1170 proxytype: napalm
1171 driver: ios
1172 host: csr1000v.mydomain.local
1173 username: root
1174 passwd: r00tme
1175
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001176.. note:: This is pillar of the node thats not able to run
1177 salt-minion itself.
Jiri Broulika0f46682017-04-20 22:45:01 +02001178
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001179Proxy pillar for JunOS device:
Jiri Broulika0f46682017-04-20 22:45:01 +02001180
1181.. code-block:: yaml
1182
1183 proxy:
1184 proxytype: napalm
1185 driver: junos
1186 host: vsrx01.mydomain.local
1187 username: root
1188 passwd: r00tme
1189 optional_args:
1190 config_format: set
1191
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001192.. note:: This pillar applies to the node that can not run
1193 salt-minion itself.
Ales Komarek8fb1da82016-08-21 23:52:03 +02001194
1195Salt SSH
Ales Komarekd768f1c2018-01-30 22:37:18 +01001196~~~~~~~~
Ales Komarek8fb1da82016-08-21 23:52:03 +02001197
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001198Salt SSH with sudoer using key:
Ales Komarek8fb1da82016-08-21 23:52:03 +02001199
1200.. literalinclude:: tests/pillar/master_ssh_minion_key.sls
1201 :language: yaml
1202
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001203Salt SSH with sudoer using password:
Ales Komarek8fb1da82016-08-21 23:52:03 +02001204
1205.. literalinclude:: tests/pillar/master_ssh_minion_password.sls
1206 :language: yaml
1207
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001208Salt SSH with root using password:
Ales Komarek8fb1da82016-08-21 23:52:03 +02001209
1210.. literalinclude:: tests/pillar/master_ssh_minion_root.sls
1211 :language: yaml
1212
Ales Komarek8ba9c0b2016-02-21 14:59:59 +01001213Salt control (cloud/kvm/docker)
1214-------------------------------
Filip Pytlounb4b80592015-10-06 16:28:32 +02001215
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001216Salt cloud with local OpenStack provider:
Filip Pytlounb4b80592015-10-06 16:28:32 +02001217
Ales Komarek8ba9c0b2016-02-21 14:59:59 +01001218.. literalinclude:: tests/pillar/control_cloud_openstack.sls
1219 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +02001220
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001221Salt cloud with Digital Ocean provider:
Filip Pytlounb4b80592015-10-06 16:28:32 +02001222
Ales Komarek8ba9c0b2016-02-21 14:59:59 +01001223.. literalinclude:: tests/pillar/control_cloud_digitalocean.sls
1224 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +02001225
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001226Salt virt with KVM cluster:
Filip Pytlounb4b80592015-10-06 16:28:32 +02001227
Ales Komarek8ba9c0b2016-02-21 14:59:59 +01001228.. literalinclude:: tests/pillar/control_virt.sls
1229 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +02001230
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001231Salt virt with custom destination for image file:
Mateusz Los4c7cd2d2018-01-09 11:46:07 +01001232
1233.. literalinclude:: tests/pillar/control_virt_custom.sls
1234 :language: yaml
1235
Dmitry Teselkin9b3097a2018-11-21 15:45:07 +03001236Salt shared library
1237-------------------
1238
1239This formula includes 'sharedlib' execution module which is a kind
1240of 'library' of function and / or classes to be used in Jinja templates
1241or directly as execution module.
1242
1243'sharedlib' implements a loader that is able to scan nested directories
1244and import Python classes / functions from nested modules. Salt doesn't
1245allow this as it only imports top-level modules:
1246
1247https://github.com/saltstack/salt/issues/37273
1248
1249'sharedlib' implements 4 main functions:
1250
1251* 'sharedlib.list' - search and print functions / classes found in nested directories
1252* 'sharedlib.info' - print docstring of a function (if it exists)
1253* 'sharedlib.get' - get function / class object, but not execute it immediately
1254* 'sharedlib.call' - get function / class and execute / initialize it with
1255 arguments given.
1256
1257Each of the commands above also have it's own docstring so it's possible to
1258use them on a system:
1259
1260.. code-block:: text
1261
1262 # salt-call sys.doc sharedlib.list
1263 local:
1264 ----------
1265 sharedlib.list:
1266
1267 List available functions.
1268
1269 .. code-block::
1270
1271 salt-call sharedlib.list
1272
1273Usage examples:
1274
1275.. code-block:: text
1276
1277 # salt-call sharedlib.list
1278 local:
1279 ----------
1280 sharedlib.list:
1281 ----------
1282 classes:
1283 - misc.Test
1284 - misc2.Test
1285 functions:
1286 - misc.cast_dict_keys_to_int
1287
1288.. code-block:: text
1289
1290 # salt-call sharedlib.info misc.cast_dict_keys_to_int
1291 local:
1292 ----------
1293 sharedlib.info:
1294 ----------
1295 misc.cast_dict_keys_to_int:
1296
1297 Return a dictionary with keys casted to int.
1298 This usually is required when you want sort the dict later.
1299
1300 Jinja example:
1301
1302 .. code-block: jinja
1303
1304 {%- set ruleset = salt['sharedlib.call']('misc.cast_dict_keys_to_int', c.get('ruleset', {})) %}
1305
1306 .. code-block:: jinja
1307
1308 {%- set func = salt['sharedlib.get']('misc.cast_dict_keys_to_int') %}
1309 {%- for c_name, c in t.chains.items() %}
1310 {%- set ruleset = func(c.get('ruleset', {})) %}
1311 {%- for rule_id, r in ruleset | dictsort %}
1312 ...
1313 {%- endfor %}
1314
Oleksandr Shyshko17176942019-02-06 17:08:23 +02001315Procedure of Data model and Schemas validation.
1316-------------------
1317Salt formula supports several mechanisms which allows to validate data model by jsonschema validator.
1318It supports unversioned schemas which must be contained at:
1319
1320.. code-block:: text
1321 'salt://{}/schemas/{}.yaml'.format(service, role)
1322
1323and/or versioned schemas which must be contained at:
1324
1325.. code-block:: text
1326 'salt://{}/schemas/{}/{}.yaml'.format(service, version, role)
1327
1328Returns list of all defined schema files.
1329
1330.. code-block:: bash
1331 salt-call modelschema.schema_list
1332
1333Returns pillar schema for given service and role.
1334
1335.. code-block:: bash
1336
1337 salt-call modelschema.schema_get ntp server
1338 .. or ..
1339 salt-call modelschema.schema_get keystone server pike
1340
1341Validates pillar schema itself of given service and role.
1342
1343.. code-block:: bash
1344
1345 salt-call modelschema.schema_validate ntp server
1346 .. or ..
1347 salt-call modelschema.schema_validate keystone server pike
1348
1349Validates pillar metadata by schema for given service and role.
1350
1351.. code-block:: bash
1352
1353 salt-call modelschema.model_validate ntp server
1354 .. or ..
1355 salt-call modelschema.model_validate keystone server pike
1356
1357Validates pillar metadata by schema for given service and role.
1358
1359.. code-block:: bash
1360 salt-run modelschema.data_validate {'a': 'b'} {'a': 'b'}
1361
1362Generate pillar schema skeleton for given service. Method iterates throught
1363test pillars and generates schema scaffold structure in JSON format that
1364can be passed to service like http://jsonschema.net/ to get the basic
1365schema for the individual roles of the service.
1366
1367.. code-block:: bash
1368
1369 salt-call modelschema.schema_from_tests ntp
1370 .. or ..
1371 salt-call modelschema.schema_from_tests keystone pike
1372
1373You can read more about it here:
1374 http://json-schema.org/implementations.html
1375 https://github.com/Julian/jsonschema
Dmitry Teselkin9b3097a2018-11-21 15:45:07 +03001376
Filip Pytlounb4b80592015-10-06 16:28:32 +02001377Usage
1378=====
1379
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001380Working with salt-cloud:
Filip Pytlounb4b80592015-10-06 16:28:32 +02001381
1382.. code-block:: bash
1383
1384 salt-cloud -m /path/to/map --assume-yes
1385
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001386Debug LIBCLOUD for salt-cloud connection:
Filip Pytlounb4b80592015-10-06 16:28:32 +02001387
1388.. code-block:: bash
1389
1390 export LIBCLOUD_DEBUG=/dev/stderr; salt-cloud --list-sizes provider_name --log-level all
1391
OlgaGusarenkof1fd82e2018-07-31 01:20:49 +03001392Read more
1393=========
Filip Pytlounb4b80592015-10-06 16:28:32 +02001394
1395* http://salt.readthedocs.org/en/latest/
1396* https://github.com/DanielBryan/salt-state-graph
1397* http://karlgrz.com/testing-salt-states-rapidly-with-docker/
1398* https://mywushublog.com/2013/03/configuration-management-with-salt-stack/
1399* http://russell.ballestrini.net/replace-the-nagios-scheduler-and-nrpe-with-salt-stack/
1400* https://github.com/saltstack-formulas/salt-formula
1401* http://docs.saltstack.com/en/latest/topics/tutorials/multimaster.html
1402
1403salt-cloud
1404----------
1405
1406* http://www.blog.sandro-mathys.ch/2013/07/setting-user-password-when-launching.html
1407* http://cloudinit.readthedocs.org/en/latest/topics/examples.html
1408* http://salt-cloud.readthedocs.org/en/latest/topics/install/index.html
1409* http://docs.saltstack.com/topics/cloud/digitalocean.html
1410* http://salt-cloud.readthedocs.org/en/latest/topics/rackspace.html
1411* http://salt-cloud.readthedocs.org/en/latest/topics/map.html
1412* http://docs.saltstack.com/en/latest/topics/tutorials/multimaster.html