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