Starting stateboard instance (#97)

Author: dokshina

README.md

@@ -25,6 +25,7 @@ to learn how to set up topology using this role.
   * [Failover](#failover)
   * [Cartridge authorization](#cartridge-authorization)
   * [Application configuration](#application-configuration)
+  * [Stateboard instance](#stateboard-instance)
 
 
 ## Requirements
@@ -69,6 +70,7 @@ To deploy an application and set up this topology:
 ---
 all:
   vars:
+    cartridge_app_name: myapp
     cartridge_package_path: ./myapp-1.0.0-0.rpm
     cartridge_cluster_cookie: secret-cookie
     cartridge_defaults:
@@ -171,6 +173,8 @@ Configuration format is described in detail in the
 * `config` (`dict`, required): [instance configuration](#instances);
 * `restarted` (`boolean`, optional, default: `false`): indicates that instance must be forcedly restarted;
 * `expelled` (`boolean`, optional, default: `false`): boolean flag that indicates if instance must be expelled from topology;
+* `stateboard` (`boolean`, optional, default: `false`): boolean flag that indicates
+   that the instance is a [stateboard](#stateboard-instance);
 * `instance_start_timeout` (`number`, optional, default: 60): time in seconds to wait for instance to be started;
 * `replicaset_alias` (`string`, optional): replicaset alias, will be displayed in Web UI;
 * `failover_priority` (`list-of-string`): failover priority;
@@ -439,7 +443,7 @@ cartridge_failover_params:
 
 #### Stateful
 
-**Note** that stateful failover is supported since `Cartridge` 2.1.0.
+**Note** that stateful failover is supported since `Cartridge` 2.1.2.
 
 `stateful` failover requires these parameters:
 
@@ -559,3 +563,72 @@ section-1: value-1  # hasn't been changed
 section-2:
   key-21: value-21-new  # body was replaced
 ```
+
+### Stateboard instance
+
+Stateboard is a Tarantool state provider for stateful failover.
+It is delivered within an application's RPM/DEB package, if the application contains the
+`stateboard.init.lua` file in its root. In this case, the application package contains the
+`/etc/systemd/system/<appname>-stateboard.service` unit file.
+
+It starts a Tarantool stateboard instance with an entry point
+`/usr/share/tarantool/<appname>/stateboard.init.lua`.
+This instance looks for its configuration in the `<appname>-stateboard` section
+across all files in the `/etc/tarantool/conf.d` directory.
+
+This instance can be started using the [Tarantool Cartridge Ansible role](https://github.com/tarantool/ansible-cartridge).
+To mark an instance as a stateboard, use the `stateboard` flag.
+
+A stateboard instance is started as a systemd service named `<app_name>-stateboard`.
+
+Stateboard can be configured using the `config` variable as well as other instances.
+This variable describes stateboard parameters that would be passed to its
+configuration.
+
+**Note:** `cartridge_defaults` doesn't affect a stateboard instance.
+
+#### Required config parameters
+
+* `listen` - stateboard instance URI.
+  It must be specified in the `<host>:<port>` format.
+
+* `password` - stateboard instance password.
+
+#### Forbidden config parameters
+
+`alias`, `console_sock`, `pid_file`, and `workdir` parameters are forbidden
+for a stateboard instance.
+
+*Example*
+
+```yaml
+---
+all:
+  vars:
+    cartridge_app_name: myapp
+    cartridge_package_path: ./myapp-1.0.0-0.rpm
+
+    # other cartridge params
+    ...
+
+    # FAILOVER PARAMS
+    cartridge_failover_params:
+      mode: stateful
+      state_provider: stateboard
+      stateboard_params:
+        uri: 172.19.0.2:3310 # <- STATEBOARD URI
+        password: secret-stateboard # <- STATEBOARD PASSWORD
+
+  hosts:
+    # STATEBOARD INSTANCE
+    my-stateboard-instance:  # instance name doesn't matter
+      stateboard: true  # this matters - instance is a stateboard
+      config:
+        listen: '172.19.0.2:3310' # <- STATEBOARD URI
+        password: 'stateboard-secret' # <- STATEBOARD PASSWORD
+
+    # APPLICATION INSTANCES
+    core-1:
+      ...
+    ...
+```

defaults/main.yml

@@ -3,4 +3,5 @@ cartridge_defaults: {}
 cartridge_enable_tarantool_repo: true
 restarted: false
 expelled: false
+stateboard: false
 instance_start_timeout: 60

examples/getting-started-app/README.md

@@ -14,7 +14,7 @@ set up the topology, and configure a cluster.
   * [Start instances](#start-instances)
   * [Set up replica sets](#set-up-replica-sets)
   * [Bootstrap vshard](#bootstrap-vshard)
-  * [Manage failover](#manage-failover)
+  * [Failover](#failover)
   * [Manage authorization](#manage-authorization)
   * [Application configuration](#application-configuration)
 * [Final checks](#final-checks)
@@ -64,7 +64,9 @@ Our example application implements two roles:
 We will set up a simple topology on 2 virtual machines, `vm1` and `vm2`:
 
 * replicaset `app-1`:
-  * roles: `api` (+ `vshard-router`)
+  * roles:
+    * `api` (+ `vshard-router`)
+    * `failover-coordinator`
   * instances:
     * `app-1` (`vm1`)
 
@@ -393,7 +395,9 @@ all:
         replicaset_alias: app-1
         failover_priority:
           - app-1  # leader
-        roles: ['api']
+        roles:
+          - api
+          - failover-coordinator
 
       hosts:  # instances
         app-1:
@@ -472,6 +476,7 @@ To disable failover just set it's mode to `disabled`:
 ---
 all:
   vars:
+    ...
     cartridge_failover_params:
       mode: disabled
     ...
@@ -481,9 +486,70 @@ If this value is unset, the failover status won't be affected.
 
 ### Stateful failover
 
-The full example for [stateful failover](https://www.tarantool.io/en/doc/2.2/book/cartridge/cartridge_api/topics/failover.md#stateful-failover)
-is coming soon.
-Now you can [read the doc](../../README.md#stateful).
+**Note** that stateful failover is supported since `Cartridge` 2.1.2.
+
+[Read the doc](../../README.md#stateful) to learn more about stateful failover.
+
+First, let's set failover mode to stateful:
+
+```yaml
+---
+all:
+  vars:
+    ...
+    cartridge_failover_params:
+      mode: stateful
+      state_provider: stateboard
+      stateboard_params:
+        uri: 172.19.0.2:3310
+        password: secret-stateboard
+    ...
+```
+
+Now, check the `Failover` button in the Admin UI:
+
+![](./images/stateful-failover.png)
+
+Stateful failover was enabled, but we didn't start the Stateboard instance.
+If you click the `Issues` button, you can see that there are problems with
+state provider availability.
+
+![](./images/issues.png)
+
+Now we need to start [Stateboard instance](../../README.md#stateboard-instance).
+
+Add host marked as `stateboard` to the first machine:
+
+```yaml
+---
+all:
+  vars:
+  ...
+  hosts:
+    ...
+    my-stateboard:
+      config:
+        listen: 172.19.0.2:3310
+        password: secret-stateboard
+      stateboard: true
+  ...
+  children:
+    machine1:
+      vars:
+        ...
+      hosts:
+        ...
+        my-stateboard:
+```
+
+Check that there aren't any issues anymore.
+Additionally, you can check stateboard service status and logs:
+
+```bash
+vagrant ssh vm1
+[vagrant@vm1 ~]$ sudo systemctl status getting-started-app-stateboard
+[vagrant@vm1 ~]$ sudo journalctl -u getting-started-app-stateboard
+```
 
 ### Manage authorization
 

examples/getting-started-app/getting-started-app-1.0.0-0.rpm

@@ -8,6 +8,18 @@ all:
     cartridge_defaults:  # default instance parameters
       log_level: 5
 
+    cartridge_bootstrap_vshard: true  # bootstrap vshard
+
+    # cartridge_failover_params:
+    #   mode: eventual
+
+    # cartridge_failover_params:
+    #   mode: stateful
+    #   state_provider: stateboard
+    #   stateboard_params:
+    #     uri: 172.19.0.2:3310
+    #     password: secret-stateboard
+
     # common ssh options
     ansible_ssh_private_key_file: ~/.vagrant.d/insecure_private_key
     ansible_ssh_common_args: '-o IdentitiesOnly=yes -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no'
@@ -29,6 +41,12 @@ all:
         advertise_uri: '172.19.0.3:3302'
         http_port: 8183
 
+    # my-stateboard:
+    #   config:
+    #     listen: 172.19.0.2:3310
+    #     password: secret-stateboard
+    #   stateboard: true
+
   children:
     # GROUP INSTANCES BY MACHINES
     machine1:
@@ -39,6 +57,7 @@ all:
 
       hosts:  # instances to be started on this machine
         storage-1:
+        # my-stateboard:
 
     machine2:
       vars:
@@ -50,26 +69,28 @@ all:
         app-1:
         storage-1-replica:
 
-# GROUP INSTANCES BY REPLICASETS
-storage_1_replicaset:  # replicaset storage-1
-  vars:  # replicaset configuration
-    replicaset_alias: storage-1
-    weight: 3
-    failover_priority:
-      - storage-1  # leader
-      - storage-1-replica
-    roles: ['storage']
-
-  hosts:  # instances
-    storage-1:
-    storage-1-replica:
+    # GROUP INSTANCES BY REPLICASETS
+    storage_1_replicaset:  # replicaset storage-1
+      vars:  # replicaset configuration
+        replicaset_alias: storage-1
+        weight: 3
+        failover_priority:
+          - storage-1  # leader
+          - storage-1-replica
+        roles: ['storage']
 
-app_1_replicaset:  # replicaset app-1
-  vars:  # replicaset configuration
-    replicaset_alias: app-1
-    failover_priority:
-      - app-1  # leader
-    roles: ['api']
+      hosts:  # instances
+        storage-1:
+        storage-1-replica:
 
-  hosts:  # instances
-    app-1:
+    app_1_replicaset:  # replicaset app-1
+      vars:  # replicaset configuration
+        replicaset_alias: app-1
+        failover_priority:
+          - app-1  # leader
+        roles:
+          - api
+          - failover-coordinator
+
+      hosts:  # instances
+        app-1: