arvados-formula
A SaltStack formula to install and configure an Arvados cluster.
1. General notes
See the full SaltStack Formulas installation and usage instructions.
If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.
If you want to use this formula, please pay attention to the FORMULA
file and/or git tag, which contains the currently released version.
This formula is versioned according to Semantic
Versioning.
See Formula Versioning Section for more details.
If you need (non-default) configuration, please pay attention to the
pillar.example file and/or Special notes section.
2. Contributing to this repo
Commit message formatting is significant!!
Please see How to contribute for more details.
3. Special notes
In the Arvados repository you can find a provision script 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).
The single-node install does not include SLURM: it is intended for an all-in-one-host installation, so it uses crunch-dispatch-local to run containers in the same instance.
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.
The Arvados formula allows you to install any dispatcher available, provided you configure the pillars the way you need them.
Arvados currently has three dispatchers:
-
crunch-dispatch-local (for single node installations),
-
arvados-dispatch-cloud (for dynamic compute on AWS or Azure) and
-
crunch-dispatch-slurm (for SLURM integration).
4. Requisites
Arvados requires a Postgres database for its API server and SSL for communications. If you don’t satisfy these two requirements, things won’t work. It also uses an Nginx server as a redirector but probably almost any other webserver/redirector can be used instead.
We suggest you use the postgres-formula, the nginx-formula and the letsencrypt-formula to satisfy these dependencies. In the test/salt/pillar/examples/ directory there are example pillar YAMLs to set up these packages, using the mentioned formulas as Arvados needs them.a
In the test/salt/states/examples/ directory there are some example helper states to set up a few requirements for single-node (all-in-one) Arvados host.
5. Usage
As Arvados is a suite of tools that can be installed in different hosts and configured to interact, this formula is split in those components, which can be installed or removed independently of the other components. This means that you’ll get flexibility to install your cluster as you prefer at the expense of having to take care on some steps:
The formula has the following components/submodules available:
-
api: installs the Arvados API server packages. Requires a running Postgres database and an Nginx+Passenger server.
-
config: creates and deploys a valid Arvados config file. This state is automatically include in all the components that require it (at the moment, all but shell), so you will rarely need to invoke this state manually.
-
controller: installs the Arvados API controller.
-
keepproxy: installs and configures the Arvados Keepproxy gateway to the Keep storages.
-
keepstore: installs and configures an Arvados Keep storages.
-
keepweb: installs and configures the WebDAV access to the Keep storages.
-
repo: configures the repositories to install arvados. It’s enabled by default.
-
shell: installs the user CLI apps to communicate with the cluster.
-
websocket: installs the websocket notifcations gateway.
-
workbench: installs the webUI to communicate with the cluster.
-
workbench2: installs the next generation webUI for Arvados.
If you just use the arvados meta-state, it will install all the components in a single host.
Also, please note that the individual subcomponents' clean states won’t remove the config file: as the config is common to all the suite components and they can be installed in the same host, removing it with a subcomponent might break others.
If you want to remove the config in a host where you’re removing a subcomponent, use the arvados.config.clean state after the arvados.<subcomponent>.clean state.
Finally, the arvados.clean meta-state will remove everything, config included, and can be used in any host to remove all of arvados files.
6. Available states
For each of the components, there are meta-states named after the component that will include other states in the component subdir that perform the actual work.
For example, using arvados.keepstore will include, in order:
-
arvados.keepstore.package.install
-
arvados.config.file
-
arvados.keepstore.service.running
while using arvados.keepstore.clean will include, in order:
-
arvados.keepstore.service.clean
-
arvados.keepstore.package.clean
Or you can use individual states, like
-
arvados.keepstore.package.install
-
arvados.keepstore.service.clean
to get the keepstore package installed with the service stopped.
The generic description for the states is
6.1. arvados
Meta-state (This is a state that includes other states).
This installs the WHOLE arvados suite in a single host, manages the arvados configuration file and then starts the associated arvados services.
6.2. arvados.clean
Meta-state (This is a state that includes other states).
This state will undo everything performed in the arvados meta-state in
reverse order, i.e. stops the services, removes the configuration file
and then uninstalls the packages.
6.3. arvados.config
This state will configure the arvados cluster. As all the arvados components use the same config file, any of the following components will include this state and you will rarely need to call it independently. You can still do, ie, to get a parsed config file to use somewhere else.
6.7. arvados.<component>
Meta-state (This is a state that includes other states).
This state will install the package, configure the component (if applicable) and start the service (if applicable).
6.8. arvados.<component>.clean
Meta-state (This is a state that includes other states).
This state will undo everything performed in the arvados.<component>
meta-state in reverse order, i.e. stop the service and uninstall the
package/s.
6.10. arvados.<component>.package.clean
This state will remove the packages of the arvados <component> node and
has a depency on arvados.<component>.service.clean via include list
(if applicable).
7. Testing
Linux testing is done with kitchen-salt.
7.1. Requirements
-
Ruby
-
Docker
$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]Where [platform] is the platform name defined in kitchen.yml, e.g.
debian-10-3000-1-py3.
7.2. bin/kitchen converge
Creates the docker instance and runs the arvados main state, ready for
testing.