Skip to content

Commit dbc281b

Browse files
scottinetalexandrebouthinon
scottinet
authored and
alexandrebouthinon
committed
Add a clustering guide (#314)
Add an advanced guide about clustering/scalability (I want these 2 words to be referenced by Algolia). URL path: core/1/guides/kuzzle-depth/scalability/ Remove obsolete information from the plugin guide. URL path: /core/1/guide/guides/essentials/plugins
1 parent f439fa3 commit dbc281b

File tree

2 files changed

+246
-31
lines changed

2 files changed

+246
-31
lines changed

‎src/core/1/guides/essentials/plugins/index.md‎

Lines changed: 13 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ For example, imagine you are developing a mobile application that accesses a **t
1313

1414
Kuzzle's **[Plugin Engine](/core/1/plugins)** is a powerful feature that ensures that Kuzzle meets any project requirement:
1515

16-
- select from a set of prebuilt plugins (such as the [OAuth2 Authentication Plugin](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-oauth) or the [MQTT Protocol](https://github.com/kuzzleio/protocol-mqtt)).
17-
- [create your own plugin](/core/1/plugins/essentials) to meet your specific requirements.
16+
- select from a set of prebuilt plugins (such as the [OAuth2 Authentication Plugin](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-oauth) or the [Cluster Plugin](https://github.com/kuzzleio/kuzzle-plugin-cluster)).
17+
- [create your own plugin](/core/1/guides/essentials/introduction/) to meet your specific requirements.
1818

1919
---
2020

@@ -41,10 +41,7 @@ Kuzzle ships with the [Local Strategy Plugin](https://github.com/kuzzleio/kuzzle
4141

4242
## Protocols
4343

44-
[Protocols](/core/1/protocols) add extended networking capabilities to your Kuzzle installation. These are useful if you need to handle other, even proprietary transport protocols.
45-
46-
_Example - "Allow Kuzzle to interact with XMPP-oriented services"_
47-
Kuzzle ships with the [MQTT Protocol](https://github.com/kuzzleio/protocol-mqtt).
44+
[Protocols](/core/1/protocols/essentials/getting-started) add extended networking capabilities to your Kuzzle installation. These are useful if you need to handle other, even proprietary transport protocols.
4845

4946
---
5047

@@ -66,7 +63,7 @@ Go to the Kuzzle installation folder and type:
6663

6764
```bash
6865
# Open plugins/available folder
69-
cd plugins/available
66+
cd <kuzzle directory>/plugins/available
7067

7168
# Download Plugin to plugins/available folder
7269
git clone https://github.com/kuzzleio/kuzzle-core-plugin-boilerplate.git
@@ -75,13 +72,11 @@ git clone https://github.com/kuzzleio/kuzzle-core-plugin-boilerplate.git
7572
cd kuzzle-core-plugin-boilerplate
7673
npm install # add --unsafe-perm if installing from inside a docker container
7774

78-
# Open plugins/enabled folder
75+
# Enable the installed plugin. Delete this link to disable it
7976
cd ../../enabled
77+
ln -s ../available/kuzzle-core-plugin-boilerplate
8078

81-
# Creata the symbolic link from the enabled folder to the available folder
82-
ln -s ../available/kuzzle-core-plugin-boilerplate .
83-
84-
# Restart Kuzzle to reload Plugins
79+
# Restart Kuzzle to reload plugins
8580
```
8681

8782
---
@@ -143,36 +138,23 @@ Note that the plugin description above contains a property for each plugin compo
143138

144139
The steps to install a new protocol are exactly the same than for plugins, except that you have to use the `protocols/` directory, instead of the `plugins/` one.
145140

146-
For instance, to install the MQTT protocol:
141+
To install a protocol:
147142

148143
```bash
149144
# In Kuzzle's directory:
150145
cd protocols/available
151146

152-
git clone https://github.com/kuzzleio/protocol-mqtt.git
147+
# copy the protocol folder into the current directory
148+
cp -r <protocol_dir> .
153149

154150
# Install the protocol's dependencies
155-
cd protocol-mqtt
151+
cd <protocol_dir>
156152
npm install # add --unsafe-perm if installing from inside a docker container
157153

158-
# Open plugins/enabled folder
154+
# Enable the installed plugin. Delete this link to disable it
159155
cd ../../enabled
160-
161-
# Creata the symbolic link from the enabled folder to the available folder
162-
ln -s ../available/protocol-mqtt .
156+
ln -s ../available/<protocol_dir>
163157

164158
# Restart Kuzzle to reload protocols
165159
```
166160

167-
---
168-
169-
## Going Further
170-
171-
To get more insight into how plugins work, please refer to the [Plugin Reference](/core/1/plugins).
172-
173-
Here is a list of official plugins:
174-
175-
- [**kuzzle-plugin-auth-passport-local**](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-local): authentication Plugin shipped with Kuzzle
176-
- [**kuzzle-plugin-logger**](https://github.com/kuzzleio/kuzzle-plugin-logger): plugin shipped with Kuzzle
177-
- [**kuzzle-plugin-auth-passport-oauth**](https://github.com/kuzzleio/kuzzle-plugin-auth-passport-oauth): authentication plugin
178-
- [**protocol-mqtt**](https://github.com/kuzzleio/protocol-mqtt): MQTT network protocol

‎src/core/1/guides/kuzzle-depth/scalability/index.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
---
2+
code: false
3+
type: page
4+
title: Scalability
5+
---
6+
7+
# Scalability
8+
9+
Kuzzle can scale horizontally, provided our [official Cluster Plugin](https://github.com/kuzzleio/kuzzle-plugin-cluster) is installed.
10+
11+
This guide covers how clustering capabilities can be added to Kuzzle.
12+
13+
---
14+
15+
## Quick start
16+
17+
This chapter shows how to quickly create a Kuzzle cluster stack for development purposes. If you already have an existing Kuzzle server running, you may want to read the manual install chapter instead.
18+
19+
::: info
20+
This development stack is for demonstration and test purposes only and should not be used as-is on production.
21+
22+
Notably, this stack only starts Kuzzle in cluster mode: Elasticsearch and Redis are not clustered.
23+
:::
24+
25+
Install and run:
26+
27+
```bash
28+
git clone https://github.com/kuzzleio/kuzzle-plugin-cluster.git
29+
cd kuzzle-plugin-cluster
30+
docker-compose -p cluster up --scale kuzzle=3
31+
```
32+
33+
You should now have a Kuzzle cluster stack running with 3 Kuzzle nodes.
34+
35+
### ENOSPC error
36+
37+
On some Linux environments, you may get `ENOSPC` errors from the filesystem watcher, because of limits set too low.
38+
39+
If that happens, simply raise the limits on the number of files that can be watched:
40+
41+
`sudo sysctl -w fs.inotify.max_user_watches=524288`
42+
43+
That configuration change will last until the next reboot.
44+
45+
To make it permanent, add the following line to your `/etc/sysctl.conf` file:
46+
47+
```
48+
fs.inotify.max_user_watches=524288
49+
```
50+
51+
---
52+
53+
## Manual install on an existing Kuzzle installation
54+
55+
To add cluster capabilities to an existing Kuzzle installation, the cluster plugin must be installed by following the [Plugin Install Guide](/core/1/guides/essentials/plugins/#installing-a-plugin).
56+
57+
::: info
58+
If you are running Kuzzle in a Docker container, you will need to access the running container's shell and then the Kuzzle installation folder inside the container.
59+
:::
60+
61+
To install the cluster plugin, follow these steps:
62+
63+
```bash
64+
cd <kuzzle directory>/plugins/available
65+
66+
git clone https://github.com/kuzzleio/kuzzle-plugin-cluster.git
67+
68+
cd kuzzle-plugin-cluster
69+
npm install # add --unsafe-perm if installing from inside a docker container
70+
71+
# Enable the installed plugin. Delete this link to disable it
72+
cd ../../enabled
73+
ln -s ../available/kuzzle-plugin-cluster
74+
```
75+
76+
### Cluster plugin configuration
77+
78+
* The cluster plugin requires a privileged context from Kuzzle. This context is granted by Kuzzle via the global configuration.
79+
* The cluster plugin registers a few [pipes](/core/1/plugins/guides/pipes/), and some of them may exceed the default pipe timeouts.
80+
81+
Add the following to your kuzzlerc configuration file (see our [Kuzzle configuration guide](/core/1/guides/essentials/configuration/)):
82+
83+
```js
84+
"plugins": {
85+
"common": {
86+
"pipeWarnTime": 5000,
87+
"pipeTimeout": 10000
88+
},
89+
"cluster": {
90+
"privileged": true
91+
}
92+
}
93+
```
94+
95+
Once the plugin installed and configured, you can start as many Kuzzle instances as you need, and they will automatically synchronize and work together.
96+
97+
---
98+
99+
## Extended API
100+
101+
The cluster plugin adds an [API controller](/core/1/plugins/guides/controllers) named `cluster`, with the following actions defined:
102+
103+
### health
104+
105+
The `cluster:health` API action returns the cluster health status.
106+
107+
#### HTTP
108+
109+
```
110+
GET http://<host>:<port>/_plugin/cluster/health
111+
```
112+
113+
#### Other Protocols
114+
115+
```js
116+
{
117+
"controller": "cluster/cluster",
118+
"action": "health"
119+
}
120+
```
121+
122+
#### Result
123+
124+
```js
125+
{
126+
"status": 200,
127+
"error": null,
128+
"controller": "cluster/cluster",
129+
"action": "health",
130+
"result": "ok"
131+
}
132+
````
133+
134+
### reset
135+
136+
The `cluster:reset` API action resets the cluster state and forces a resync.
137+
138+
#### HTTP
139+
140+
```
141+
POST http://<host>:<port>/_plugin/cluster/reset
142+
```
143+
144+
#### Other Protocols
145+
146+
```js
147+
{
148+
"controller": "cluster/cluster",
149+
"action": "reset"
150+
}
151+
```
152+
153+
#### Result
154+
155+
```js
156+
{
157+
"status": 200,
158+
"error": null,
159+
"controller": "cluster/cluster",
160+
"action": "reset",
161+
"result": "ok"
162+
}
163+
````
164+
165+
### status
166+
167+
The `cluster:status` API action returns the current cluster status.
168+
169+
#### HTTP
170+
171+
```
172+
GET http://<host>:<port>/_plugin/cluster/status
173+
```
174+
175+
#### Other Protocols
176+
177+
```js
178+
{
179+
"controller": "cluster/cluster",
180+
"action": "status"
181+
}
182+
```
183+
184+
#### Result
185+
186+
```js
187+
{
188+
"status": 200,
189+
"error": null,
190+
"controller": "cluster/cluster",
191+
"action": "status",
192+
"result": {
193+
"count": 3,
194+
"current": {
195+
"pub": "tcp://<kuzzle node IP>:7511",
196+
"router": "tcp://<kuzzle node IP>:7510",
197+
"ready": true
198+
},
199+
"pool": [
200+
{
201+
"pub": "tcp://<kuzzle node IP>:7511",
202+
"router": "tcp://<kuzzle node IP>:7510",
203+
"ready": true
204+
},
205+
{
206+
"pub": "tcp://<kuzzle node IP>:7511",
207+
"router": "tcp://<kuzzle node IP>:7510",
208+
"ready": true
209+
}
210+
]
211+
}
212+
}
213+
```
214+
215+
---
216+
217+
## How a Kuzzle cluster works
218+
219+
### Auto-discovery and Synchronization
220+
221+
Kuzzle nodes are synchronized by maintaining their state in a [Redis](https://redis.io/) server instance, and they constantly exchange information using the [0mq](http://zeromq.org/) messaging library.
222+
223+
What this means is that, to scale horizontally, all a Kuzzle node needs is a reachable Redis instance, and to be able to connect to other nodes.
224+
When these conditions are met, a Kuzzle node with the cluster plugin installed only needs to be started to automatically synchronize its state and to work together with the other nodes.
225+
226+
Check our [Kuzzle configuration guide](/core/1/guides/essentials/configuration/) to know how to make Kuzzle connect to specific Redis instances.
227+
228+
### Load Balancing
229+
230+
A load balancer in front of a Kuzzle cluster is hugely advised, to dispatch user connections to different Kuzzle nodes.
231+
Once assigned to a Kuzzle node, a client stays attached to it until their connection drop; when needed, a Kuzzle node automatically dispatches valuable information to other nodes.
232+
233+
Any load balancer will do. For instance, our development stack uses nginx for the sake of example.

0 commit comments

Comments
 (0)