Skip to main content
Version: 1.x

NATS

Overview​

The wasmCloud lattice is built on NATS, an open source connective technology hosted by the Cloud Native Computing Foundation (CNCF). NATS enables secure application-layer networking across diverse environments including edge, different vendors' clouds, and on-premise datacenters.

NATS is designed to provide seamless connectivity tailored specifically to distributed systems, avoiding the complexities and limitations of 1:1 communication frameworks like HTTP or gRPC in distributed use cases. In wasmCloud, NATS uses WIT-over-RPC (wRPC) as a transport protocol and helps to deliver a lattice with out-of-the-box load balancing, failover, and other features for systems that span environments.

Supercluster pattern​

Supercluster pattern

NATS enables a "supercluster" architecture for wasmCloud, with multiple NATS clusters connected through NATS Gateways. The supercluster architecture provides...

  • Scalability: Seamlessly scales communication across multiple clusters, ensuring applications can grow without limitation.
  • Reliability: Enhances the overall reliability of the system by providing failover and load balancing across clusters.
  • Geo-awareness: Geo-affinity is implemented automatically in queuing, ensuring that service requests are handled by the nearest available cluster, reducing latency and improving performance.

A leaf node is a specially configured NATS server that creates a local NATS network that functions even without a connection to the broader network. This can allow for even further scaling and lower latency in use cases such as edge and IoT.

Compared to Kubernetes...

Where Kubernetes uses HTTP and DNS (or alternatively a service mesh solution) for connectivity across a cluster, wasmCloud uses NATS for a "distributed-first" approach. Challenge areas for Kubernetes such as edge, multi-cluster, and multi-cloud are first-class use cases in wasmCloud. NATS also fulfills roles comparable to those served by etcd in Kubernetes, such as storing state.

Essential NATS concepts​

NATS conceptualizes communications as messages. Applications send and receive messages identified by subject strings. In addition to the subject, messages contain a byte array payload and any number of header fields.

Topics and subjects

What is called a "subject" in NATS is often called a "topic" in messaging systems more generally, including Apache Kafka, Google Cloud Pub/Sub, and Confluent, as well as the wasi-messaging proposal. In this documentation, we use "subject" in NATS-specific contexts, but you can think of "topic" and "subject" as essentially interchangeable.

An entity that sends a message is a publisher. When a publisher sends a message, it may be received by one or more subscribers. This one-to-many communication pattern is called the publish-subscribe model.

NATS supports a request-reply pattern built on the publish-subscribe model. A publisher may send a "reply" message (the "request") on a given subject. Entities subscribed to the subject may send replies which are automatically directed back to the original request publisher.

In addition to the core publish-subscribe functionality, NATS provides streaming and key-value storage through its distributed persistence system called JetStream:

  • Streams are stores for messages on a given subject.
  • Buckets are immediately consistent key-value stores using strings as keys and byte arrays as values (used in wasmCloud for tasks such as storing application manifests).

Streams and buckets play an important role in the scheduling process of the wasmCloud Application Deployment Manager (wadm). See the wadm section for more information.

Queue subscriptions​

In addition to subscribing to a subject, subscribers may register themselves as part of a queue group: a collection of potential receivers between whom messages are automatically load-balanced, so that only one subcriber ultimately receives the message. There is an equal likelihood that any given member of the queue group will receive any given message.

Usage of queue groups is defined at the publisher and subscriber level, meaning that it can facilitate workload scaling with server configuration.

In wasmCloud, components and providers use this queue subscription model to subscribe to invocations. When a component or provider exports a function, the system creates a queue subscription on a NATS subject that other entities can call.

NATS queue subscription diagram

In the diagram above:

  1. A component imports a function on a linked provider over a shared interface.
  2. When the component runs, an invocation message is published to a queue group.
  3. There are three instances of the linked provider on the lattice. Any one of those three could receive the invocation. In this case, Provider-3 gets the invocation message and runs its exported function.

With this basic model, queue groups and queue subscription facilitate horizontal scaling, load balancing, and failover for components and providers.

Using the NATS CLI​

You can interact directly with NATS using the NATS CLI. While it is not necessary to install the NATS CLI to use wasmCloud, it can be useful for debugging. Installation instructions for the CLI are available on the NATS CLI GitHub repo.

To list all streams on your NATS network:

shell
nats stream list

When running a wasmCloud host and wadm, the listed streams for a wasmCloud lattice will include:

  • wadm_commands
  • wadm_events
  • wadm_mirror
  • wadm_notify
  • wadm_status

You can list all key-value buckets on your NATS instance with:

shell
nats kv list

The listed key-value buckets will include:

  • CONFIGDATA_default
  • wadm_manifests
  • wadm_state
  • LATTICEDATA_default

For more information on debugging and NATS, see the troubleshooting section.

Keep reading​