NATS services

Apcera provides the gnatsd service gateway for creating NATS services for sending and consuming NATS messages.

Creating NATS services and bindings

The gnatsd service gateway creates a NATS service to which you can bind one or more jobs.

For example, the following APC command creates a NATS service named nats-server:

apc service create nats-server --type gnatsd
╭──────────────────────────────────────────────────────╮
│              Service Creation Settings               │
├───────────────┬──────────────────────────────────────┤
│      Service: │ service::/sandbox/admin::nats-server │
│ Service Type: │ gnatsd                               │
╰───────────────┴──────────────────────────────────────╯

Is this correct? [Y/n]: 
Creating service... done
Success!

The following APC command creates the nats-server service and binds the job nats-pub to this service:

apc service create nats-server --type gnatsd --job nats-pub

Note that you do not need to create a provider to implement NATS services. When you create a NATS service, the NATS server runs as a job in the namespace where it was created.

For example:

apc job list
Working in "/sandbox/admin"
╭───────────────────────┬──────┬────────────────┬─────────┬───────────╮
│ Name                  │ Type │ Namespace      │ Status  │ Instances │
├───────────────────────┼──────┼────────────────┼─────────┼───────────┤
│ gnatsd/nats-server    │ job  │ /sandbox/admin │ started │ 1/1       │
│ nats-pub              │ job  │ /sandbox/admin │ started │ 1/1       │
│ nats-sub              │ job  │ /sandbox/admin │ started │ 1/1       │
╰───────────────────────┴──────┴────────────────┴─────────┴───────────╯
apc job show gnatsd/nats-server
╭──────────────────────┬────────────────────────────────────────────────────╮
│ Job:                 │ gnatsd/nats-server                                 │
├──────────────────────┼────────────────────────────────────────────────────┤
│ FQN:                 │ job::/sandbox/admin::gnatsd/nats-server            │
│ State:               │ started                                            │
│                      │                                                    │
│ Created by:          │ admin@apcera.me                                    │
│ Created at:          │ 2016-04-07 04:41:02.160206557 +0000 UTC            │
│ Updated by:          │ admin@apcera.me                                    │
│ Updated at:          │ 2016-04-07 04:41:02.202457092 +0000 UTC            │
│                      │                                                    │
│ Running Instances:   │ 1/1 started                                        │
│                      │                                                    │
│ Restart:             │ always                                             │
│ ...                  │                                                    │
╰──────────────────────┴────────────────────────────────────────────────────╯

Troubleshooting NATS service gateway

If you receive an error implementing the NATS service gateway, try these troubleshooting tips.

Package error

If you receive the following package dependency error when creating the NATS service:

apc service create nats-server --type gnatsd
╭─────────────────────────────────────────────────╮
│            Service Creation Settings            │
├───────────────┬─────────────────────────────────┤
│      Service: │ service::/sandbox/admin::mynats │
│ Service Type: │ gnatsd                          │
╰───────────────┴─────────────────────────────────╯

Is this correct? [Y/n]: Y
Creating service... error
Error: gnatsd gateway failed to create service: no packages satisfy dependency "package.gnatsd"

This means you do not have the NATS Server package in your cluster.

To remedy this error:

1) Download to your local machine the NATS Server package script file from the Apcera Package Scripts repository:

https://github.com/apcera/package-scripts/blob/master/packages/gnatsd-0.7.2.conf

2) Run the following APC command to build the NATS Server package:

apc package build gnatsd-0.7.2.conf

3) Re-run the service creation command:

apc service create nats-server --type gnatsd

Service gateway error

If you can't create a NATS service, verify that the NATS service gatway is available.

To do this, run the following APC command:

apc gateway list -ns /

You should see a list of all available service gateways in your cluster.

For example:

$ apc gateway list -ns /
Working in "/"
╭──────────┬──────────┬──────────────────────────┬─────────┬───────────╮
│ Name     │ Type     │ Namespace                │ Status  │ Instances │
├──────────┼──────────┼──────────────────────────┼─────────┼───────────┤
│ generic  │ generic  │ /apcera/service-gateways │ started │ 1/1       │
│ gnatsd   │ gnatsd   │ /apcera/service-gateways │ started │ 1/1       │
│ http     │ http     │ /apcera/service-gateways │ started │ 1/1       │
│ ipm      │ ipm      │ /apcera/service-gateways │ started │ 1/1       │
│ memcache │ memcache │ /apcera/service-gateways │ started │ 1/1       │
│ mongodb  │ mongodb  │ /apcera/service-gateways │ started │ 1/1       │
│ mysql    │ mysql    │ /apcera/service-gateways │ started │ 1/1       │
│ network  │ network  │ /apcera/service-gateways │ started │ 1/1       │
│ nfs      │ nfs      │ /apcera/service-gateways │ started │ 1/1       │
│ postgres │ postgres │ /apcera/service-gateways │ started │ 1/1       │
│ rabbitmq │ rabbitmq │ /apcera/service-gateways │ started │ 1/1       │
│ redis    │ redis    │ /apcera/service-gateways │ started │ 1/1       │
│ s3       │ s3       │ /apcera/service-gateways │ started │ 1/1       │
╰──────────┴──────────┴──────────────────────────┴─────────┴───────────╯

If a supported service gateway type is not listed, you can manually add it to the cluster.conf file and redeploy the cluster. See Configuring Stagehand for details.

Running NATS Docker image

To run NATS in Docker, see the NATS documentation.

To run NATS as an app in Apcera that you pull from Docker, see the NATS tutorial. Note with this approach the NATS server runs as an app, not a job.

For example:

apc docker run nats-docker -i nats
l[nats-docker] -- Pulling Docker image -- checking policy
[nats-docker] -- Pulling Docker image -- checking if package FQN is taken
[nats-docker] -- Pulling Docker image -- fetching image metadata
[nats-docker] -- Pulling Docker image -- creating package
[nats-docker] -- Pulling Docker image -- all layers downloaded
[nats-docker] -- Creating job
[nats-docker] -- Configuring job -- tagging package
[nats-docker] -- Starting job
[stderr] [5] 2016/04/07 05:06:00.417666 [INF] Starting gnatsd version 0.7.2
[stderr] [5] 2016/04/07 05:06:00.417711 [INF] Starting http monitor on 0.0.0.0:8222
[stderr] [5] 2016/04/07 05:06:00.417812 [INF] Listening for route connections on :6222
[stderr] [5] 2016/04/07 05:06:00.417876 [INF] Listening for client connections on 0.0.0.0:4222
[stderr] [5] 2016/04/07 05:06:00.417906 [INF] gnatsd is ready
apc job list
Working in "/sandbox/admin"
╭───────────────────────┬──────┬────────────────┬─────────┬───────────╮
│ Name                  │ Type │ Namespace      │ Status  │ Instances │
├───────────────────────┼──────┼────────────────┼─────────┼───────────┤
│ gnatsd/nats-server    │ job  │ /sandbox/admin │ started │ 1/1       │
│ nats-docker           │ app  │ /sandbox/admin │ started │ 1/1       │
│ nats-pub              │ job  │ /sandbox/admin │ started │ 1/1       │
│ nats-sub              │ job  │ /sandbox/admin │ started │ 1/1       │
╰───────────────────────┴──────┴────────────────┴─────────┴───────────╯