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