posts/Salt_Stack.mdwn

   1 [Salt][] is a remote execution and automated deployment system.  It's
   2 great for running your own clusters once your website outgrows a
   3 single box.  If you get bored of running your own boxes, you can use
   4 [salt-cloud][] to provision minions on someone else's cloud (Amazon
   5 EC2, Linode, …).  You can install Salt on [[Gentoo]] with:
   6
   7     # USE=git emerge -av app-admin/salt
   8
   9 [Usually][syndic] you'll have one master, and a host of minions
  10 running salt daemons that locally execute commands sent from the
  11 master.  After setting up [[BIND]] so `salt` (the [default master
  12 name][master-name]) resolves to your development box, you should be
  13 able to run:
  14
  15     # rc-service salt-master start
  16     # rc-service salt-minion restart
  17     # salt-key -L
  18     Accepted Keys:
  19     Unaccepted Keys:
  20     devbox.example.net
  21     Rejected Keys:
  22     # salt-key -A
  23     The following keys are going to be accepted:
  24     Unaccepted Keys:
  25     devbox.example.net
  26     Proceed? [n/Y] y
  27     Key for minion devbox.example.net accepted.
  28
  29 If you were not confined to the local box, it would be wise to compare
  30 the proposed key:
  31
  32     # salt-key -p devbox.example.net
  33
  34 with that on the minon itself:
  35
  36     # cat /etc/salt/pki/minion/minion.pub
  37
  38 before accepting the key.
  39
  40 Once you have accepted the minon, ping it:
  41
  42     # salt '*' test.ping
  43     devbox.example.net:
  44         True
  45
  46 Then you can browse through all of the [available goodies][api]:
  47
  48     # salt '*' sys.doc
  49
  50 Once you've had some fun reading about those, it's time to [configure
  51 your state tree][state].  For a quick intro, we can just borrow the
  52 [salt-state example repository][salt-states].  The salt state data is
  53 conventionally kept in `/srv/salt`, which seemed odd to me, but does
  54 indeed follow the [FHS][FHS-srv].
  55
  56     # mkdir /srv/
  57     $ git clone git://github.com/saltstack/salt-states.git
  58     # mv salt-states /srv/salt
  59
  60 This leaves `/srv/salt` owned by my personal user (instead of root),
  61 because as much as I love [[Git]], I'm not going to run it as root.
  62
  63 Once you've got a state tree in `/srv/salt`, you can mock-install the
  64 configured state for each node.  It's always a good idea to [test your
  65 commands][testing] before you run them, to make sure they won't do
  66 something wonky.
  67
  68     # salt '*' state.highstate test=True
  69     devbox.example.net:
  70     ----------
  71         State: - file
  72         Name:      /etc/hosts
  73         Function:  comment
  74             Result:    None
  75             Comment:   File /etc/hosts is set to be updated
  76             Changes:
  77     ----------
  78         State: - file
  79         Name:      /etc/hosts
  80         Function:  uncomment
  81             Result:    True
  82             Comment:   Pattern already uncommented
  83             Changes:
  84     ----------
  85         State: - cmd
  86         Name:      date > /tmp/date
  87         Function:  run
  88             Result:    None
  89             Comment:   Command "date > /tmp/date" would have been executed
  90             Changes:
  91     ----------
  92     …
  93
  94 You can also install a particular sub-state on a particular minon
  95 (again, I'm showing the testing version):
  96
  97     # salt 'devbox.example.net' state.sls python,ssh.server test=True
  98     devbox.example.net:
  99     ----------
 100         State: - pkg
 101         Name:      openssh
 102         Function:  installed
 103             Result:    False
 104             Comment:   Package category missing for "openssh" (possible matches: net-misc/openssh).
 105             Changes:
 106     ----------
 107         State: - pkg
 108         Name:      python-mako
 109         Function:  installed
 110             Result:    False
 111             Comment:   Package category missing for "python-mako" and no match found in portage tree.
 112             Changes:
 113
 114     ----------
 115     …
 116
 117 The comments (Package category missing for…) mean that the
 118 [salt-states][] repository hasn't been updated to [recent][3008]
 119 [versions][3009] [of][3019] Salt (0.12+), which [require fully
 120 qualified package names][ebuild-cat].
 121
 122 You can also install a particular [ID declaration][id] on a particular
 123 minon (again, I'm showing the testing version):
 124
 125     # salt 'devbox.example.net' state.sls python,ssh.server test=True
 126
 127 For single-box testing, you can also skip the master node, running
 128 commands on a [masterless minion][masterless] by using `salt-call
 129 --local` instead of `salt '<target>'` in your Salt invocations:
 130
 131     # salt-call --local state.highstate test=True
 132     local:
 133     ----------
 134         State: - file
 135         Name:      /etc/hosts
 136         Function:  comment
 137             Result:    None
 138             Comment:   File /etc/hosts is set to be updated
 139             Changes:
 140     ----------
 141     …
 142
 143 Because you don't have a master passing you state, `--local` calls
 144 require you to have the state stored on your local box (in `/srv/salt`
 145 by default).  It's hard to imagine using Salt without storing state
 146 anywhere ;).
 147
 148 It's also possible to [run Salt as a non-root user][nonroot], but I
 149 haven't looked into that yet.
 150
 151 [Salt]: http://saltstack.com/community.html
 152 [salt-cloud]: https://github.com/saltstack/salt-cloud
 153 [syndic]: http://docs.saltstack.com/ref/syndic.html
 154 [master-name]: http://docs.saltstack.com/ref/configuration/minion.html#master
 155 [api]: http://docs.saltstack.com/ref/modules/all/
 156 [state]: http://docs.saltstack.com/topics/tutorials/starting_states.html
 157 [salt-states]: https://github.com/saltstack/salt-states
 158 [FHS-srv]: http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM
 159 [testing]: http://docs.saltstack.com/ref/states/testing.html
 160 [3008]: https://github.com/saltstack/salt/pull/3008
 161 [3009]: https://github.com/saltstack/salt/pull/3009
 162 [3019]: https://github.com/saltstack/salt/pull/3019
 163 [ebuild-cat]: http://docs.saltstack.com/ref/modules/all/salt.modules.ebuild.html
 164 [id]: http://docs.saltstack.com/ref/states/highstate.html#id-declaration
 165 [masterless]: http://docs.saltstack.com/topics/tutorials/quickstart.html
 166 [nonroot]: https://salt.readthedocs.org/en/v0.17.0/topics/nonroot.html
 167
 168 [[!tag tags/linux]]
 169 [[!tag tags/tools]]