2. Click **Add New Service**.
### Step 2: Select a Service and Connector
From the service type dropdown, select **Messaging Services**, then click the **Nats** connector tile.
### Step 3: Add Service Name and Description
* Enter a unique, descriptive **Service Name**. OpenMetadata identifies services by their service name. Enter a name that distinguishes this deployment from other NATS JetStream services you're ingesting metadata from.
* Optional: Enter a **Description** for the service.
* **NATS Servers**: NATS server URLs as comma-separated values. Each entry uses the `nats://host:port` form (the default NATS port is `4222`). Example: `nats://host1:4222,nats://host2:4222`. This is the only required field.
* **Authentication Type**: The method used to authenticate to NATS. Leave empty for anonymous access, or choose one of the following:
* **Username and Password**: Provide a **Username** and **Password** for basic authentication.
* **Token**: Provide a single **Token** for token-based authentication.
* **NKey Seed**: Provide an **NKey Seed** (the private key seed beginning with `S`) for NKey authentication.
* **TLS Configuration** *(Optional)*: TLS/SSL configuration for secure connections. Provide the **CA Certificate** used to validate the server. For mutual TLS, also provide the **SSL Certificate** (client certificate) and **SSL Key** (the private key for that certificate). Both must be supplied together. For more information, see [TLS Configuration](#tls-configuration).
* **Schema KV Bucket** *(Optional)*: Name of the JetStream KV bucket where schemas are stored. Keys must match stream names and values should be Avro JSON, Protobuf (`.proto`), or JSON Schema text. For more information, see [Schema KV Bucket](#schema-kv-bucket).
* **Additional NATS Config** *(Optional)*: Additional NATS client configuration options passed through to the client. See the [NATS Python client documentation](https://nats-io.github.io/nats.py/). The following connection-managed keys are reserved and can't be set here: `servers`, `user`, `password`, `token`, `nkeys_seed`, `nkeys_seed_str`, `tls`, `user_credentials`, `signature_cb`, and `user_jwt_cb`.
#### Test Connection
After you add the credentials, click **Test Connection**, then click **Save**.
The test runs two checks:
* **GetTopics**: Lists JetStream streams to confirm the connection and JetStream access.
* **CheckSchemaKvBucket**: Confirms the configured Schema KV bucket is reachable. This check is optional. When no **Schema KV Bucket** is set, it reports a failure that you can ignore; the overall test still passes.
### Step 5: Configure Ingestion Options
In the **What to Ingest** step, configure filter rules for the topics (JetStream streams) OpenMetadata ingests.
#### How Filter Rules Work
Each rule matches topic names using one of five match types:
* **Contains**: Matches any name containing the value. For example, `orders` matches `prod_orders` and `orders_2024`.
* **Starts with**: Matches names beginning with the value. For example, `prod_` matches `prod_orders` and `prod_events`.
* **Ends with**: Matches names ending with the value. For example, `_raw` matches `events_raw` and `logs_raw`.
* **Is exactly**: Matches the exact name only. For example, `orders` matches only `orders`.
* **Matches regex**: Matches names using a regular expression. For example, `^orders_.*_v\d+$` matches `orders_eu_v1`.
When include and exclusion rules both match a topic, the exclusion rule takes priority.
2. Click the service you have added.
3. Select the **Agents** tab and click **Add Agent** > **Metadata**.
For some services, the dropdown is not available and clicking **Add Agent** takes you directly to the agent configuration page.
4. On the **Configure Ingestion** page, do the following and click **Next**.
* **Name this Ingestion**: Enter a unique recognizable name for this ingestion pipeline.
* **Agent Setup**: Configure the core parameters for this agent. The following fields are available:
| Field | Default | Description |
| - | - | - |
| Generate Sample Data | Off | Option to turn on/off generating sample data during metadata extraction. |
| Mark Deleted Topics | On | Soft-delete topics in OpenMetadata when they are removed from the source. Associated entities like sample data and lineage are also deleted. |
* **Filter Patterns**: Apply include or exclude rules to scope which topics this agent ingests. These follow the same filter options described in **Step 5: Configure Ingestion Options**.
* **Scope & Behaviour**: Control what metadata to include and how to handle deletions. Toggle each option on or off based on your needs:
| Toggle | Default | Description |
| - | - | - |
| Enable Debug Log | Off | Sets the ingestion log level to DEBUG. Useful for troubleshooting. |
| Override Metadata | Off | When on, source values overwrite existing descriptions, tags, owners, and display names in OpenMetadata. When off, OpenMetadata only updates fields that have no existing value. |
5. On the **Schedule Interval** page, set when the agent runs:
* **Schedule**: Choose a preset interval (Hourly, Daily, Weekly, Monthly) or enter a custom cron expression.
* **On-Demand**: No automatic schedule; trigger the agent manually when needed.
6. Click **Add** to deploy the agent.
## TLS Configuration
To establish secure connections between OpenMetadata and NATS, configure the **TLS Configuration** option. Provide the **CA Certificate** used to validate the NATS server's certificate.
If your server requires mutual TLS (mTLS), also provide the **SSL Certificate** (the client certificate) and the **SSL Key** (the private key associated with that certificate). The client certificate and key must always be supplied together. Configuring only one of them results in a connection error.
## Schema KV Bucket
NATS JetStream doesn't have a built-in schema registry. To ingest topic schemas, store them in a JetStream **KV bucket** and set the **Schema KV Bucket** option to that bucket's name.
* Each key in the bucket must match a stream (topic) name.
* Each value should be schema text in Avro JSON, Protobuf (`.proto`), or JSON Schema format.
During ingestion, OpenMetadata looks up the latest value for each stream name in the bucket. It then detects the schema type, parses the fields, and attaches the schema to the corresponding topic. Streams without a matching key in the bucket are still ingested, just without a schema.
## Sample Data
When **Generate Sample Data** is enabled in the ingestion configuration, OpenMetadata fetches up to 10 messages from the last 100 sequences of each stream. The total sample is capped at 1 MB. Only UTF-8 text messages are included. Binary payloads are skipped. Sample data collection also respects the global sample-data storage setting. If sample data storage is disabled server-wide, no sample messages are collected.
## Related