https://github.com/zendesk/ipcluster
Node.js master/worker clustering module for sticky session load balancing using IPTABLES
https://github.com/zendesk/ipcluster
Last synced: 10 months ago
JSON representation
Node.js master/worker clustering module for sticky session load balancing using IPTABLES
- Host: GitHub
- URL: https://github.com/zendesk/ipcluster
- Owner: zendesk
- License: apache-2.0
- Created: 2014-11-20T01:45:50.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2024-12-09T04:05:02.000Z (over 1 year ago)
- Last Synced: 2025-03-25T16:51:35.724Z (over 1 year ago)
- Language: JavaScript
- Size: 93.8 KB
- Stars: 21
- Watchers: 326
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
IPCluster
=========
IPCluster is a "bare-metal" library for Node.js to manage multi-core concurrency, with sticky sessions and zero-downtime reloading.
Features
--------
* Sticky sessions (via iptables abuse) - suitable for long-polling
* Configurable per-process and cluster memory limits
* Graceful shutdowns and restarts
* Renice older workers
Dependencies
------------
* npm modules - toobusy-js, q
_IPCluster sticky sessions currently requires `iptables` for sticky sessions and so is Linux-only_
Setup
=====
npm dependencies
----------------
npm install
iptables sudo support
---------------------
sudo iptables support is required in order to support sticky sessions.
Add to sudoers (visudo):
ALL=(ALL) NOPASSWD: /sbin/iptables -t nat -L
ALL=(ALL) NOPASSWD: /sbin/iptables -t nat -[ID] PREROUTING -p tcp -m tcp -s 0.0.0.*/0.0.0.* -d * --dport 80 -j REDIRECT --to-ports ?????
ALL=(ALL) NOPASSWD: /sbin/iptables -t nat -[ID] PREROUTING -p tcp -m tcp -s 0.0.0.*/0.0.0.* -d * --dport 443 -j REDIRECT --to-ports ?????
etc. for other ports
Change `` to the running user.
Thankfully, iptables does not allow duplicate copies of most flags, so that the `*` wildcards can't be abused (much). Nonetheless, security feedback is welcome. An alternative for `*` would be appreciated.
Usage
=====
npm install ipcluster --save
See https://github.com/zendesk/zopim-ipcluster-example for a simple example.
In your application
-------------------
### Deploying new code / Running a new batch of workers
Once you app is ipcluster-enabled, starting it should start a master that will spawn multiple workers. The workers are _not_ child processes (they will outlive the master).
To start a new batch a workers (e.g. when you are deployig new code), you should kill off the old master, and start a new master. The old workers will still be running happily.
Starting a new master will do 2 things:
- Spawn a new generation of workers, running your latest code for all new incoming connections
- Become the master for all old workers, and manage their retirement and (eventual) destruction
Note: you can start a new master without first killing the old one. The new master will find and terminate the old master as part of its boot up sequence.
Signals
-------
The master process understands these signals:
- `SIGUSR1`: Kills all retired workers.
Contributing
============
Linting
-------------------
Run eslint
npm run lint
Testing
-------
ipcluster contains some unit tests made with [nodeunit](https://github.com/caolan/nodeunit) (with many more to come, thanks to **you**!). At the root of the project run:
npm test
Do run the test suite prior to committing.
Copyright and license
=====================
Copyright 2014 Zopim
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.