Skip to content

Commit 73429ef

Browse files
RoRoJRoRoJ
committed
feat(nats): add doc for nats produc
1 parent 81132ae commit 73429ef

22 files changed

+814
-0
lines changed

‎menu/navigation.json‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4143,6 +4143,82 @@
41434143
"label": "Jobs",
41444144
"slug": "serverless-jobs"
41454145
},
4146+
{
4147+
"items": [
4148+
{
4149+
"label": "Overview",
4150+
"slug": "../messaging"
4151+
},
4152+
{
4153+
"label": "Concepts",
4154+
"slug": "concepts"
4155+
},
4156+
{
4157+
"label": "Quickstart",
4158+
"slug": "quickstart"
4159+
},
4160+
{
4161+
"label": "FAQ",
4162+
"slug": "faq"
4163+
},
4164+
{
4165+
"items": [
4166+
{
4167+
"label": "Create a NATS account",
4168+
"slug": "create-account"
4169+
},
4170+
{
4171+
"label": "Create credentials",
4172+
"slug": "create-credentials"
4173+
},
4174+
{
4175+
"label": "Manage credentials",
4176+
"slug": "manage-credentials"
4177+
},
4178+
{
4179+
"label": "Monitor NATS with Cockpit",
4180+
"slug": "monitor-nats-cockpit"
4181+
},
4182+
{
4183+
"label": "Delete a NATS account",
4184+
"slug": "delete-nats-account"
4185+
}
4186+
],
4187+
"label": "How to",
4188+
"slug": "how-to"
4189+
},
4190+
{
4191+
"items": [
4192+
{
4193+
"label": "NATS API Reference",
4194+
"slug": "https://www.scaleway.com/en/developers/api/messaging-and-queuing/nats-api/"
4195+
},
4196+
{
4197+
"label": "Using the NATS CLI",
4198+
"slug": "nats-cli"
4199+
}
4200+
],
4201+
"label": "API/CLI",
4202+
"slug": "api-cli"
4203+
},
4204+
{
4205+
"items": [
4206+
{
4207+
"label": "NATS overview",
4208+
"slug": "nats-overview"
4209+
},
4210+
{
4211+
"label": "Limitations",
4212+
"slug": "limitations"
4213+
}
4214+
],
4215+
"label": "Additional Content",
4216+
"slug": "reference-content"
4217+
}
4218+
],
4219+
"label": "NATS",
4220+
"slug": "nats"
4221+
},
41464222
{
41474223
"items": [
41484224
{

‎pages/nats/api-cli/index.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
meta:
3+
title: NATS - API/CLI Documentation
4+
description: NATS API/CLI Documentation
5+
content:
6+
h1: NATS - API/CLI Documentation
7+
paragraph: NATS API/CLI Documentation
8+
---

‎pages/nats/api-cli/nats-cli.mdx‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
meta:
3+
title: Using the NATS CLI
4+
description: This page explains how to use the NATS CLI with Scaleway NATS
5+
content:
6+
h1: Using the NATS CLI
7+
paragraph: This page explains how to use the NATS CLI with Scaleway NATS
8+
tags: messaging nats cli
9+
categories:
10+
- messaging
11+
dates:
12+
validation: 2024-10-18
13+
posted: 2023-01-20
14+
---
15+
16+
The NATS CLI (`nats`) is the official NATS tool for managing your NATS resources. It allows you to simply create and manage your streams, consumers and more.
17+
18+
Check out the official [NATS CLI documentation](https://docs.nats.io/using-nats/nats-tools/nats_cli/) for installation instructions, examples and more.
19+
20+
<Message type="tip">
21+
You can also configure Scaleway NATS with the Terraform/OpenTofu NATS Jetstream provider using our [dedicated tutorial](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/guides/mnq_with_nats_terraform_provider).
22+
</Message>
23+
24+
This page shows you how to get started with some basic actions via the NATS CLI.
25+
26+
<Macro id="requirements" />
27+
28+
- A Scaleway account logged into the [console](https://console.scaleway.com)
29+
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
30+
- A Scaleway [NATS account](/nats/how-to/create-nats-account)
31+
- NATS [credentials](/nats/how-to/create-credentials/) downloaded to your machine
32+
33+
## Installing the NATS CLI
34+
35+
Follow instructions from the [official NATS documentation](https://docs.nats.io/using-nats/nats-tools/nats_cli#installing-nats). The installation process may differ depending on your OS.
36+
37+
## Define a context
38+
39+
To simplify your interactions with NATS hosted on Scaleway, we recommend that you use [contexts](https://docs.nats.io/using-nats/nats-tools/nats_cli#nats-contexts). A context is a named configuration that stores the settings (such as credentials, URLs and certificates) required to connect to NATS. By creating a context, you won't need to specify your server and credentials with each new request.
40+
41+
### Create a context
42+
43+
The example below creates a context named `scaleway`.
44+
- Replace `{Scaleway NATS URL}` with the URL of your NATS account (find this in the console on your NATS account **Overview** tab).
45+
- Replace `{path to your creds file}` with the path to the location where you [downloaded your `.creds` file](/nats/how-to/create-credentials/).
46+
47+
```bash
48+
nats context save scaleway --server={Scaleway NATS URL} --creds={path to your creds file}
49+
```
50+
51+
### Use the saved context
52+
53+
Enter the following command to select the `scaleway` context for use:
54+
55+
```
56+
nats context select scaleway
57+
```
58+
59+
## Create a stream
60+
61+
To create a [stream](/nats/concepts/#stream), use the command `nats stream add` and follow the CLI guidelines.
62+
63+
<Message type="important">
64+
Bear in mind that:
65+
- Scaleway NATS does not support in-memory streams: choose `File` as storage backend.
66+
- Some [system limits](/nats/reference-content/limitations/) may apply by default.
67+
- If you choose a `Retention Policy` other than `Work Queue` you will be billed for the messages stored and retained.
68+
- Choosing three replicas has an impact on:
69+
- The stream storage limit (as data is replicated 3 times)
70+
- The volume of billed messages
71+
</Message>
72+
73+
You can connect to your stream using code, developer tools or the NATS CLI (for testing purposes only).
74+
75+
## NATS cheat sheet
76+
77+
Use the `nats cheat` command to get a list of all possible commands.
78+
79+
Below we provide a summary of some useful commands.
80+
81+
### General
82+
83+
| Action | Command |
84+
| ------------ | ------------------- |
85+
| Show a specific section of cheats | `nats cheat pub` |
86+
| List available sections | `nats cheat --sections` |
87+
88+
89+
### Messaging
90+
91+
| Action | Command |
92+
| ------------ | ------------------- |
93+
| Publish message from STDIN | `echo "hello world" \| nats pub destination.subject` |
94+
| Publish 100 messages with a random body of 100 - 1000 characters | `nats cheat --sections``nats pub destination.subject "{{ Random 100 1000 }}" -H Count:{{ Count }} --count 100` |
95+
| Publish message from STDINReceive new messages received with the subject ORDERS.new | `nats sub ORDERS.new` |
96+
| Subscribe to messages, on subject source.subject | `nats sub source.subject` |
97+
98+
99+
### Queuing/Streaming
100+
101+
| Action | Command |
102+
| ------------ | ------------------- |
103+
| Adding a stream | `nats stream add` |
104+
| Viewing a stream | `nats stream info STREAMNAME` |
105+
| Removing a stream | `nats stream rm STREAMNAME` |
106+
| Show a list of streams | `nats stream list` |
107+
| Get message `12345` in stream `ORDERS` | `nats stream get ORDERS 12345` |
108+
| Delete message `12345` in stream `ORDERS` | `nats stream rmm ORDERS 12345` |
109+
| Purge messages from stream `ORDERS` | `nats stream purge ORDERS` |
110+
| Mark a stream `ORDERS` as read only | `nats stream seal ORDERS` |
111+
| Add a consumer | `nats consumer add` |
112+
| View a consumer `NEW` of stream `ORDERS` | `nats consumer info ORDERS NEW` |
113+
| Remove consumer `NEW` from stream `ORDERS`| `nats consumer rm ORDERS NEW` |
114+
| Get messages from consumer `NEW` of stream `ORDERS` | `nats consumer next ORDERS NEW --ack --count=10 `, `nats consumer next ORDERS NEW --no-ack`, `nats consumer sub ORDERS NEW --ack` |

‎pages/nats/assets/scaleway-nats-create-account.webp‎

18.7 KB
Loading

‎pages/nats/assets/scaleway-nats-creds.webp‎

22.9 KB
Loading

‎pages/nats/assets/scaleway-nats-overview.webp‎

37.2 KB
Loading

‎pages/nats/concepts.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
meta:
3+
title: NATS - Concepts
4+
description: Understand the core concepts of Scaleway NATS. Explore fundamental principles for efficient message handling and service optimization.
5+
content:
6+
h1: NATS - Concepts
7+
paragraph: Understand the core concepts of Scaleway NATS. Explore fundamental principles for efficient message handling and service optimization.
8+
categories:
9+
-
10+
tags: messaging queuing concepts nats
11+
dates:
12+
validation: 2025-04-01
13+
posted: 2025-04-01
14+
---
15+
16+
## Content-based
17+
18+
The NATS [publish/subscribe model](#publish-subscribe) can be implemented as a content-based or topic-based system. In a content-based messaging system, the subscriber specifies the properties of the messages they want to receive, based on the message’s attributes or content. Message delivery is therefore selective, and messages are only delivered to a subscriber if the attributes or content match the constraints they set.
19+
20+
## Credentials
21+
22+
Credentials give services and platforms access to Scaleway NATS, enabling them to connect to the host system. NATS credentials give full read-write-manage access to your NATS message broker. See the documetnation on [how to create credentials](TODO) for full details.
23+
24+
## Message broker
25+
26+
A message broker is a piece of software that allows applications, systems and services to communicate with each other and send/receive data. It facilitates the exchange of information by receiving messages from a producer, and transmitting them to a consumer. Scaleway NATS is a message broker tool based on the NATS messaging system.
27+
28+
## Messaging and Queuing
29+
30+
Previously, Scaleway Messaging and Queuing was a single product that grouped together three different messaging protocols. It has now been split into three distinct products: [NATS](#nats), [Queues](#queues), and [Topics and Events](#topics-and-events).
31+
32+
## NATS account
33+
34+
A Scaleway NATS account sets a scope for any NATS credentials, messages, queues and streams held within it. You can create one or multiple NATS accounts with Scaleway NATS.
35+
36+
## NATS messaging system
37+
38+
The **N**eural **A**utonomic **T**ransport **S**ystem, or [NATS](https://nats.io/), is a distributed messaging system, designed to be lightweight and high-performance. Fully open-source, it is part of the Cloud Native Computing Foundation (CNCF) and has more than 40 client language implementations.
39+
40+
It implements both of the following:
41+
- A [publish/subscribe](#publish-subscribe) model, designed for real-time messaging and notifications and event-driven architectures. This is ideal for communication between microservices.
42+
- A [streaming service](#stream) via JetStream, providing persistence so that messages can be re-accessed after sending. The streaming add-on is ideal when applications require message replay or historical data access, such as event sourcing and audit logs.
43+
44+
## Publish/Subscribe
45+
46+
This is the primary messaging model for NATS, sometimes abbreviated to "pub/sub". The key feature of publish/subscribe is that the publisher does not send messages to defined recipients. Instead, subscribers define the types of message they are interested in, and only receive messages matching their criteria. The publisher sends the message without knowing exactly who will receive it.
47+
48+
Subscribers can select which messages to receive using[topic-based](#topic-based) or [content-based](#content-based). The publish/subscribe model relies on a [message broker](#message-broker) to relay messages between publishers and subscribers.
49+
50+
## Region
51+
52+
NATS is available in multiple regions. A region designates the geographical area where the service is hosted. Refer to the [product availability table](/account/reference-content/products-availability/) to check which regions are available for NATS.
53+
54+
When [creating a NATS account](/nats/how-to/create-nats-account), you need to do this on a region-by-region basis. The region drop-down in the console allows you to switch between available regions.
55+
56+
## Scaleway NATS
57+
58+
Scaleway NATS is a managed messaging service that leverages the open-source [NATS messaging system](#nats-messaging-system) to enable seamless communication between distributed applications and microservices. Scaleway handles set-up, patching, and performance optimization, as well as scaling to adjust to dynamic workloads, and backups of your data.
59+
60+
Check our our [NATS quickstart](/nats/quickstart/) to get started with Scaleway NATS, or our [tutorial](/tutorials/large-messages/) on creating a serverless architecture to process large messages with NATS, to get an idea of how to go further.
61+
62+
## Stream
63+
64+
NATS includes the JetStream feature, an add-on to its pub/sub model which implements message streams with persistent messaging capabilities. Distinct from traditional message brokers where messages are deleted once received/consumed, streams retain records ("persistence") of their events. A streaming broker is therefore often likened to a distributed append-only logs file, where every new message is added at the end of the persistent log. Consumers can be thought of as “cursors” in the stream, consuming the stream’s messages according to their filters.
65+
66+
With NATS, you would typically implement a queue as a stream with a single consumer to read from.
67+
68+
## Stream volume
69+
70+
Stream volume is one of the factors affecting the billing of Scaleway NATS. Stream volume is calculated as the number of messages in a stream, multiplied by the message size. Or, the sum of the size of all messages in a stream.
71+
72+
## Stream persistence
73+
74+
Stream persistence is one of the factors affecting the billing of Scaleway NATS. Stream persistence is calculated as the total amount stored in a stream, multiplied by the duration it is stored for.
75+
76+
## Topic-based
77+
78+
The NATS [publish/subscribe model](#publish-subscribe) can be implemented as a content-based or topic-based system. In a topic-based system, messages are published to “topics” or named logical channels.

‎pages/nats/faq.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
meta:
3+
title: NATS FAQ
4+
description: Discover Scaleway NATS, and get answers to all your most commonly asked questions, including information on compatibility with various services, and billing.
5+
content:
6+
h1: NATS FAQ
7+
dates:
8+
validation: 2025-04-01
9+
category: serverless
10+
productIcon: NatsProductIcon
11+
---
12+
13+
## What is Scaleway NATS?
14+
15+
Scaleway NATS is a managed messaging service that leverages the open-source [NATS messaging system](/nats/concepts/#nats-messaging-system) to enable seamless communication between distributed applications and microservices. It allows you to implement your messaging streams without the hassle of managing the infrastructure, scaling or updates.
16+
17+
## Can I configure Scaleway NATS via Terraform/OpenTofu?
18+
19+
Yes, check out our [tutorial](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/guides/mnq_with_nats_terraform_provider) on how to configure Scaleway NATS with the Terraform/OpenTofu [NATS Jetstream provider](https://registry.terraform.io/providers/nats-io/jetstream/latest/docs).
20+
21+
## What is the NATS messaging system?
22+
23+
The **N**eural **A**utonomic **T**ransport **S**ystem, or [NATS](https://nats.io/), is a distributed messaging system, designed to be lightweight and high-performance. It implements both of the following:
24+
- A [publish/subscribe](#publish-subscribe) model, designed for real-time messaging and notifications and event-driven architectures. This is ideal for communication between microservices.
25+
- A [streaming service](#stream) via JetStream, providing persistence so that messages can be re-accessed after sending. The streaming add-on is ideal when applications require message replay or historical data access, such as event sourcing and audit logs.
26+
27+
## How is Scaleway NATS billed?
28+
29+
Billing is based on [stream volume](/nats/concepts/#stream-volume) (the total sum of each message's size going through the stream) and [stream persistence](/nats/concepts/#stream-persistence) (the total amount of data stored * duration).
30+
31+
For full pricing details, see our [dedicated pricing page](https://www.scaleway.com/en/pricing/).

‎pages/nats/how-to/assets/scaleway-nats-create-account.webp‎

18.7 KB
Loading

‎pages/nats/how-to/assets/scaleway-nats-creds.webp‎

22.9 KB
Loading

0 commit comments

Comments
 (0)