NATS Source
Provided by: "Apache Software Foundation"
Support Level for this Kamelet is: "Stable"
Receives each message published to a subject on a NATS server, or stored in a JetStream stream.
Use it to react to events or commands that services publish on NATS. Use nats-sink to publish them.
Output: the body is the payload, as bytes, unchanged. The CamelNatsSubject header is the subject, and the NATS headers of the message become headers too.
Good to know: without JetStream, it receives only the messages published while it is connected. With jetstreamEnabled, it creates the stream jetstreamName for the subject when it does not exist. Each time it starts it reads the stream from the beginning, so messages already read are received again, unless durableName is set: then it carries on after the last message it acknowledged. A message is acknowledged once it has been processed. A message that fails is delivered again 5 seconds later, with no end unless maxDeliver is set. When an integration with a durableName stops abruptly, the messages it had not finished come back after 30 seconds, so the one in progress can be received twice. When several copies of the integration run, each copy receives every message, unless they share a queueName (without JetStream) or a durableName (with JetStream): then each message goes to only one of them. It connects with TLS when secure is true. The certificate of the server is checked against the certificate authorities that Java trusts. To trust a private one with Camel JBang or Camel Main, set the application properties camel.ssl.enabled=true, camel.ssl.trustStore, camel.ssl.trustStorePassword and camel.component.nats.useGlobalSslContextParameters=true: that trust store then replaces the one of Java for every NATS connection of the application that has secure set. The integration fails to start when no server can be reached, or when the server refuses the login.
Configuration Options
The following table summarizes the configuration options available for the nats-source Kamelet:
| Property | Name | Description | Type | Default | Example |
|---|---|---|---|---|---|
Servers | Required The addresses of one or more NATS servers, as | string | nats://localhost:4222 | ||
Subject | Required The NATS subject to receive the messages from. | string | orders.created | ||
Acknowledge Policy | How the messages are acknowledged to JetStream, so that it does not deliver them again. Enum values: * Explicit * All * None | string | |||
Credentials File | A NATS credentials file ( | string | file:/etc/nats/user.creds | ||
Durable Consumer Name | The name of a durable JetStream consumer: the server keeps it, and the position of the integration in the stream, when the integration stops. After a restart, it carries on with the first message that was not acknowledged, instead of reading the stream from the beginning. Copies of the integration with the same | string | order-processor | ||
JetStream Async | Not used by the source, which receives the messages the same way whether it is true or false. | boolean | true | ||
JetStream Enabled | If true, the messages are read from the JetStream stream | boolean | false | ||
JetStream Stream Name | The name of the JetStream stream that stores the messages. Only used when | string | ORDERS | ||
Maximum Deliveries | How many times at most a message is delivered, the first time included. A message that fails is delivered again 5 seconds later, until it has been delivered this many times; it then stays in the stream but is not delivered again. When not set, a message that fails is delivered again with no end. Only used when | integer | 5 | ||
Queue Group | The name of a NATS queue group to join. The subscribers of | string | order-workers | ||
Secure (TLS) | If true, it connects with TLS, which a server with TLS in its configuration requires; without it, such a server refuses the connection with | boolean |
Dependencies
At runtime, the nats-source Kamelet relies upon the presence of the following dependencies:
-
camel:jackson3
-
camel:nats
-
camel:kamelet
Camel JBang usage
Prerequisites
-
You’ve installed JBang.
-
You have executed the following command:
jbang app install camel@apache/camel Supposing you have a file named route.yaml with this content:
- route:
from:
uri: "kamelet:nats-source"
parameters:
.
.
.
steps:
- to:
uri: "kamelet:log-sink" You can now run it directly through the following command
camel run route.yaml NATS Source Kamelet Description
Login
For a server that needs a user and password, put them in the address in servers, as nats://user:password@host:4222, or put a token there, as nats://token@host:4222.
For a server with decentralized authentication, such as Synadia Cloud, log in with a NATS credentials file (.creds), which holds a user JWT and the NKey seed of the user. Set its location in credentialsFilePath, as file: followed by the path of the file. The nsc generate creds command makes one.
TLS with a Private Certificate Authority
With secure: true the Kamelet connects with TLS, which a server with TLS in its configuration requires, and checks the certificate of the server against the certificate authorities that Java trusts. When the server has a certificate from a private or self-signed authority, put the certificate of that authority in a trust store file (JKS or PKCS12), and set it in the application properties, as the global TLS settings of Camel. With Camel JBang or Camel Main, in application.properties:
camel.ssl.enabled=true
camel.ssl.trustStore=file:/etc/nats/truststore.p12
camel.ssl.trustStorePassword=changeit
camel.component.nats.useGlobalSslContextParameters=true That trust store then replaces the one of Java for every NATS connection of the application that has secure set. An address that starts with tls:// also connects with TLS, but it uses that trust store only when secure is true.
Running several copies: queue groups
Each copy of the integration receives every message of the subject. To share the messages instead, so that each message is processed by only one copy, give every copy the same queueName. NATS then delivers each message to one member of the queue group. This works only without JetStream: with jetstreamEnabled, give every copy the same durableName instead (see below).
Output format
The body is the NATS payload, unchanged, as bytes; it is not turned into JSON. The CamelNatsSubject header is the subject, and the NATS headers of the message become headers too.
JetStream
With jetstreamEnabled set to true, the Kamelet reads from the JetStream stream jetstreamName, and creates it for the subject in topic when it does not exist. Without durableName, each time it starts it reads the stream from the beginning, so the messages it already read are received again.
Durable consumer: carry on after a restart
With durableName, the server keeps a durable consumer for the Kamelet, and remembers which messages it acknowledged. After a restart, the Kamelet carries on with the first message that was not acknowledged: no message is lost and none is received again. A new durable consumer starts at the beginning of the stream.
-
A message is acknowledged once the integration has processed it. A message that fails is delivered again 5 seconds later. Set
maxDeliverto stop after that many deliveries; the message then stays in the stream. -
When the integration stops abruptly, the messages it had not finished come back after 30 seconds, so the message in progress can be received twice.
-
Copies of the integration with the same
durableNameshare the messages: each message goes to only one of them. -
ackPolicysays how the messages are acknowledged:ackPolicyA message that fails Explicit(when not set)is delivered again.
Allis delivered again, until a later message succeeds: acknowledging a message also acknowledges the earlier ones.
Noneis not delivered again: JetStream counts a message as done when it sends it.
On the server, the consumer is named after durableName with -durable added. It stays there when the integration is removed, and its ackPolicy and maxDeliver cannot be changed afterwards: the integration then logs Existing consumer cannot be modified and receives nothing. Delete it with the nats command line tool first:
nats consumer rm ORDERS order-processor-durable Usage example
- route:
from:
uri: "kamelet:nats-source"
parameters:
servers: "nats://localhost:4222"
topic: "orders.created"
steps:
- to:
uri: "kamelet:log-sink" Example with TLS, a Credentials File and a Queue Group
- route:
from:
uri: "kamelet:nats-source"
parameters:
servers: "tls://nats.example.com:4222"
topic: "orders.created"
secure: true
credentialsFilePath: "file:/etc/nats/app-user.creds"
queueName: "order-workers"
steps:
- to:
uri: "kamelet:log-sink"