From ce705a504b8841177a52bf4c47077222efc5ac74 Mon Sep 17 00:00:00 2001 From: Alberto Ricart Date: Wed, 15 May 2019 14:53:38 -0500 Subject: [PATCH] wip --- nats_docker/README.md | 258 ++++++++++++++++++++++++++++++++ nats_docker/tutorial.md | 59 ++++++++ nats_tools/README.md | 5 + nats_tools/nats_top/README.md | 81 ++++++++++ nats_tools/nats_top/tutorial.md | 137 +++++++++++++++++ 5 files changed, 540 insertions(+) create mode 100644 nats_docker/README.md create mode 100644 nats_docker/tutorial.md create mode 100644 nats_tools/README.md create mode 100644 nats_tools/nats_top/README.md create mode 100644 nats_tools/nats_top/tutorial.md diff --git a/nats_docker/README.md b/nats_docker/README.md new file mode 100644 index 0000000..ef1e071 --- /dev/null +++ b/nats_docker/README.md @@ -0,0 +1,258 @@ + +## NATS Server Containerization + +The NATS server is provided as a Docker image on [Docker Hub](https://hub.docker.com/_/nats/) that you can run using the Docker daemon. The NATS server Docker image is extremely lightweight, coming in under 10 MB in size. + +Synadia actively maintains and supports the NATS server Docker image. + +### Usage + +To use the Docker container image, install Docker and pull the public image: + +```sh +> docker pull nats +``` + +Run the NATS server image: + +```sh +> docker run -d --name nats-main nats +``` + +By default the NATS server exposes multiple ports: + +- 4222 is for clients. +- 8222 is an HTTP management port for information reporting. +- 6222 is a routing port for clustering. +- Use -p or -P to customize. + +For example: + +```sh +$ docker run -d --name nats-main nats +[INF] Starting nats-server version 0.6.6 +[INF] Starting http monitor on port 8222 +[INF] Listening for route connections on 0.0.0.0:6222 +[INF] Listening for client connections on 0.0.0.0:4222 +[INF] nats-server is ready +``` + +To run with the ports exposed on the host: + +```sh +> docker run -d -p 4222:4222 -p 6222:6222 -p 8222:8222 --name nats-main nats +``` + +To run a second server and cluster them together: + +```sh +> docker run -d --name=nats-2 --link nats-main nats --routes=nats-route://ruser:T0pS3cr3t@nats-main:6222 +``` + +**NOTE** Since the Docker image protects routes using credentials we need to provide them above. Extracted [from Docker image configuration](https://github.com/nats-io/nats-docker/blob/master/amd64/nats-server.conf#L16-L20) + +```ascii +# Routes are protected, so need to use them with --routes flag +# e.g. --routes=nats-route://ruser:T0pS3cr3t@otherdockerhost:6222 +authorization { + user: ruser + password: T0pS3cr3t + timeout: 2 +} +``` + +To verify the routes are connected: + +```sh +$ docker run -d --name=nats-2 --link nats-main nats --routes=nats-route://ruser:T0pS3cr3t@nats-main:6222 -DV +[INF] Starting nats-server version 0.6.6 +[INF] Starting http monitor on port 8222 +[INF] Listening for route connections on :6222 +[INF] Listening for client connections on 0.0.0.0:4222 +[INF] nats-server is ready +[DBG] Trying to connect to route on nats-main:6222 +[DBG] 172.17.0.52:6222 - rid:1 - Route connection created +[DBG] 172.17.0.52:6222 - rid:1 - Route connect msg sent +[DBG] 172.17.0.52:6222 - rid:1 - Registering remote route "ee35d227433a738c729f9422a59667bb" +[DBG] 172.17.0.52:6222 - rid:1 - Route sent local subscriptions +``` + +## Clustering With Docker + +Below is are a couple examples of how to setup nats-server cluster using Docker. We put 3 different configurations (one per nats-server server) under a folder named conf as follows: + +```ascii +|-- conf + |-- nats-server-A.conf + |-- nats-server-B.conf + |-- nats-server-C.conf +``` + +Each one of those files have the following content below: (Here I am using ip 192.168.59.103 as an example, so just replace with the proper ip from your server) + +### Example 1: Setting up a cluster on 3 different servers provisioned beforehand + +In this example, the three servers are started with config files that know about the other servers. + +#### nats-server-A + +```ascii +# Cluster Server A + +port: 7222 + +cluster { + host: '0.0.0.0' + port: 7244 + + routes = [ + nats-route://192.168.59.103:7246 + nats-route://192.168.59.103:7248 + ] +} +``` + +#### nats-server-B + +```ascii +# Cluster Server B + +port: 8222 + +cluster { + host: '0.0.0.0' + port: 7246 + + routes = [ + nats-route://192.168.59.103:7244 + nats-route://192.168.59.103:7248 + ] +} +``` + +#### nats-server-C + +```ascii +# Cluster Server C + +port: 9222 + +cluster { + host: '0.0.0.0' + port: 7248 + + routes = [ + nats-route://192.168.59.103:7244 + nats-route://192.168.59.103:7246 + ] +} +``` + +To start the containers, on each one of your servers, you should be able to start the nats-server image as follows: + +```sh +docker run -it -p 0.0.0.0:7222:7222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-A.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 7222 -D -V +``` + +``` +docker run -it -p 0.0.0.0:8222:8222 -p 0.0.0.0:7246:7246 --rm -v $(pwd)/conf/nats-server-B.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 8222 -D -V +``` + +``` +docker run -it -p 0.0.0.0:9222:9222 -p 0.0.0.0:7248:7248 --rm -v $(pwd)/conf/nats-server-C.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 9222 -D -V +``` + +### Example 2: Setting a nats-server cluster one by one + +In this scenario: + +- We bring up A and get its ip (nats-route://192.168.59.103:7244) +- Then create B and then use address of A in its configuration. +- Get the address of B nats-route://192.168.59.104:7246 and create C and use the addresses of A and B. + +First, we create the Node A and start up a nats-server server with the following config: + +```ascii +# Cluster Server A + +port: 4222 + +cluster { + host: '0.0.0.0' + port: 7244 + +} +``` + +```sh +docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-A.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 4222 -D -V +``` + +Then we proceed to create the next node. We realize that the first node has ip:port as `192.168.59.103:7244` so we add this to the routes configuration as follows: + +```ascii +# Cluster Server B + +port: 4222 + +cluster { + host: '0.0.0.0' + port: 7244 + + routes = [ + nats-route://192.168.59.103:7244 + ] +} +``` + +Then start server B: + +```sh +docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-B.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 4222 -D -V +``` + +Finally, we create another Node C. We now know the routes of A and B so we can add it to its configuration: + +```ascii +# Cluster Server C + +port: 4222 + +cluster { + host: '0.0.0.0' + port: 7244 + + routes = [ + nats-route://192.168.59.103:7244 + nats-route://192.168.59.104:7244 + ] +} +``` + +Then start it: + +```sh +docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-C.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 9222 -D -V +``` + +### Testing the Clusters + +Now, the following should work: make a subscription to Node A then publish to Node C. You should be able to to receive the message without problems. + +```sh +nats-sub -s "nats://192.168.59.103:7222" hello & + +nats-pub -s "nats://192.168.59.105:7222" hello world + +[#1] Received on [hello] : 'world' + +# GNATSD on Node C logs: +[1] 2015/06/23 05:20:31.100032 [TRC] 192.168.59.103:7244 - rid:2 - <<- [MSG hello RSID:8:2 5] + +# GNATSD on Node A logs: +[1] 2015/06/23 05:20:31.100600 [TRC] 10.0.2.2:51007 - cid:8 - <<- [MSG hello 2 5] +``` + +## Tutorial + +See the [NATS Docker tutorial](tutorial.md) for more instructions on using the NATS server Docker image. diff --git a/nats_docker/tutorial.md b/nats_docker/tutorial.md new file mode 100644 index 0000000..db0fc8d --- /dev/null +++ b/nats_docker/tutorial.md @@ -0,0 +1,59 @@ +## NATS Docker Tutorial + +In this tutorial you run the [NATS server Docker image](https://hub.docker.com/_/nats/). The Docker image provides an instance of the [NATS Server](/documentation/server/gnatsd-intro/). Synadia actively maintains and supports the gnatsd Docker image. The NATS image is only 6 MB in size. + +**1. Set up Docker.** + +See [Get Started with Docker](http://docs.docker.com/mac/started/) for guidance. + +The easiest way to run Docker is to use the [Docker Toolbox](http://docs.docker.com/mac/step_one/). + +**2. Run the gnatsd Docker image.** + +```sh +> docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 --name gnatsd -ti nats:latest +``` + +**3. Verify that the NATS server is running.** + +You should see the following: + +```sh +Unable to find image 'nats:latest' locally +latest: Pulling from library/nats +2d3d00b0941f: Pull complete +24bc6bd33ea7: Pull complete +Digest: sha256:47b825feb34e545317c4ad122bd1a752a3172bbbc72104fc7fb5e57cf90f79e4 +Status: Downloaded newer image for nats:latest +``` + +Followed by this, indicating that the NATS server is running: + +```sh +[1] 2017/06/28 18:34:19.605144 [INF] Starting nats-server version 0.9.6 +[1] 2017/06/28 18:34:19.605191 [INF] Starting http monitor on 0.0.0.0:8222 +[1] 2017/06/28 18:34:19.605286 [INF] Listening for client connections on 0.0.0.0:4222 +[1] 2017/06/28 18:34:19.605312 [INF] Server is ready +[1] 2017/06/28 18:34:19.608756 [INF] Listening for route connections on 0.0.0.0:6222 +``` + +Notice how quickly the NATS server Docker image downloads. It is a mere 6 MB in size. + +**4. Test the NATS server to verify it is running.** + +An easy way to test the client connection port is through using telnet. + +```sh +> telnet localhost 4222 +``` + +Expected result: + +```sh +Trying ::1... +Connected to localhost. +Escape character is '^]'. +INFO {"server_id":"YMeTi2z178lM5SG302YgH2","version":"0.9.6","go":"go1.7.4","host":"0.0.0.0","port":4222,"auth_required":false,"ssl_required":false,"tls_required":false,"tls_verify":false,"max_payload":1048576} +``` + +You can also test the monitoring endpoint, viewing `http://localhost:8222` with a browser. \ No newline at end of file diff --git a/nats_tools/README.md b/nats_tools/README.md new file mode 100644 index 0000000..c478ae8 --- /dev/null +++ b/nats_tools/README.md @@ -0,0 +1,5 @@ +## NATS Tools + +The NATS Ecosystem has many tools, some interesting tools include: + +- [NATS TOP (statistics)](nats_top/README.md) \ No newline at end of file diff --git a/nats_tools/nats_top/README.md b/nats_tools/nats_top/README.md new file mode 100644 index 0000000..133a66e --- /dev/null +++ b/nats_tools/nats_top/README.md @@ -0,0 +1,81 @@ +## NATS TOP + +[nats-top](https://github.com/nats-io/nats-top) is a [top](http://man7.org/linux/man-pages/man1/top.1.html)-like tool for monitoring nats-server servers. + +The nats-top tool provides a dynamic real-time view of a NATS server. nats-top can display a variety of system summary information about the NATS server, such as subscription, pending bytes, number of messages, and more, in real time. For example: + +```sh +nats-top + +nats-server version 0.6.4 (uptime: 31m42s) +Server: + Load: CPU: 0.8% Memory: 5.9M Slow Consumers: 0 + In: Msgs: 34.2K Bytes: 3.0M Msgs/Sec: 37.9 Bytes/Sec: 3389.7 + Out: Msgs: 68.3K Bytes: 6.0M Msgs/Sec: 75.8 Bytes/Sec: 6779.4 + +Connections: 4 + HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION SUBSCRIPTIONS + 127.0.0.1:56134 2 5 0 11.6K 11.6K 1.1M 905.1K go 1.1.0 foo, hello + 127.0.1.1:56138 3 1 0 34.2K 0 3.0M 0 go 1.1.0 _INBOX.a96f3f6853616154d23d1b5072 + 127.0.0.1:56144 4 5 0 11.2K 11.1K 873.5K 1.1M go 1.1.0 foo, hello + 127.0.0.1:56151 5 8 0 11.4K 11.5K 1014.6K 1.0M go 1.1.0 foo, hello +``` + +## Installation + +nats-top can be installed using `go get`. For example: + +```sh +go get github.com/nats-io/nats-top +``` + +NOTE: You may have to run the above command as user `sudo` depending on your setup. If you receive an error that you cannot install nats-top because your $GOPATH is not set, when in fact it is set, use command `sudo -E go get github.com/nats-io/nats-top` to install nats-top. The `-E` flag tells sudo to preserve the current user's environment. + +## Usage + +Once installed, nats-top can be run with the command `nats-top` and optional arguments. + +```sh +nats-top [-s server] [-m monitor] [-n num_connections] [-d delay_in_secs] [-sort by] +``` + +## Options + +Optional arguments inclde the following: + +| Option | Description | +|-----------------------|-----------------------------------------------| +| `-m monitor` | Monitoring http port from nats-server. | +| `-n num_connections` | Limit the connections requested to the server (default 1024). | +| `-d delay_in_secs` | Screen refresh interval (default 1 second). | +| `-sort by` | Field to use for sorting the connections (see below). | + +## Commands + +While in nats-top view, you can use the following commands. + +### option + +Use the `o