blob: cd9abc671b5a8f6799459ff7781f5f05bf80e955 [file] [log] [blame]
Filip Pytlounb4b80592015-10-06 16:28:32 +02001
Ales Komarek54740682017-05-15 07:16:23 +02002============
3Salt Formula
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 +020013
14Sample Metadata
15===============
16
Filip Pytlounb4b80592015-10-06 16:28:32 +020017
Ales Komarekd768f1c2018-01-30 22:37:18 +010018Salt Master
Filip Pytlounb4b80592015-10-06 16:28:32 +020019-----------
20
Ales Komarek54740682017-05-15 07:16:23 +020021Salt master with base formulas and pillar metadata backend
Filip Pytlounb4b80592015-10-06 16:28:32 +020022
Ales Komarek8ba9c0b2016-02-21 14:59:59 +010023.. literalinclude:: tests/pillar/master_single_pillar.sls
24 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +020025
Ales Komarek54740682017-05-15 07:16:23 +020026Salt master with reclass ENC metadata backend
Filip Pytlounb4b80592015-10-06 16:28:32 +020027
Ales Komarek8ba9c0b2016-02-21 14:59:59 +010028.. literalinclude:: tests/pillar/master_single_reclass.sls
29 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +020030
Ales Komarek459407b2018-01-18 17:16:31 +010031Salt master with Architect ENC metadata backend
32
33.. code-block:: yaml
34
35 salt:
36 master:
37 enabled: true
38 pillar:
39 engine: architect
40 project: project-name
41 host: architect-api
42 port: 8181
43 username: salt
44 password: password
45
Petr Michalec1f541c42017-08-17 13:30:37 +020046Salt master with multiple ext_pillars
47
48.. literalinclude:: tests/pillar/master_single_extpillars.sls
49 :language: yaml
50
Filip Pytlounb4b80592015-10-06 16:28:32 +020051Salt master with API
52
Ales Komarekb2c8ff62016-08-22 00:20:01 +020053.. literalinclude:: tests/pillar/master_api.sls
54 :language: yaml
Ales Komarekcdb280f2016-07-27 15:37:51 +020055
56Salt master with defined user ACLs
57
Ales Komarekb2c8ff62016-08-22 00:20:01 +020058.. literalinclude:: tests/pillar/master_acl.sls
59 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +020060
61Salt master with preset minions
62
63.. code-block:: yaml
64
65 salt:
66 master:
67 enabled: true
Filip Pytlounb4b80592015-10-06 16:28:32 +020068 minions:
69 - name: 'node1.system.location.domain.com'
70
Ales Komarek54740682017-05-15 07:16:23 +020071Salt master with pip based installation (optional)
Adam Tenglercaedd972016-05-04 16:44:00 +020072
73.. code-block:: yaml
74
75 salt:
76 master:
77 enabled: true
78 ...
79 source:
80 engine: pip
81 version: 2016.3.0rc2
82
Ales Komarek54740682017-05-15 07:16:23 +020083Install formula through system package management
Adam Tengler3eb85ad2016-05-06 02:52:40 +020084
85.. code-block:: yaml
86
87 salt:
88 master:
89 enabled: true
90 ...
91 environment:
92 prd:
Petr Michalec7a2f1d22017-05-17 22:08:32 +020093 keystone:
Adam Tengler3eb85ad2016-05-06 02:52:40 +020094 source: pkg
95 name: salt-formula-keystone
Petr Michalec7a2f1d22017-05-17 22:08:32 +020096 nova:
97 source: pkg
98 name: salt-formula-keystone
99 version: 0.1+0~20160818133412.24~1.gbp6e1ebb
100 postresql:
101 source: pkg
102 name: salt-formula-postgresql
103 version: purged
104
105Formula keystone is installed latest version and the formulas without version are installed in one call to aptpkg module.
106If the version attribute is present sls iterates over formulas and take action to install specific version or remove it.
107The version attribute may have these values ``[latest|purged|removed|<VERSION>]``.
Adam Tengler3eb85ad2016-05-06 02:52:40 +0200108
109Clone master branch of keystone formula as local feature branch
110
111.. code-block:: yaml
112
113 salt:
114 master:
115 enabled: true
116 ...
117 environment:
118 dev:
119 formula:
120 keystone:
121 source: git
122 address: git@github.com:openstack/salt-formula-keystone.git
123 revision: master
124 branch: feature
125
126Salt master with specified formula refs (for example for Gerrit review)
127
128.. code-block:: yaml
129
130 salt:
131 master:
132 enabled: true
133 ...
134 environment:
135 dev:
136 formula:
137 keystone:
138 source: git
139 address: https://git.openstack.org/openstack/salt-formula-keystone
140 revision: refs/changes/56/123456/1
141
Ales Komarek54740682017-05-15 07:16:23 +0200142Salt master with logging handlers
Filip Pytlounb4b80592015-10-06 16:28:32 +0200143
144.. code-block:: yaml
145
146 salt:
147 master:
148 enabled: true
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100149 handler:
150 handler01:
151 engine: udp
152 bind:
153 host: 127.0.0.1
154 port: 9999
Filip Pytlounb4b80592015-10-06 16:28:32 +0200155 minion:
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100156 handler:
157 handler01:
158 engine: udp
159 bind:
160 host: 127.0.0.1
161 port: 9999
162 handler02:
163 engine: zmq
164 bind:
165 host: 127.0.0.1
166 port: 9999
167
Ales Komareka9fc6e72017-09-06 15:02:40 +0200168Salt engine definition for saltgraph metadata collector
169
170.. code-block:: yaml
171
172 salt:
173 master:
174 engine:
175 graph_metadata:
176 engine: saltgraph
177 host: 127.0.0.1
178 port: 5432
179 user: salt
180 password: salt
181 database: salt
182
Ales Komarek459407b2018-01-18 17:16:31 +0100183Salt engine definition for Architect service
184
185.. code-block:: yaml
186
187 salt:
188 master:
189 engine:
190 architect:
191 engine: architect
192 project: project-name
193 host: architect-api
194 port: 8181
195 username: salt
196 password: password
197
Ales Komareka9fc6e72017-09-06 15:02:40 +0200198Salt engine definition for sending events from docker events
199
200.. code-block:: yaml
201
202 salt:
203 master:
204 engine:
205 docker_events:
206 docker_url: unix://var/run/docker.sock
207
Ales Komarek54740682017-05-15 07:16:23 +0200208Salt master peer setup for remote certificate signing
Jakub Pavlikd4859842016-05-23 10:48:04 +0200209
210.. code-block:: yaml
211
212 salt:
213 master:
214 peer:
215 ".*":
216 - x509.sign_remote_certificate
Filip Pytlounb4b80592015-10-06 16:28:32 +0200217
Ales Komarekb2ada522017-12-07 11:31:32 +0100218
219Salt master backup configuration
220
221.. code-block:: yaml
222
223 salt:
224 master:
225 backup: true
226 initial_data:
227 engine: backupninja
228 source: backup-node-host
229 host: original-salt-master-id
230
Tomáš Kukrál8922aef2017-05-10 10:27:04 +0200231Configure verbosity of state output (used for `salt` command)
232
233.. code-block:: yaml
234
235 salt:
236 master:
Tomáš Kukrál044667b2017-05-11 10:12:15 +0200237 state_output: changes
Tomáš Kukrál8922aef2017-05-10 10:27:04 +0200238
Ales Komarekd768f1c2018-01-30 22:37:18 +0100239Pass pillar render error to minion log
240
241.. note:: When set to `False` this option is great for debuging.
242 However it is not recomended for any production environment as it may contain
243 templating data as passwords, etc... , that minion should not expose.
244
245.. code-block:: yaml
246
247 salt:
248 master:
249 pillar_safe_render_error: False
250
251
252Event/Reactor Systems
253~~~~~~~~~~~~~~~~~~~~~
Petr Michalec1f541c42017-08-17 13:30:37 +0200254
Ales Komareke7844d12017-06-08 12:00:01 +0200255Salt synchronise node pillar and modules after start
Ales Komarek54740682017-05-15 07:16:23 +0200256
257.. code-block:: yaml
258
259 salt:
260 master:
261 reactor:
262 salt/minion/*/start:
Ales Komareke7844d12017-06-08 12:00:01 +0200263 - salt://salt/reactor/node_start.sls
Ales Komarek54740682017-05-15 07:16:23 +0200264
Ales Komareke7844d12017-06-08 12:00:01 +0200265Trigger basic node install
266
267.. code-block:: yaml
268
269 salt:
270 master:
271 reactor:
272 salt/minion/install:
273 - salt://salt/reactor/node_install.sls
274
275Sample event to trigger the node installation
276
277.. code-block:: bash
278
279 salt-call event.send 'salt/minion/install'
280
Ales Komarek213fbe02017-08-21 16:39:05 +0200281Run any defined orchestration pipeline
Ales Komarek5c58de32017-06-06 11:49:32 +0200282
283.. code-block:: yaml
284
285 salt:
286 master:
287 reactor:
288 salt/orchestrate/start:
289 - salt://salt/reactor/orchestrate_start.sls
290
Ales Komareke7844d12017-06-08 12:00:01 +0200291Event to trigger the orchestration pipeline
Ales Komarek5c58de32017-06-06 11:49:32 +0200292
293.. code-block:: bash
294
Ales Komareke7844d12017-06-08 12:00:01 +0200295 salt-call event.send 'salt/orchestrate/start' "{'orchestrate': 'salt/orchestrate/infra_install.sls'}"
Ales Komarek5c58de32017-06-06 11:49:32 +0200296
Ales Komarek3ed7c432017-08-24 16:15:49 +0200297Synchronise modules and pillars on minion start.
298
299.. code-block:: yaml
300
301 salt:
302 master:
303 reactor:
304 'salt/minion/*/start':
305 - salt://salt/reactor/minion_start.sls
306
Ales Komarek213fbe02017-08-21 16:39:05 +0200307Add and/or remove the minion key
Ales Komarek5c58de32017-06-06 11:49:32 +0200308
309.. code-block:: yaml
310
311 salt:
312 master:
313 reactor:
Ales Komarek213fbe02017-08-21 16:39:05 +0200314 salt/key/create:
315 - salt://salt/reactor/key_create.sls
316 salt/key/remove:
317 - salt://salt/reactor/key_remove.sls
Ales Komarek5c58de32017-06-06 11:49:32 +0200318
Ales Komarek213fbe02017-08-21 16:39:05 +0200319Event to trigger the key creation
Ales Komarek5c58de32017-06-06 11:49:32 +0200320
321.. code-block:: bash
322
Adam Tengler62188962017-09-04 13:34:44 +0000323 salt-call event.send 'salt/key/create' \
324 > "{'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 +0200325
Ales Komarek213fbe02017-08-21 16:39:05 +0200326.. note::
327
328 You can add pass additional `orch_pre_create`, `orch_post_create`,
329 `orch_pre_remove` or `orch_post_remove` parameters to the event to call
330 extra orchestrate files. This can be useful for example for
331 registering/unregistering nodes from the monitoring alarms or dashboards.
332
333 The key creation event needs to be run from other machine than the one
334 being registered.
335
336Event to trigger the key removal
337
338.. code-block:: bash
339
340 salt-call event.send 'salt/key/remove'
Ales Komarek54740682017-05-15 07:16:23 +0200341
Petr Michalec1f541c42017-08-17 13:30:37 +0200342
Ales Komarekd768f1c2018-01-30 22:37:18 +0100343Encrypted Pillars
344~~~~~~~~~~~~~~~~~
Petr Michalec1f541c42017-08-17 13:30:37 +0200345
346Note: NACL + below configuration will be available in Salt > 2017.7.
347
348External resources:
349
350- Tutorial to configure salt + reclass ext_pillar and nacl: http://apealive.net/post/2017-09-salt-nacl-ext-pillar/
351- Saltstack documentation: https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.nacl.html
352
353Configure salt NACL module:
354
355.. code-block:: shell
356
357 pip install --upgrade libnacl===1.5.2
358 salt-call --local nacl.keygen /etc/salt/pki/master/nacl
359
360 local:
361 saved sk_file:/etc/salt/pki/master/nacl pk_file: /etc/salt/pki/master/nacl.pub
362
363
364.. code-block:: yaml
365
366 salt:
367 master:
368 pillar:
369 reclass: *reclass
370 nacl:
371 index: 99
372 nacl:
373 box_type: sealedbox
374 sk_file: /etc/salt/pki/master/nacl
375 pk_file: /etc/salt/pki/master/nacl.pub
376 #sk: None
377 #pk: None
378
379NACL encrypt secrets:
380
381 salt-call --local nacl.enc 'my_secret_value' pk_file=/etc/salt/pki/master/nacl.pub
382 hXTkJpC1hcKMS7yZVGESutWrkvzusXfETXkacSklIxYjfWDlMJmR37MlmthdIgjXpg4f2AlBKb8tc9Woma7q
383 # or
384 salt-run nacl.enc 'myotherpass'
385 ADDFD0Rav6p6+63sojl7Htfrncp5rrDVyeE4BSPO7ipq8fZuLDIVAzQLf4PCbDqi+Fau5KD3/J/E+Pw=
386
387
388NACL encrypted values on pillar:
389
390Use Boxed syntax `NACL[CryptedValue=]` to encode value on pillar:
391
392.. code-block:: yaml
393
394 my_pillar:
395 my_nacl:
396 key0: unencrypted_value
397 key1: NACL[hXTkJpC1hcKMS7yZVGESutWrkvzusXfETXkacSklIxYjfWDlMJmR37MlmthdIgjXpg4f2AlBKb8tc9Woma7q]
398
399NACL large files:
400
401.. code-block:: shell
402 salt-call nacl.enc_file /tmp/cert.crt out=/srv/salt/env/dev/cert.nacl
403 # or more advanced
404 cert=$(cat /tmp/cert.crt)
405 salt-call --out=newline_values_only nacl.enc_pub data="$cert" > /srv/salt/env/dev/cert.nacl
406
407
408NACL within template/native pillars:
409
410 pillarexample:
411 user: root
412 password1: {{salt.nacl.dec('DRB7Q6/X5gGSRCTpZyxS6hlbWj0llUA+uaVyvou3vJ4=')|json}}
413 cert_key: {{salt.nacl.dec_file('/srv/salt/env/dev/certs/example.com/cert.nacl')|json}}
414 cert_key2: {{salt.nacl.dec_file('salt:///certs/example.com/cert2.nacl')|json}}
415
Ales Komarekd768f1c2018-01-30 22:37:18 +0100416
417Salt Syndic
Ales Komarek54740682017-05-15 07:16:23 +0200418-----------
419
420The master of masters
421
422.. code-block:: yaml
423
424 salt:
425 master:
426 enabled: true
427 order_masters: True
428
429Lower syndicated master
430
431.. code-block:: yaml
432
433 salt:
434 syndic:
435 enabled: true
436 master:
437 host: master-of-master-host
438 timeout: 5
439
440Syndicated master with multiple master of masters
441
442.. code-block:: yaml
443
444 salt:
445 syndic:
446 enabled: true
447 masters:
448 - host: master-of-master-host1
449 - host: master-of-master-host2
450 timeout: 5
451
452
Ales Komarekd768f1c2018-01-30 22:37:18 +0100453Salt Minion
454-----------
455
456Simplest Salt minion setup with central configuration node
457
458.. code-block:: yaml
459
460.. literalinclude:: tests/pillar/minion_master.sls
461 :language: yaml
462
463Multi-master Salt minion setup
464
465.. literalinclude:: tests/pillar/minion_multi_master.sls
466 :language: yaml
467
468Salt minion with salt mine options
469
470.. literalinclude:: tests/pillar/minion_mine.sls
471 :language: yaml
472
473Salt minion with graphing dependencies
474
475.. literalinclude:: tests/pillar/minion_graph.sls
476 :language: yaml
477
478Salt minion behind HTTP proxy
479
480.. code-block:: yaml
481
482 salt:
483 minion:
484 proxy:
485 host: 127.0.0.1
486 port: 3128
487
488Salt minion to specify non-default HTTP backend. The default tornado backend
489does not respect HTTP proxy settings set as environment variables. This is
490useful for cases where you need to set no_proxy lists.
491
492.. code-block:: yaml
493
494 salt:
495 minion:
496 backend: urllib2
497
498
499Salt minion with PKI certificate authority (CA)
500
501.. literalinclude:: tests/pillar/minion_pki_ca.sls
502 :language: yaml
503
504Salt minion using PKI certificate
505
506.. literalinclude:: tests/pillar/minion_pki_cert.sls
507 :language: yaml
508
509Salt minion trust CA certificates issued by salt CA on a specific host (ie: salt-master node)
510
511.. code-block:: yaml
512
513 salt:
514 minion:
515 trusted_ca_minions:
516 - cfg01
517
518
519Salt Minion Proxy
520~~~~~~~~~~~~~~~~~
Jiri Broulika0f46682017-04-20 22:45:01 +0200521
522Salt proxy pillar
523
524.. code-block:: yaml
525
526 salt:
527 minion:
Jiri Broulik88275242017-05-24 17:21:17 +0200528 proxy_minion:
Jiri Broulika0f46682017-04-20 22:45:01 +0200529 master: localhost
530 device:
531 vsrx01.mydomain.local:
532 enabled: true
533 engine: napalm
534 csr1000v.mydomain.local:
535 enabled: true
536 engine: napalm
537
538.. note:: This is pillar of the the real salt-minion
539
540
541Proxy pillar for IOS device
542
543.. code-block:: yaml
544
545 proxy:
546 proxytype: napalm
547 driver: ios
548 host: csr1000v.mydomain.local
549 username: root
550 passwd: r00tme
551
552.. note:: This is pillar of the node thats not able to run salt-minion itself
553
554
555Proxy pillar for JunOS device
556
557.. code-block:: yaml
558
559 proxy:
560 proxytype: napalm
561 driver: junos
562 host: vsrx01.mydomain.local
563 username: root
564 passwd: r00tme
565 optional_args:
566 config_format: set
567
568.. note:: This is pillar of the node thats not able to run salt-minion itself
569
Ales Komarek8fb1da82016-08-21 23:52:03 +0200570
571Salt SSH
Ales Komarekd768f1c2018-01-30 22:37:18 +0100572~~~~~~~~
Ales Komarek8fb1da82016-08-21 23:52:03 +0200573
574Salt SSH with sudoer using key
575
576.. literalinclude:: tests/pillar/master_ssh_minion_key.sls
577 :language: yaml
578
579Salt SSH with sudoer using password
580
581.. literalinclude:: tests/pillar/master_ssh_minion_password.sls
582 :language: yaml
583
584Salt SSH with root using password
585
586.. literalinclude:: tests/pillar/master_ssh_minion_root.sls
587 :language: yaml
588
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100589Salt control (cloud/kvm/docker)
590-------------------------------
Filip Pytlounb4b80592015-10-06 16:28:32 +0200591
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100592Salt cloud with local OpenStack provider
Filip Pytlounb4b80592015-10-06 16:28:32 +0200593
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100594.. literalinclude:: tests/pillar/control_cloud_openstack.sls
595 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +0200596
597Salt cloud with Digital Ocean provider
598
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100599.. literalinclude:: tests/pillar/control_cloud_digitalocean.sls
600 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +0200601
Ales Komarek8fb1da82016-08-21 23:52:03 +0200602Salt virt with KVM cluster
Filip Pytlounb4b80592015-10-06 16:28:32 +0200603
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100604.. literalinclude:: tests/pillar/control_virt.sls
605 :language: yaml
Filip Pytlounb4b80592015-10-06 16:28:32 +0200606
Mateusz Los4c7cd2d2018-01-09 11:46:07 +0100607salt virt with custom destination for image file
608
609.. literalinclude:: tests/pillar/control_virt_custom.sls
610 :language: yaml
611
Filip Pytlounb4b80592015-10-06 16:28:32 +0200612
613Usage
614=====
615
616Working with salt-cloud
617
618.. code-block:: bash
619
620 salt-cloud -m /path/to/map --assume-yes
621
622Debug LIBCLOUD for salt-cloud connection
623
624.. code-block:: bash
625
626 export LIBCLOUD_DEBUG=/dev/stderr; salt-cloud --list-sizes provider_name --log-level all
627
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100628
Ales Komarekd768f1c2018-01-30 22:37:18 +0100629References
630==========
Filip Pytlounb4b80592015-10-06 16:28:32 +0200631
632* http://salt.readthedocs.org/en/latest/
633* https://github.com/DanielBryan/salt-state-graph
634* http://karlgrz.com/testing-salt-states-rapidly-with-docker/
635* https://mywushublog.com/2013/03/configuration-management-with-salt-stack/
636* http://russell.ballestrini.net/replace-the-nagios-scheduler-and-nrpe-with-salt-stack/
637* https://github.com/saltstack-formulas/salt-formula
638* http://docs.saltstack.com/en/latest/topics/tutorials/multimaster.html
639
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100640
Filip Pytlounb4b80592015-10-06 16:28:32 +0200641salt-cloud
642----------
643
644* http://www.blog.sandro-mathys.ch/2013/07/setting-user-password-when-launching.html
645* http://cloudinit.readthedocs.org/en/latest/topics/examples.html
646* http://salt-cloud.readthedocs.org/en/latest/topics/install/index.html
647* http://docs.saltstack.com/topics/cloud/digitalocean.html
648* http://salt-cloud.readthedocs.org/en/latest/topics/rackspace.html
649* http://salt-cloud.readthedocs.org/en/latest/topics/map.html
650* http://docs.saltstack.com/en/latest/topics/tutorials/multimaster.html
Ales Komarek8ba9c0b2016-02-21 14:59:59 +0100651
Filip Pytloun954dbd62017-02-02 13:02:03 +0100652
653Documentation and Bugs
654======================
655
656To learn how to install and update salt-formulas, consult the documentation
657available online at:
658
659 http://salt-formulas.readthedocs.io/
660
661In the unfortunate event that bugs are discovered, they should be reported to
662the appropriate issue tracker. Use Github issue tracker for specific salt
663formula:
664
665 https://github.com/salt-formulas/salt-formula-salt/issues
666
667For feature requests, bug reports or blueprints affecting entire ecosystem,
668use Launchpad salt-formulas project:
669
670 https://launchpad.net/salt-formulas
671
672You can also join salt-formulas-users team and subscribe to mailing list:
673
674 https://launchpad.net/~salt-formulas-users
675
676Developers wishing to work on the salt-formulas projects should always base
677their work on master branch and submit pull request against specific formula.
678
679 https://github.com/salt-formulas/salt-formula-salt
680
681Any questions or feedback is always welcome so feel free to join our IRC
682channel:
683
684 #salt-formulas @ irc.freenode.net