diff --git a/menu/navigation.json b/menu/navigation.json index c53a923632..ff0ac4f441 100644 --- a/menu/navigation.json +++ b/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 NATS credentials", + "slug": "create-credentials" + }, + { + "label": "Manage NATS 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": [ { diff --git a/pages/nats/api-cli/index.mdx b/pages/nats/api-cli/index.mdx new file mode 100644 index 0000000000..cf24e2b0b3 --- /dev/null +++ b/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 +--- diff --git a/pages/nats/api-cli/nats-cli.mdx b/pages/nats/api-cli/nats-cli.mdx new file mode 100644 index 0000000000..dd0eec375c --- /dev/null +++ b/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. + + + 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). + + +This page shows you how to get started with some basic actions via the NATS CLI. + + + +- 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 operating system. + +## 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. + + + 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 + + +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` | diff --git a/pages/nats/assets/scaleway-nats-create-account.webp b/pages/nats/assets/scaleway-nats-create-account.webp new file mode 100644 index 0000000000..12653712c9 Binary files /dev/null and b/pages/nats/assets/scaleway-nats-create-account.webp differ diff --git a/pages/nats/assets/scaleway-nats-creds.webp b/pages/nats/assets/scaleway-nats-creds.webp new file mode 100644 index 0000000000..eea32747f4 Binary files /dev/null and b/pages/nats/assets/scaleway-nats-creds.webp differ diff --git a/pages/nats/assets/scaleway-nats-overview.webp b/pages/nats/assets/scaleway-nats-overview.webp new file mode 100644 index 0000000000..c2240019b0 Binary files /dev/null and b/pages/nats/assets/scaleway-nats-overview.webp differ diff --git a/pages/nats/concepts.mdx b/pages/nats/concepts.mdx new file mode 100644 index 0000000000..53d7110a2e --- /dev/null +++ b/pages/nats/concepts.mdx @@ -0,0 +1,70 @@ +--- +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 +--- + +## 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. + +## Message volume + +Message volume is one of the factors affecting the billing of Scaleway NATS. Message volume is calculated as the number of messages sent to/received by NATS, multiplied by the message size. Or, the sum of the size of all messages passing through NATS. + +## Message persistence + +Message persistence is one of the factors affecting the billing of Scaleway NATS. Message persistence is calculated as the total amount stored in NATS, multiplied by the duration it is stored for. + +## 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. + +The publish/subscribe model relies on a [message broker](#message-broker) to relay messages between publishers and subscribers. With NATS, subscribers can select which messages to receive based on **subject**. + +## 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. \ No newline at end of file diff --git a/pages/nats/faq.mdx b/pages/nats/faq.mdx new file mode 100644 index 0000000000..f1bc0cf8ea --- /dev/null +++ b/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 [message volume](/nats/concepts/#message-volume) (the total sum of each message's size going through NATS) and [message persistence](/nats/concepts/#message-persistence) (the total amount of data stored * duration). + +For full pricing details, see our [dedicated pricing page](https://www.scaleway.com/en/pricing/). \ No newline at end of file diff --git a/pages/nats/how-to/assets/scaleway-nats-create-account.webp b/pages/nats/how-to/assets/scaleway-nats-create-account.webp new file mode 100644 index 0000000000..12653712c9 Binary files /dev/null and b/pages/nats/how-to/assets/scaleway-nats-create-account.webp differ diff --git a/pages/nats/how-to/assets/scaleway-nats-creds.webp b/pages/nats/how-to/assets/scaleway-nats-creds.webp new file mode 100644 index 0000000000..eea32747f4 Binary files /dev/null and b/pages/nats/how-to/assets/scaleway-nats-creds.webp differ diff --git a/pages/nats/how-to/assets/scaleway-nats-overview.webp b/pages/nats/how-to/assets/scaleway-nats-overview.webp new file mode 100644 index 0000000000..c2240019b0 Binary files /dev/null and b/pages/nats/how-to/assets/scaleway-nats-overview.webp differ diff --git a/pages/nats/how-to/create-account.mdx b/pages/nats/how-to/create-account.mdx new file mode 100644 index 0000000000..3caa49a886 --- /dev/null +++ b/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. + + + + +- 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. + + + +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. + + + 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. + \ No newline at end of file diff --git a/pages/nats/how-to/create-credentials.mdx b/pages/nats/how-to/create-credentials.mdx new file mode 100644 index 0000000000..1de0418eb0 --- /dev/null +++ b/pages/nats/how-to/create-credentials.mdx @@ -0,0 +1,52 @@ +--- +meta: + title: How to create credentials for NATS + description: Learn how to create credentials for Scaleway NATS. Securely manage access, and ensure seamless integration with this step-by-step guide. +content: + h1: How to create credentials for NATS + paragraph: Learn how to create credentials for Scaleway NATS. Securely manage access, and ensure seamless integration with this step-by-step guide. +tags: credentials messaging queuing key token nats +categories: + - serverless +dates: + validation: 2025-04-01 + posted: 2025-04-01 +--- + +This page shows how to create [credentials](/nats/concepts/#credentials) for Scaleway NATS (previously part of the Messaging and Queuing product). Credentials give their bearer (e.g. services and platforms) access to your service. + +You can create multiple sets of credentials for each of your NATS accounts. + + + +- 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 [NATS account](/nats/how-to/create-account/) + +## How to create credentials for a NATS account + +Credentials for NATS accounts are not granular: they necessarily give full read and write access. The bearer of these credentials can publish and receive messages, as well as manage topics and streams, for this account. + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Use the drop-down menu to select the [region](/nats/concepts/#region) of the NATS account for which you want to create credentials. The list of your NATS accounts in the pre-selected region displays. + +3. Click the NATS account you want to generate credentials for. The account's **Overview** page displays. + + + +4. In the **Credentials** panel, click **Generate credentials**. A pop-up displays. + +5. Enter a name for these credentials, and click **Generate credentials**. + + The credentials are created and a button displays prompting you to download them in a `.creds` file. + + + + + The generated credentials are displayed only once. Make sure to download and safely store them before closing the window. + + +6. Click **Download** and save the file, before closing the window. + + You are returned to your NATs account's overview page. The name of your newly-generated credentials and their access level is displayed in the **Credentials** panel. \ No newline at end of file diff --git a/pages/nats/how-to/delete-account.mdx b/pages/nats/how-to/delete-account.mdx new file mode 100644 index 0000000000..475f145476 --- /dev/null +++ b/pages/nats/how-to/delete-account.mdx @@ -0,0 +1,44 @@ +--- +meta: + title: How to delete a NATS account + description: Delete a Scaleway NATS account effectively. Safely remove resources with this straightforward guide. +content: + h1: How to delete a NATS account + paragraph: Delete a Scaleway NATS account effectively. Safely remove resources with this straightforward guide. +dates: + validation: 2025-04-01 + posted: 2025-04-01 +tags: delete messaging queuing messaging-and-queuing service delete nats-account +categories: + - serverless +--- + +This page shows how to delete a Scaleway **NATS**, account. + + + + +- 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 +- At least one [NATS account](/nats/how-to/create-account/) + +## How to delete a NATS account + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Use the drop-down menu to select the [region](/nats/concepts/#region) containing the NATS account you want to delete. + +3. Click the NATS account you want to delete. + +4. In the bottom panel, click the **Delete NATS account** button. + + A pop-up displays, reminding you that the action is irreversible, and any associated queued messages and credentials will be deleted. + +5. Type `DELETE` and click **Delete NATS account** to confirm. + + +Repeat the process above for each NATS account you want to delete. Remember to use the region drop-down as appropriate to access the different NATS accounts you hold in different regions. + + + + diff --git a/pages/nats/how-to/index.mdx b/pages/nats/how-to/index.mdx new file mode 100644 index 0000000000..7bff246f34 --- /dev/null +++ b/pages/nats/how-to/index.mdx @@ -0,0 +1,8 @@ +--- +meta: + title: NATS - How Tos + description: NATS How Tos +content: + h1: NATS- How Tos + paragraph: NATS How Tos +--- diff --git a/pages/nats/how-to/manage-credentials.mdx b/pages/nats/how-to/manage-credentials.mdx new file mode 100644 index 0000000000..9a6c396710 --- /dev/null +++ b/pages/nats/how-to/manage-credentials.mdx @@ -0,0 +1,42 @@ +--- +meta: + title: How to manage credentials for Scaleway NATS + description: Master managing credentials for Scaleway NATS. Follow this guide to securely update, rotate, and control access to your messaging services. +content: + h1: How to manage credentials for Scaleway NATS + paragraph: Master managing credentials for Scaleway NATS. Follow this guide to securely update, rotate, and control access to your messaging services. +dates: + validation: 2025-04-01 + posted: 2025-04-01 +tags: manage credentials nats permissions update revoke +categories: + - serverless +--- + +Credentials give their bearer (e.g. services and platforms) access to your service. + +This page shows how to manage [credentials](/nats/concepts/#credentials) for Scaleway NATS (previously part of the Messaging and Queuing product). + +Note that the only management action available for NATS credentials is revocation. Once credentials are revoked, any user trying to use the credentials to connect to the service will be denied. + + + +- 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 +- Valid [NATS credentials](/nats/how-to/create-credentials/) + +## How to revoke NATS credentials + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Select the NATS account you want to revoke credentials for. + +3. In the **Credentials** panel, click the button next to the credentials you want to revoke. + + A pop-up displays, warning you that this action is irreversible and the key will no longer be able to access your service. + +4. Click **Revoke credentials**. + + The credentials are revoked and you are returned to the NATS account's **Overview** page. + + diff --git a/pages/nats/how-to/monitor-nats-cockpit.mdx b/pages/nats/how-to/monitor-nats-cockpit.mdx new file mode 100644 index 0000000000..8b71c000c2 --- /dev/null +++ b/pages/nats/how-to/monitor-nats-cockpit.mdx @@ -0,0 +1,45 @@ +--- +meta: + title: How to monitor NATS with Scaleway Cockpit + description: Monitor your NATS service with Scaleway Cockpit. This guide helps you track performance to manage your messaging services efficiently. +content: + h1: How to monitor NATS with Scaleway Cockpit + paragraph: Monitor your NATS service with Scaleway Cockpit. This guide helps you track performance to manage your messaging services efficiently. +tags: messaging queuing nats cockpit metrics observability +categories: + - serverless +dates: + validation: 2025-04-01 + posted: 2025-04-01 +--- + +You can view metrics for your NATS services via [Scaleway Cockpit](/cockpit/quickstart/). This allows you to monitor your queues/streams and messages at a glance. There are two steps to complete to view your metrics for the first time with Cockpit: + +1. Generate your Grafana credentials +2. Access the product's metrics dashboard + +These steps are described below. + + + +- 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 +- At least one [NATS account](/nats/how-to/create-account/) + +## How to generate Grafana credentials + +To view your metrics with Cockpit, you will use a Grafana dashboard which is accessible from the Scaleway console. First, you must create a user and their associated credentials (a username and password) for Grafana. This can be done directly from the Scaleway console, [by following this procedure](/cockpit/how-to/retrieve-grafana-credentials/). + +## How to access your NATS dashboard and view your metrics + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Click the **Metrics** tab. + +3. Click **Open Grafana metrics dashboard**. + +4. Enter your Grafana username and password to log in. + + You are directed to the NATS dashboard, where you can view all your metrics. + + diff --git a/pages/nats/index.mdx b/pages/nats/index.mdx new file mode 100644 index 0000000000..6bee88e879 --- /dev/null +++ b/pages/nats/index.mdx @@ -0,0 +1,73 @@ +--- +meta: + title: NATS Documentation + description: Explore Scaleway NATS. Simplify your microservice workflows with scalable, reliable, and cost-effective message handling solutions. +--- + + + +## Getting Started + + + + + + + + + +## Tutorials + + + + + + + + +## Changelog + + \ No newline at end of file diff --git a/pages/nats/quickstart.mdx b/pages/nats/quickstart.mdx new file mode 100644 index 0000000000..eae0e678de --- /dev/null +++ b/pages/nats/quickstart.mdx @@ -0,0 +1,90 @@ +--- +meta: + title: NATS - Quickstart + description: Get started with Scaleway NATS. This quickstart guide helps you easily set up and manage scalable messaging solutions in minutes. +content: + h1: NATS - Quickstart + paragraph: Get started with Scaleway NATS. This quickstart guide helps you easily set up and manage scalable messaging solutions in minutes. +dates: + validation: 2025-04-01 + posted: 2025-04-01 +tags: messaging queuing queueing quickstart messaging-and-queuing nats message-broker queues topics messages streams jetstream +categories: + - serverless +--- + +Scaleway NATS is a managed message broker tool that allows you to transfer messages between different microservices and platforms. This enables them to "talk" to each other effectively even if they are not otherwise compatible. This enables and simplifies microservices application development and allows you to build highly scalable, reliable, distributed applications. + + +Scaleway NATS was previously part of our Messaging and Queuing product, and has now become a product in its own right. + + + + +- 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 + +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. + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Click **Create a NATS account**. The creation wizard displays. + + + +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-scaleway-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. + +## How to create NATS credentials + +Credentials for NATS accounts are not granular: they necessarily give full read and write access. The bearer of these credentials can publish and receive messages, as well as manage topics and streams, for this account. + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Use the drop-down menu to select the [region](/nats/concepts/#region) of the NATS account for which you want to create credentials. The list of your NATS accounts in the pre-selected region displays. + +3. Click the NATS account you want to generate credentials for. The account's **Overview** page displays. + + + +4. In the **Credentials** panel, click **Generate credentials**. A pop-up displays. + +5. Enter a name for these credentials, and click **Generate credentials**. + + The credentials are created and a button displays prompting you to download them in a `.creds` file. + + + + + The generated credentials are displayed only once. Make sure to download and safely store them before closing the window. + + +6. Click **Download** and save the file, before closing the window. + + You are returned to your NATs account's overview page. The name of your newly-generated credentials and their access level is displayed in the **Credentials** panel. + +## How to create and manage queues, messages and streams + +All further actions related to publishing, processing and managing messages, subjects, queues and streams can be done via a supported CLI or SDK. See our documentation on [NATS CLI and SDKs](/nats/reference-content/nats-overview/#further-actions-nats-cli-and-nats-sdk) for more information. You can also check out our tutorial on [creating a serverless architecture for handling large messages](/tutorials/large-messages/) with Scaleway NATS. + +## How to delete a NATS account + +1. Click **NATS** in the **Serverless** section of the Scaleway console side menu. + +2. Use the drop-down menu to select the [region](/nats/concepts/#region) containing the NATS account you want to delete. + +3. Click the NATS account you want to delete. + +4. In the bottom panel, click the **Delete NATS account** button. + + A pop-up displays, reminding you that the action is irreversible, and any associated queued messages and credentials will be deleted. + +5. Type `DELETE` and click **Delete NATS account** to confirm. \ No newline at end of file diff --git a/pages/nats/reference-content/index.mdx b/pages/nats/reference-content/index.mdx new file mode 100644 index 0000000000..dacce5bb31 --- /dev/null +++ b/pages/nats/reference-content/index.mdx @@ -0,0 +1,8 @@ +--- +meta: + title: NATS - Additional content + description: NATS additional content +content: + h1: NATS - Additional content + paragraph: NATS additional content +--- diff --git a/pages/nats/reference-content/limitations.mdx b/pages/nats/reference-content/limitations.mdx new file mode 100644 index 0000000000..0ce68a8d6d --- /dev/null +++ b/pages/nats/reference-content/limitations.mdx @@ -0,0 +1,22 @@ +--- +meta: + title: NATS Limitations + description: Learn about the current limitations of Scaleway NATS +content: + h1: NATS Limitations + paragraph: Learn about the current limitations of Scaleway NATS +tags: messaging limitations space size storage payload max-streams max-consumers max-subscribers max-topics visibility-timeout +dates: + validation: 2025-04-01 + posted: 2025-04-01 +categories: + - serverless +--- + +## Usage limits + +For the usage limits that apply when using Scaleway NATS, see the dedicated sections on our [Organization quotas](/organizations-and-projects/additional-content/organization-quotas/) page. Limits (quotas) apply to, for example, the maximum number of queues, streams, topics and consumers/subscribers, as well as to message retention duration and storage. + +## VPC + +NATS is not currently compatible with [Scaleway VPC](/vpc/quickstart/). diff --git a/pages/nats/reference-content/nats-overview.mdx b/pages/nats/reference-content/nats-overview.mdx new file mode 100644 index 0000000000..c3de3c6bf4 --- /dev/null +++ b/pages/nats/reference-content/nats-overview.mdx @@ -0,0 +1,81 @@ +--- +meta: + title: NATS Overview + description: Learn about the NATS messaging system +content: + h1: NATS Overview + paragraph: Learn about the NATS messaging system +tags: nats overview neural-autonomic-transport-system publish-subscribe jetstream streaming messaging deno +categories: + - serverless +dates: + validation: 2024-10-18 + posted: 2023-01-04 +--- + +## What is NATS? + +NATS (**N**eural **A**utonomic **T**ransport **S**ystem) is a messaging system that aims to be simple to use, scalable and provide high performance. It implements a [publish/subscribe](/nats/concepts/#publishsubscribe) model as well as adding a [streaming](/nats/concepts/#stream) service via [JetStream](https://docs.nats.io/nats-concepts/jetstream). A stream is a persistent, time-ordered list of messages which can be read sequentially by consumers. A consumer can be thought of as a "cursor" in the stream, consuming the stream's messages according to their "subject filter" or "replay policy". With NATS, you would typically implement a queue as a stream with a single consumer to read from. + +NATS is a [Cloud Native Computing Foundation](https://www.cncf.io/) project supported by a strong community, and can also be integrated in a Kubernetes cluster. + +## Scaleway NATS + +Scaleway NATS is a managed messaging service that enable seamless communication between distributed applications, which leverages the NATS protocol. + +## NATS accounts + +You can easily create a NATS account from the [Scaleway console](https://console.scaleway.com/), via the [Scaleway API](https://www.scaleway.com/en/developers/api/messaging-and-queuing/nats-api/) or via [Terraform/OpenTofu](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/guides/mnq_with_nats_terraform_provider). + +## NATS credentials + +When you create your NATS account, you next need to [create credentials](/nats/how-to/create-credentials/). On the NATS side, these credentials are the equivalent of a 'user'. We use the most secure connection type offered by NATS: [NKeys](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/nkey_auth). NKeys are a public-key signature system based on [Ed25519](https://ed25519.cr.yp.to/). + +Your credentials are provided in the form of a downloadable `.creds` file. Each set of credentials gives you full access to your NATS account, but does not enable you to generate new users with specific rights or fine-grained permissions. + +## Further actions: NATS CLI & NATS SDK + +All further actions related to publishing, processing and managing messages, subjects and streams can be done via one of the tools described below. + +Note that the Scaleway NATS server is configured with TLS, and as such will require all clients to connect with TLS. In the case of the NATS SDK however, the SDK abstracts this and handles the TLS connection itself. + +### NATS CLI + +The [NATS CLI](https://docs.nats.io/using-nats/nats-tools/nats_cli) is a great tool for administrating or testing your subjects and streams. See our [dedicated documentation](/nats/api-cli/nats-cli/) for help getting started with the NATS CLI. + +### NATS SDK + +NATS has a wide range of language compatibility: + +| Language | Links | +|:----------:|:----------------------------:| +| Golang | [nats.go](https://github.com/nats-io/nats.go), [godoc](http://godoc.org/github.com/nats-io/nats.go) | +| Java | [nats.java](https://github.com/nats-io/nats.java), [javadoc](https://javadoc.io/doc/io.nats/jnats), [examples](https://github.com/nats-io/java-nats-examples) | +| C# | [nats.net](https://github.com/nats-io/nats.net), [doxygen](http://nats-io.github.io/nats.net/), [package](https://www.nuget.org/packages/NATS.Client/0.14.1) | +| JavaScript | [Node.js](https://github.com/nats-io/nats.js/#readme), [deno](https://github.com/nats-io/nats.deno/blob/main/README.md), [WebSocket](https://github.com/nats-io/nats.ws/#readme) | +| Python | [nats.py](https://github.com/nats-io/nats.py), [doc](https://nats-io.github.io/nats.py/) | +| Ruby | [nats-pure.rb](https://github.com/nats-io/nats-pure.rb), [yard](https://www.rubydoc.info/gems/nats) | +| C | [nats.c](https://github.com/nats-io/nats.c), [doc](http://nats-io.github.io/nats.c) | +| Rust | [nats.rs](https://github.com/nats-io/nats.rs), [doc](https://docs.rs/nats) | +| Elixir | [nats.ex](https://github.com/nats-io/nats.ex), [doc](https://hex.pm/packages/gnat) | +| Zig | [nats.zig](https://github.com/nats-io/nats.zig) | +| PHP | [phpnats](https://github.com/repejota/phpnats) [nats.php](https://github.com/basis-company/nats.php) | + +Further community NATS SDKs, e.g. SwiftyNats, Kotlin and Crystal, can be found [here](https://docs.nats.io/using-nats/developer). + +The following documents may help you get started using the above SDKs: +- [Authentication with SDK](https://docs.nats.io/using-nats/developer/connecting/creds) +- [JavaScript: Using Jetstream](https://github.com/nats-io/nats.deno/blob/main/jetstream.md/#jetstream-client) +- [Python: Using Jetstream](https://github.com/nats-io/nats.py#jetstream) +- [Go: Using Jetstream](https://github.com/nats-io/nats.go#jetstream-basic-usage) + +The main difference you will find between the standard NATS documentation and Scaleway NATS is that we require you to provide a specific NATS URL and credentials to access the service. Refer to our [developers documentation](https://www.scaleway.com/en/developers/api/messaging-and-queuing/nats-api/) for further information. + +## NATS resources + +- [Official NATS Documentation: What is NATS?](https://docs.nats.io/nats-concepts/what-is-nats) +- [Create a serverless architecture for handling large messages using Scaleway's NATS, Serverless Functions, and Object Storage](/tutorials/large-messages/) +- [Publish/Subscribe in pure NATS (no message retention)](https://docs.nats.io/nats-concepts/core-nats/pubsub/pubsub_walkthrough) +- [Introduction to JetStream](https://docs.nats.io/nats-concepts/jetstream) +- [Learn NATS by Example](https://natsbyexample.com/) +- [How to use Scaleway NATS with the Terraform/OpenTofu NATS Jetstream provider](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/guides/mnq_with_nats_terraform_provider) \ No newline at end of file