docs/README.rst

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