docs/README.rst

   1 .. _readme:
   2
   3 arvados-formula
   4 ================
   5
   6 |img_travis| |img_sr|
   7
   8 .. |img_travis| image:: https://travis-ci.com/saltstack-formulas/arvados-formula.svg?branch=master
   9    :alt: Travis CI Build Status
  10    :scale: 100%
  11    :target: https://travis-ci.com/saltstack-formulas/arvados-formula
  12 .. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
  13    :alt: Semantic Release
  14    :scale: 100%
  15    :target: https://github.com/semantic-release/semantic-release
  16
  17 A SaltStack formula to install and configure an `Arvados cluster <https://arvados.org>`_.
  18
  19 .. contents:: **Table of Contents**
  20
  21 General notes
  22 -------------
  23
  24 See the full `SaltStack Formulas installation and usage instructions
  25 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
  26
  27 If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
  28 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
  29
  30 If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
  31 which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
  32
  33 See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
  34
  35 If you need (non-default) configuration, please pay attention to the ``pillar.example`` file and/or `Special notes`_ section.
  36
  37 Contributing to this repo
  38 -------------------------
  39
  40 **Commit message formatting is significant!!**
  41
  42 Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
  43
  44 Special notes
  45 -------------
  46
  47 In the `Arvados repository <https://github.com/arvados/arvados/>`_ you can find `a provision script <https://github.com/arvados/arvados/tree/master/tools/salt-install>`_
  48 to deploy a single-node, all-in-one Arvados cluster (The script uses this formula to get a cluster up and running in Saltstack's master-less mode).
  49
  50 The `single-node` install does not include SLURM: it is intended for an `all-in-one-host` installation,
  51 so it uses `crunch-dispatch-local` to run containers in the same instance.
  52
  53 The provision script can be run anywhere, so you can run it in an AWS instance and you'll get a `single-node` Arvados cluster there.
  54
  55 The Arvados formula allows you to `install any dispatcher available <https://github.com/saltstack-formulas/arvados-formula/blob/master/pillar.example#L182-L191>`_,
  56 provided you configure the pillars the way you need them.
  57
  58 Arvados currently has three dispatchers:
  59
  60 * **crunch-dispatch-local** (for single node installations),
  61 * **arvados-dispatch-cloud** (for dynamic compute on AWS or Azure) and
  62 * **crunch-dispatch-slurm** (for SLURM integration).
  63
  64 Requisites
  65 ----------
  66
  67 Arvados **requires** a Postgres database for its API server and SSL for communications. If you don't satisfy these two requirements, things
  68 won't work. It also uses an Nginx server as a redirector but probably almost any other webserver/redirector can be used instead.
  69
  70 We suggest you use the `postgres-formula <https://github.com/saltstack-formulas/postgres-formula/>`_,
  71 the `nginx-formula <https://github.com/saltstack-formulas/nginx-formula/>`_ and the
  72 `letsencrypt-formula <https://github.com/saltstack-formulas/letsencrypt-formula/>`_ to satisfy these dependencies.
  73 In the **test/salt/pillar/examples/** directory there are example pillar YAMLs to set up these packages, using the mentioned formulas
  74 as Arvados needs them.a
  75
  76 In the **test/salt/states/examples/** directory there are some example helper states to set up a few requirements for single-node
  77 (all-in-one) Arvados host.
  78
  79 Usage
  80 -----
  81
  82 As Arvados is a *suite* of tools that can be installed in different hosts and configured to interact, this formula is split in
  83 those components, which can be installed or removed independently of the other components. This means that you'll get flexibility
  84 to install your cluster as you prefer at the expense of having to take care on some steps:
  85
  86 The formula has the following components/submodules available:
  87
  88 * `api <https://doc.arvados.org/install/install-api-server.html>`_: installs the Arvados API server packages. Requires a running
  89   Postgres database and an Nginx+Passenger server.
  90 * `config <https://doc.arvados.org/v2.0/admin/config.html>`_: creates and deploys a valid Arvados config file. This state is automatically
  91   include in all the components that require it (at the moment, all but `shell`), so you will rarely need to invoke this state manually.
  92 * `controller <https://doc.arvados.org/v2.0/install/install-api-server.html>`_: installs the Arvados API controller.
  93 * `keepproxy <https://doc.arvados.org/v2.0/install/install-keepproxy.html>`_: installs and configures the Arvados Keepproxy gateway
  94   to the Keep storages.
  95 * `keepstore <https://doc.arvados.org/v2.0/install/install-keepstore.html>`_: installs and configures an Arvados Keep storages.
  96 * `keepweb <https://doc.arvados.org/v2.0/install/install-keep-web.html>`_: installs and configures the WebDAV access to the Keep storages.
  97 * `repo <https://doc.arvados.org/v2.0/install/packages.html>`_: configures the repositories to install arvados. It's enabled by default.
  98 * `shell <https://doc.arvados.org/v2.0/install/install-shell-server.html>`_: installs the user CLI apps to communicate with the cluster.
  99 * `websocket <https://doc.arvados.org/v2.0/install/install-ws.html>`_: installs the websocket notifcations gateway.
 100 * `workbench <https://doc.arvados.org/v2.0/install/install-workbench-app.html>`_: installs the webUI to communicate with the cluster.
 101 * `workbench2 <https://doc.arvados.org/v2.0/install/install-workbench2-app.html>`_: installs the next generation webUI for Arvados.
 102
 103 If you just use the `arvados` meta-state, it will install all the components in a single host.
 104
 105 Also, please note that the individual subcomponents' `clean` states **won't remove the config file**: as the config is common to all the suite
 106 components and they can be installed in the same host, removing it with a subcomponent might break others.
 107
 108 If you want to remove the config in a host where you're removing a subcomponent, use the `arvados.config.clean` state after the
 109 `arvados.<subcomponent>.clean` state.
 110
 111 Finally, the `arvados.clean` meta-state will remove everything, config included, and can be used in any host to remove all of arvados files.
 112
 113 Available states
 114 ----------------
 115
 116 For each of the components, there are *meta-states* named after the component that will include other states in the component subdir
 117 that perform the actual work.
 118
 119 For example, using *arvados.keepstore* will include, in order:
 120
 121 * arvados.keepstore.package.install
 122 * arvados.config.file
 123 * arvados.keepstore.service.running
 124
 125 while using *arvados.keepstore.clean* will include, in order:
 126
 127 * arvados.keepstore.service.clean
 128 * arvados.keepstore.package.clean
 129
 130 Or you can use individual states, like
 131
 132 * arvados.keepstore.package.install
 133 * arvados.keepstore.service.clean
 134
 135 to get the *keepstore* package installed with the service stopped.
 136
 137 The generic description for the states is
 138
 139 .. contents::
 140    :local:
 141
 142 ``arvados``
 143 ^^^^^^^^^^^^
 144
 145 *Meta-state (This is a state that includes other states)*.
 146
 147 This installs the *WHOLE* arvados suite in a single host,
 148 manages the arvados configuration file and then
 149 starts the associated arvados services.
 150
 151 ``arvados.clean``
 152 ^^^^^^^^^^^^^^^^^
 153
 154 *Meta-state (This is a state that includes other states)*.
 155
 156 This state will undo everything performed in the ``arvados`` meta-state in reverse order, i.e.
 157 stops the services, removes the configuration file and then uninstalls the packages.
 158
 159
 160 ``arvados.config``
 161 ^^^^^^^^^^^^^^^^^^
 162
 163 This state will configure the arvados cluster. As all the arvados components use the same config
 164 file, any of the following components will include this state and you will rarely need to call it
 165 independently. You can still do, ie, to get a parsed config file to use somewhere else.
 166
 167 ``arvados.config.clean``
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 This state will remove the configuration of the arvados node.
 171
 172 ``arvados.repo``
 173 ^^^^^^^^^^^^^^^^
 174
 175 This state will configure the arvados repository.
 176
 177 ``arvados.repo.clean``
 178 ^^^^^^^^^^^^^^^^^^^^^^
 179
 180 This state will remove the arvados repository configuration.
 181
 182
 183 ``arvados.<component>``
 184 ^^^^^^^^^^^^^^^^^^^^^^^
 185
 186 *Meta-state (This is a state that includes other states)*.
 187
 188 This state will install the package, configure the component (if applicable) and start the service (if applicable).
 189
 190 ``arvados.<component>.clean``
 191 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 192
 193 *Meta-state (This is a state that includes other states)*.
 194
 195 This state will undo everything performed in the ``arvados.<component>`` meta-state in reverse order, i.e.
 196 stop the service and uninstall the package/s.
 197
 198 ``arvados.<component>.package``
 199 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 200
 201 This state will install the arvados <component> package/s only.
 202
 203 ``arvados.<component>.package.clean``
 204 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 205
 206 This state will remove the packages of the arvados <component> node and has a depency on
 207 ``arvados.<component>.service.clean`` via include list (if applicable).
 208
 209 ``arvados.<component>.service``
 210 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 211
 212 This state will start the arvados service and has a dependency on ``arvados.config``
 213 via include list.
 214
 215 ``arvados.<component>.service.clean``
 216 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 217
 218 This state will stop the arvados service and disable it at boot time.
 219
 220
 221 Testing
 222 -------
 223
 224 Linux testing is done with ``kitchen-salt``.
 225
 226 Requirements
 227 ^^^^^^^^^^^^
 228
 229 * Ruby
 230 * Docker
 231
 232 .. code-block:: bash
 233
 234    $ gem install bundler
 235    $ bundle install
 236    $ bin/kitchen test [platform]
 237
 238 Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
 239 e.g. ``debian-10-3000-1-py3``.
 240
 241 ``bin/kitchen converge``
 242 ^^^^^^^^^^^^^^^^^^^^^^^^
 243
 244 Creates the docker instance and runs the ``arvados`` main state, ready for testing.
 245
 246 ``bin/kitchen verify``
 247 ^^^^^^^^^^^^^^^^^^^^^^
 248
 249 Runs the ``inspec`` tests on the actual instance.
 250
 251 ``bin/kitchen destroy``
 252 ^^^^^^^^^^^^^^^^^^^^^^^
 253
 254 Removes the docker instance.
 255
 256 ``bin/kitchen test``
 257 ^^^^^^^^^^^^^^^^^^^^
 258
 259 Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
 260
 261 ``bin/kitchen login``
 262 ^^^^^^^^^^^^^^^^^^^^^
 263
 264 Gives you SSH access to the instance for manual testing.
 265