New Saltstack Salt formula
選択できるのは25トピックまでです。 トピックは、先頭が英数字で、英数字とダッシュ('-')を使用した35文字以内のものにしてください。

README.rst 15KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649
  1. ============
  2. Salt Formula
  3. ============
  4. Salt is a new approach to infrastructure management. Easy enough to get
  5. running in minutes, scalable enough to manage tens of thousands of servers,
  6. and fast enough to communicate with them in seconds.
  7. Salt delivers a dynamic communication bus for infrastructures that can be used
  8. for orchestration, remote execution, configuration management and much more.
  9. Sample Metadata
  10. ===============
  11. Salt master
  12. -----------
  13. Salt master with base formulas and pillar metadata backend
  14. .. literalinclude:: tests/pillar/master_single_pillar.sls
  15. :language: yaml
  16. Salt master with reclass ENC metadata backend
  17. .. literalinclude:: tests/pillar/master_single_reclass.sls
  18. :language: yaml
  19. Salt master with multiple ext_pillars
  20. .. literalinclude:: tests/pillar/master_single_extpillars.sls
  21. :language: yaml
  22. Salt master with API
  23. .. literalinclude:: tests/pillar/master_api.sls
  24. :language: yaml
  25. Salt master with defined user ACLs
  26. .. literalinclude:: tests/pillar/master_acl.sls
  27. :language: yaml
  28. Salt master with preset minions
  29. .. code-block:: yaml
  30. salt:
  31. master:
  32. enabled: true
  33. minions:
  34. - name: 'node1.system.location.domain.com'
  35. Salt master with pip based installation (optional)
  36. .. code-block:: yaml
  37. salt:
  38. master:
  39. enabled: true
  40. ...
  41. source:
  42. engine: pip
  43. version: 2016.3.0rc2
  44. Install formula through system package management
  45. .. code-block:: yaml
  46. salt:
  47. master:
  48. enabled: true
  49. ...
  50. environment:
  51. prd:
  52. keystone:
  53. source: pkg
  54. name: salt-formula-keystone
  55. nova:
  56. source: pkg
  57. name: salt-formula-keystone
  58. version: 0.1+0~20160818133412.24~1.gbp6e1ebb
  59. postresql:
  60. source: pkg
  61. name: salt-formula-postgresql
  62. version: purged
  63. Formula keystone is installed latest version and the formulas without version are installed in one call to aptpkg module.
  64. If the version attribute is present sls iterates over formulas and take action to install specific version or remove it.
  65. The version attribute may have these values ``[latest|purged|removed|<VERSION>]``.
  66. Clone master branch of keystone formula as local feature branch
  67. .. code-block:: yaml
  68. salt:
  69. master:
  70. enabled: true
  71. ...
  72. environment:
  73. dev:
  74. formula:
  75. keystone:
  76. source: git
  77. address: git@github.com:openstack/salt-formula-keystone.git
  78. revision: master
  79. branch: feature
  80. Salt master with specified formula refs (for example for Gerrit review)
  81. .. code-block:: yaml
  82. salt:
  83. master:
  84. enabled: true
  85. ...
  86. environment:
  87. dev:
  88. formula:
  89. keystone:
  90. source: git
  91. address: https://git.openstack.org/openstack/salt-formula-keystone
  92. revision: refs/changes/56/123456/1
  93. Salt master with logging handlers
  94. .. code-block:: yaml
  95. salt:
  96. master:
  97. enabled: true
  98. handler:
  99. handler01:
  100. engine: udp
  101. bind:
  102. host: 127.0.0.1
  103. port: 9999
  104. minion:
  105. handler:
  106. handler01:
  107. engine: udp
  108. bind:
  109. host: 127.0.0.1
  110. port: 9999
  111. handler02:
  112. engine: zmq
  113. bind:
  114. host: 127.0.0.1
  115. port: 9999
  116. Salt engine definition for saltgraph metadata collector
  117. .. code-block:: yaml
  118. salt:
  119. master:
  120. engine:
  121. graph_metadata:
  122. engine: saltgraph
  123. host: 127.0.0.1
  124. port: 5432
  125. user: salt
  126. password: salt
  127. database: salt
  128. Salt engine definition for sending events from docker events
  129. .. code-block:: yaml
  130. salt:
  131. master:
  132. engine:
  133. docker_events:
  134. docker_url: unix://var/run/docker.sock
  135. Salt master peer setup for remote certificate signing
  136. .. code-block:: yaml
  137. salt:
  138. master:
  139. peer:
  140. ".*":
  141. - x509.sign_remote_certificate
  142. Salt master backup configuration
  143. .. code-block:: yaml
  144. salt:
  145. master:
  146. backup: true
  147. initial_data:
  148. engine: backupninja
  149. source: backup-node-host
  150. host: original-salt-master-id
  151. Configure verbosity of state output (used for `salt` command)
  152. .. code-block:: yaml
  153. salt:
  154. master:
  155. state_output: changes
  156. Salt synchronise node pillar and modules after start
  157. .. code-block:: yaml
  158. salt:
  159. master:
  160. reactor:
  161. salt/minion/*/start:
  162. - salt://salt/reactor/node_start.sls
  163. Trigger basic node install
  164. .. code-block:: yaml
  165. salt:
  166. master:
  167. reactor:
  168. salt/minion/install:
  169. - salt://salt/reactor/node_install.sls
  170. Sample event to trigger the node installation
  171. .. code-block:: bash
  172. salt-call event.send 'salt/minion/install'
  173. Run any defined orchestration pipeline
  174. .. code-block:: yaml
  175. salt:
  176. master:
  177. reactor:
  178. salt/orchestrate/start:
  179. - salt://salt/reactor/orchestrate_start.sls
  180. Event to trigger the orchestration pipeline
  181. .. code-block:: bash
  182. salt-call event.send 'salt/orchestrate/start' "{'orchestrate': 'salt/orchestrate/infra_install.sls'}"
  183. Synchronise modules and pillars on minion start.
  184. .. code-block:: yaml
  185. salt:
  186. master:
  187. reactor:
  188. 'salt/minion/*/start':
  189. - salt://salt/reactor/minion_start.sls
  190. Add and/or remove the minion key
  191. .. code-block:: yaml
  192. salt:
  193. master:
  194. reactor:
  195. salt/key/create:
  196. - salt://salt/reactor/key_create.sls
  197. salt/key/remove:
  198. - salt://salt/reactor/key_remove.sls
  199. Event to trigger the key creation
  200. .. code-block:: bash
  201. salt-call event.send 'salt/key/create' \
  202. > "{'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'}}"
  203. .. note::
  204. You can add pass additional `orch_pre_create`, `orch_post_create`,
  205. `orch_pre_remove` or `orch_post_remove` parameters to the event to call
  206. extra orchestrate files. This can be useful for example for
  207. registering/unregistering nodes from the monitoring alarms or dashboards.
  208. The key creation event needs to be run from other machine than the one
  209. being registered.
  210. Event to trigger the key removal
  211. .. code-block:: bash
  212. salt-call event.send 'salt/key/remove'
  213. Encrypted pillars
  214. -----------------
  215. Note: NACL + below configuration will be available in Salt > 2017.7.
  216. External resources:
  217. - Tutorial to configure salt + reclass ext_pillar and nacl: http://apealive.net/post/2017-09-salt-nacl-ext-pillar/
  218. - Saltstack documentation: https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.nacl.html
  219. Configure salt NACL module:
  220. .. code-block:: shell
  221. pip install --upgrade libnacl===1.5.2
  222. salt-call --local nacl.keygen /etc/salt/pki/master/nacl
  223. local:
  224. saved sk_file:/etc/salt/pki/master/nacl pk_file: /etc/salt/pki/master/nacl.pub
  225. .. code-block:: yaml
  226. salt:
  227. master:
  228. pillar:
  229. reclass: *reclass
  230. nacl:
  231. index: 99
  232. nacl:
  233. box_type: sealedbox
  234. sk_file: /etc/salt/pki/master/nacl
  235. pk_file: /etc/salt/pki/master/nacl.pub
  236. #sk: None
  237. #pk: None
  238. NACL encrypt secrets:
  239. salt-call --local nacl.enc 'my_secret_value' pk_file=/etc/salt/pki/master/nacl.pub
  240. hXTkJpC1hcKMS7yZVGESutWrkvzusXfETXkacSklIxYjfWDlMJmR37MlmthdIgjXpg4f2AlBKb8tc9Woma7q
  241. # or
  242. salt-run nacl.enc 'myotherpass'
  243. ADDFD0Rav6p6+63sojl7Htfrncp5rrDVyeE4BSPO7ipq8fZuLDIVAzQLf4PCbDqi+Fau5KD3/J/E+Pw=
  244. NACL encrypted values on pillar:
  245. Use Boxed syntax `NACL[CryptedValue=]` to encode value on pillar:
  246. .. code-block:: yaml
  247. my_pillar:
  248. my_nacl:
  249. key0: unencrypted_value
  250. key1: NACL[hXTkJpC1hcKMS7yZVGESutWrkvzusXfETXkacSklIxYjfWDlMJmR37MlmthdIgjXpg4f2AlBKb8tc9Woma7q]
  251. NACL large files:
  252. .. code-block:: shell
  253. salt-call nacl.enc_file /tmp/cert.crt out=/srv/salt/env/dev/cert.nacl
  254. # or more advanced
  255. cert=$(cat /tmp/cert.crt)
  256. salt-call --out=newline_values_only nacl.enc_pub data="$cert" > /srv/salt/env/dev/cert.nacl
  257. NACL within template/native pillars:
  258. pillarexample:
  259. user: root
  260. password1: {{salt.nacl.dec('DRB7Q6/X5gGSRCTpZyxS6hlbWj0llUA+uaVyvou3vJ4=')|json}}
  261. cert_key: {{salt.nacl.dec_file('/srv/salt/env/dev/certs/example.com/cert.nacl')|json}}
  262. cert_key2: {{salt.nacl.dec_file('salt:///certs/example.com/cert2.nacl')|json}}
  263. Salt syndic
  264. -----------
  265. The master of masters
  266. .. code-block:: yaml
  267. salt:
  268. master:
  269. enabled: true
  270. order_masters: True
  271. Lower syndicated master
  272. .. code-block:: yaml
  273. salt:
  274. syndic:
  275. enabled: true
  276. master:
  277. host: master-of-master-host
  278. timeout: 5
  279. Syndicated master with multiple master of masters
  280. .. code-block:: yaml
  281. salt:
  282. syndic:
  283. enabled: true
  284. masters:
  285. - host: master-of-master-host1
  286. - host: master-of-master-host2
  287. timeout: 5
  288. Salt-minion proxy
  289. -----------------
  290. Salt proxy pillar
  291. .. code-block:: yaml
  292. salt:
  293. minion:
  294. proxy_minion:
  295. master: localhost
  296. device:
  297. vsrx01.mydomain.local:
  298. enabled: true
  299. engine: napalm
  300. csr1000v.mydomain.local:
  301. enabled: true
  302. engine: napalm
  303. .. note:: This is pillar of the the real salt-minion
  304. Proxy pillar for IOS device
  305. .. code-block:: yaml
  306. proxy:
  307. proxytype: napalm
  308. driver: ios
  309. host: csr1000v.mydomain.local
  310. username: root
  311. passwd: r00tme
  312. .. note:: This is pillar of the node thats not able to run salt-minion itself
  313. Proxy pillar for JunOS device
  314. .. code-block:: yaml
  315. proxy:
  316. proxytype: napalm
  317. driver: junos
  318. host: vsrx01.mydomain.local
  319. username: root
  320. passwd: r00tme
  321. optional_args:
  322. config_format: set
  323. .. note:: This is pillar of the node thats not able to run salt-minion itself
  324. Salt SSH
  325. --------
  326. Salt SSH with sudoer using key
  327. .. literalinclude:: tests/pillar/master_ssh_minion_key.sls
  328. :language: yaml
  329. Salt SSH with sudoer using password
  330. .. literalinclude:: tests/pillar/master_ssh_minion_password.sls
  331. :language: yaml
  332. Salt SSH with root using password
  333. .. literalinclude:: tests/pillar/master_ssh_minion_root.sls
  334. :language: yaml
  335. Common salt config options
  336. --------------------------
  337. Pass pillar render error to minion log.
  338. .. Note: When set to `False` this option is great for debuging. However it is not recomended for
  339. any production environment as it may contain templating data as passwords, etc...,
  340. that minion should not have.
  341. .. code-block:: yaml
  342. salt:
  343. master:
  344. pillar_safe_render_error: False
  345. Salt minion
  346. -----------
  347. Simplest Salt minion setup with central configuration node
  348. .. code-block:: yaml
  349. .. literalinclude:: tests/pillar/minion_master.sls
  350. :language: yaml
  351. Multi-master Salt minion setup
  352. .. literalinclude:: tests/pillar/minion_multi_master.sls
  353. :language: yaml
  354. Salt minion with salt mine options
  355. .. literalinclude:: tests/pillar/minion_mine.sls
  356. :language: yaml
  357. Salt minion with graphing dependencies
  358. .. literalinclude:: tests/pillar/minion_graph.sls
  359. :language: yaml
  360. Salt minion behind HTTP proxy
  361. .. code-block:: yaml
  362. salt:
  363. minion:
  364. proxy:
  365. host: 127.0.0.1
  366. port: 3128
  367. Salt minion to specify non-default HTTP backend. The default tornado backend
  368. does not respect HTTP proxy settings set as environment variables. This is
  369. useful for cases where you need to set no_proxy lists.
  370. .. code-block:: yaml
  371. salt:
  372. minion:
  373. backend: urllib2
  374. Salt minion with PKI certificate authority (CA)
  375. .. literalinclude:: tests/pillar/minion_pki_ca.sls
  376. :language: yaml
  377. Salt minion using PKI certificate
  378. .. literalinclude:: tests/pillar/minion_pki_cert.sls
  379. :language: yaml
  380. Salt minion trust CA certificates issued by salt CA on a specific host (ie: salt-master node)
  381. .. code-block:: yaml
  382. salt:
  383. minion:
  384. trusted_ca_minions:
  385. - cfg01
  386. Salt control (cloud/kvm/docker)
  387. -------------------------------
  388. Salt cloud with local OpenStack provider
  389. .. literalinclude:: tests/pillar/control_cloud_openstack.sls
  390. :language: yaml
  391. Salt cloud with Digital Ocean provider
  392. .. literalinclude:: tests/pillar/control_cloud_digitalocean.sls
  393. :language: yaml
  394. Salt virt with KVM cluster
  395. .. literalinclude:: tests/pillar/control_virt.sls
  396. :language: yaml
  397. Usage
  398. =====
  399. Working with salt-cloud
  400. .. code-block:: bash
  401. salt-cloud -m /path/to/map --assume-yes
  402. Debug LIBCLOUD for salt-cloud connection
  403. .. code-block:: bash
  404. export LIBCLOUD_DEBUG=/dev/stderr; salt-cloud --list-sizes provider_name --log-level all
  405. More Information
  406. ================
  407. * http://salt.readthedocs.org/en/latest/
  408. * https://github.com/DanielBryan/salt-state-graph
  409. * http://karlgrz.com/testing-salt-states-rapidly-with-docker/
  410. * https://mywushublog.com/2013/03/configuration-management-with-salt-stack/
  411. * http://russell.ballestrini.net/replace-the-nagios-scheduler-and-nrpe-with-salt-stack/
  412. * https://github.com/saltstack-formulas/salt-formula
  413. * http://docs.saltstack.com/en/latest/topics/tutorials/multimaster.html
  414. salt-cloud
  415. ----------
  416. * http://www.blog.sandro-mathys.ch/2013/07/setting-user-password-when-launching.html
  417. * http://cloudinit.readthedocs.org/en/latest/topics/examples.html
  418. * http://salt-cloud.readthedocs.org/en/latest/topics/install/index.html
  419. * http://docs.saltstack.com/topics/cloud/digitalocean.html
  420. * http://salt-cloud.readthedocs.org/en/latest/topics/rackspace.html
  421. * http://salt-cloud.readthedocs.org/en/latest/topics/map.html
  422. * http://docs.saltstack.com/en/latest/topics/tutorials/multimaster.html
  423. Documentation and Bugs
  424. ======================
  425. To learn how to install and update salt-formulas, consult the documentation
  426. available online at:
  427. http://salt-formulas.readthedocs.io/
  428. In the unfortunate event that bugs are discovered, they should be reported to
  429. the appropriate issue tracker. Use Github issue tracker for specific salt
  430. formula:
  431. https://github.com/salt-formulas/salt-formula-salt/issues
  432. For feature requests, bug reports or blueprints affecting entire ecosystem,
  433. use Launchpad salt-formulas project:
  434. https://launchpad.net/salt-formulas
  435. You can also join salt-formulas-users team and subscribe to mailing list:
  436. https://launchpad.net/~salt-formulas-users
  437. Developers wishing to work on the salt-formulas projects should always base
  438. their work on master branch and submit pull request against specific formula.
  439. https://github.com/salt-formulas/salt-formula-salt
  440. Any questions or feedback is always welcome so feel free to join our IRC
  441. channel:
  442. #salt-formulas @ irc.freenode.net