feat(nats): add doc for NATS product

menu/navigation.json

@@ -4143,6 +4143,82 @@
             "label": "Jobs",
             "slug": "serverless-jobs"
           },
+          {
+            "items": [
+              {
+                "label": "Overview",
+                "slug": "../nats"
+              },
+              {
+                "label": "Concepts",
+                "slug": "concepts"
+              },
+              {
+                "label": "Quickstart",
+                "slug": "quickstart"
+              },
+              {
+                "label": "FAQ",
+                "slug": "faq"
+              },
+              {
+                "items": [
+                  {
+                    "label": "Create a NATS account",
+                    "slug": "create-account"
+                  },
+                  {
+                    "label": "Create credentials",
+                    "slug": "create-credentials"
+                  },
+                  {
+                    "label": "Manage credentials",
+                    "slug": "manage-credentials"
+                  },
+                  {
+                    "label": "Monitor NATS with Cockpit",
+                    "slug": "monitor-nats-cockpit"
+                  },
+                  {
+                    "label": "Delete a NATS account",
+                    "slug": "delete-account"
+                  }
+                ],
+                "label": "How to",
+                "slug": "how-to"
+              },
+              {
+                "items": [
+                  {
+                    "label": "NATS API Reference",
+                    "slug": "https://www.scaleway.com/en/developers/api/messaging-and-queuing/nats-api/"
+                  },
+                  {
+                    "label": "Using the NATS CLI",
+                    "slug": "nats-cli"
+                  }
+                ],
+                "label": "API/CLI",
+                "slug": "api-cli"
+              },
+              {
+                "items": [
+                  {
+                    "label": "NATS overview",
+                    "slug": "nats-overview"
+                  },
+                  {
+                    "label": "Limitations",
+                    "slug": "limitations"
+                  }
+                ],
+                "label": "Additional Content",
+                "slug": "reference-content"
+              }
+            ],
+            "label": "NATS",
+            "slug": "nats"
+          },
           {
             "items": [
               {

pages/nats/api-cli/index.mdx

@@ -0,0 +1,8 @@
+---
+meta:
+  title: NATS - API/CLI Documentation
+  description: NATS API/CLI Documentation
+content:
+  h1: NATS - API/CLI Documentation
+  paragraph: NATS API/CLI Documentation
+---

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

@@ -0,0 +1,114 @@
+---
+meta:
+  title: Using the NATS CLI
+  description: This page explains how to use the NATS CLI with Scaleway NATS
+content:
+  h1: Using the NATS CLI
+  paragraph: This page explains how to use the NATS CLI with Scaleway NATS
+tags: messaging nats cli
+categories: 
+  - messaging
+dates:
+  validation: 2024-10-18
+  posted: 2023-01-20
+---
+
+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.
+
+Check out the official [NATS CLI documentation](https://docs.nats.io/using-nats/nats-tools/nats_cli/) for installation instructions, examples and more.
+
+<Message type="tip">
+  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).
+</Message>
+
+This page shows you how to get started with some basic actions via the NATS CLI.
+
+<Macro id="requirements" />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+- A Scaleway [NATS account](/nats/how-to/create-account)
+- NATS [credentials](/nats/how-to/create-credentials/) downloaded to your machine
+
+## Installing the NATS CLI
+
+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.
+
+## Define a context
+
+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 will not need to specify your server and credentials with each new request.
+
+### Create a context
+
+The example below creates a context named `scaleway`.
+- Replace `{Scaleway NATS URL}` with the URL of your NATS account (find this in the console on your NATS account **Overview** tab).
+- Replace `{path to your creds file}` with the path to the location where you [downloaded your `.creds` file](/nats/how-to/create-credentials/).
+
+```bash
+nats context save scaleway --server={Scaleway NATS URL} --creds={path to your creds file}
+```
+
+### Use the saved context
+
+Enter the following command to select the `scaleway` context for use:
+
+```
+nats context select scaleway
+```
+
+## Create a stream
+
+To create a [stream](/nats/concepts/#stream), use the command `nats stream add` and follow the CLI guidelines.
+
+<Message type="important">
+  Bear in mind that:
+  - Scaleway NATS does not support in-memory streams: choose `File` as storage backend.
+  - Some [system limits](/nats/reference-content/limitations/) may apply by default.
+  - If you choose a `Retention Policy` other than `Work Queue` you will be billed for the messages stored and retained.
+  - Choosing three replicas has an impact on:
+    - The stream storage limit (as data is replicated 3 times)
+    - The volume of billed messages
+</Message>
+
+You can connect to your stream using code, developer tools or the NATS CLI (for testing purposes only).
+
+## NATS cheat sheet
+
+Use the `nats cheat` command to get a list of all possible commands.
+
+Below we provide a summary of some useful commands.
+
+### General
+
+| Action                              | Command                   |
+| ------------                        | -------------------       |
+| Show a specific section of cheats   | `nats cheat pub`          |
+| List available sections             | `nats cheat --sections`   |
+
+
+### Messaging
+
+| Action                              | Command                                                           |
+| ------------                        | -------------------       |
+| Publish message from STDIN          | `echo "hello world" \| nats pub destination.subject`               |
+| 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`   |
+| Publish message from STDINReceive new messages received with the subject ORDERS.new          | `nats sub ORDERS.new` | 
+| Subscribe to messages, on subject source.subject          |  `nats sub source.subject` |
+
+
+### Queuing/Streaming
+
+| Action                              | Command                                         |
+| ------------                        | -------------------                             |
+| Adding a stream                     | `nats stream add`                               |
+| Viewing a stream                    | `nats stream info STREAMNAME`                   |
+| Removing a stream                   | `nats stream rm STREAMNAME`                     | 
+| Show a list of streams              | `nats stream list`                              |
+| Get message `12345` in stream `ORDERS` | `nats stream get ORDERS 12345`               |
+| Delete message `12345` in stream `ORDERS` | `nats stream rmm ORDERS 12345`            |
+| Purge messages from stream `ORDERS`       | `nats stream purge ORDERS`                | 
+| Mark a stream `ORDERS` as read only       | `nats stream seal ORDERS`                 |
+| Add a consumer                            | `nats consumer add`                       |
+| View a consumer `NEW` of stream `ORDERS`  | `nats consumer info ORDERS NEW`           | 
+| Remove consumer `NEW` from stream `ORDERS`| `nats consumer rm ORDERS NEW`             |
+| 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/concepts.mdx

@@ -0,0 +1,78 @@
+---
+meta:
+  title: NATS - Concepts
+  description: Understand the core concepts of Scaleway NATS. Explore fundamental principles for efficient message handling and service optimization.
+content:
+  h1: NATS - Concepts
+  paragraph: Understand the core concepts of Scaleway NATS. Explore fundamental principles for efficient message handling and service optimization.
+categories:
+  -
+tags: messaging queuing concepts nats
+dates:
+  validation: 2025-04-01
+  posted: 2025-04-01
+---
+
+## Content-based
+
+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.
+
+## Credentials
+
+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 documentation on [how to create credentials](/nats/how-to/create-credentials/) for full details.
+
+## Message broker
+
+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.
+
+## Messaging and Queuing
+
+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](#scaleway-nats), [Queues](/queues/), and [Topics and Events](/topics-and-events/).
+
+## NATS account
+
+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.
+
+## NATS messaging system
+
+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. 
+
+It implements both of the following:
+- A [publish/subscribe](#publish-subscribe) model, designed for real-time messaging and notifications and event-driven architectures. This is ideal for communication between microservices.
+- 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.
+
+## Publish/Subscribe
+
+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. 
+
+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.
+
+## Region
+
+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.
+
+When [creating a NATS account](/nats/how-to/create-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.
+
+## Scaleway NATS
+
+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.
+
+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.
+
+## Stream
+
+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. 
+
+With NATS, you would typically implement a queue as a stream with a single consumer to read from.
+
+## Stream volume
+
+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.
+
+## Stream persistence
+
+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.
+
+## Topic-based
+
+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

@@ -0,0 +1,31 @@
+---
+meta:
+  title: NATS FAQ
+  description: Discover Scaleway NATS, and get answers to all your most commonly asked questions, including information on compatibility with various services, and billing.
+content:
+  h1: NATS FAQ
+dates:
+  validation: 2025-04-01
+category: serverless
+productIcon: NatsProductIcon
+---
+
+## What is Scaleway NATS?
+
+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.
+
+## Can I configure Scaleway NATS via Terraform/OpenTofu?
+
+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).
+
+## What is the NATS messaging system?
+
+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:
+- A [publish/subscribe](#publish-subscribe) model, designed for real-time messaging and notifications and event-driven architectures. This is ideal for communication between microservices.
+- 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.
+
+## How is Scaleway NATS billed?
+
+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).
+
+For full pricing details, see our [dedicated pricing page](https://www.scaleway.com/en/pricing/).

pages/nats/how-to/create-account.mdx

@@ -0,0 +1,43 @@
+---
+meta:
+  title: How to create a NATS account
+  description: Kickstart your journey with Scaleway NAT. Learn how to set up, manage, and optimize your NATS services effortlessly.
+content:
+  h1: How to create a NATS account
+  paragraph: Kickstart your journey with Scaleway NAT. Learn how to set up, manage, and optimize your NATS services effortlessly.
+tags: messaging queuing enable disable nats account
+categories:
+  - serverless 
+dates:
+  validation: 2025-04-01
+  posted: 2025-04-01
+---
+
+To start using a NATS message broker, you must first create a NATS account. This sets a scope for your NATS credentials, messages, queues and stream.
+
+
+<Macro id="requirements" />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
+
+## How to create a NATS account
+
+1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. 
+
+2. Click **Create a NATS account**. The creation wizard displays.
+
+    <Lightbox src="scaleway-nats-create-account.webp" alt="In the Scaleway console, the Create a NATS Account screen displays. The different parts of the page are detailed in the steps below." />
+
+3. Complete the following steps in the wizard:
+
+    - Choose a **region**, which is the geographical location in which your NATS account will be created.
+    - Enter a **name** for your NATS account, or use the auto-generated name suggested for you.
+    - Optional: Use the *Estimated cost** calculator to simulate how messages sent and stored with NATS streams will be billed. Note that simply creating a NATS account does not in itself incur any billing. For more information about NATS billing, see the [FAQ](/nats/faq/#how-is-nats-billed).
+    - Click **Create NATS account** to finish.
+
+    You are directed to the listing of your NATS accounts, where your newly-created NATS account now appears.
+
+    <Message type="tip">
+    You can create more NATS accounts in your pre-selected region if you wish, by clicking on the `+ Create NATS account` button. To create NATS accounts in other regions, repeat the steps above starting from step 2 and selecting the required region.
+    </Message>