@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/plugins/azure-schema-registry/02-plugin-configuration.md

@@ -0,0 +1,375 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Azure Schema Registry plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Azure Schema Registry plugin
+---
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog Azure Schema Registry plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+:::info Authentication
+The plugin uses Azure's REST API with Bearer token authentication. You must set the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable.
+
+<details>
+<summary>Example .env file</summary>
+
+```bash
+# EventCatalog license key
+export EVENTCATALOG_LICENSE_KEY_AZURE_SCHEMA_REGISTRY=your-license-key
+
+# Azure Schema Registry access token
+export AZURE_SCHEMA_REGISTRY_TOKEN=your-azure-access-token
+```
+
+Get the token using Azure CLI:
+```bash
+az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv
+```
+
+</details>
+
+:::
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schemaRegistryUrl` | `string` | Yes | The URL of your Azure Schema Registry (e.g., `https://your-namespace.servicebus.windows.net`). You can find this in the Azure Portal under your Event Hubs namespace. |
+| `services` | `array` | Yes | List of services and their schema mappings. **Note:** Unlike Confluent, Azure Schema Registry doesn't provide an API to list all schemas, so you must explicitly define which schemas to fetch. |
+
+## Optional Configuration Options
+
+### Services
+
+You can assign schemas to services (producers/consumers) in your architecture.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `services` | `array` | - | List of services to document with their schemas. |
+| `services[].id` | `string` | - | EventCatalog ID for the service (e.g., `orders-service`). |
+| `services[].name` | `string` | `services[].id` | Display name for the service (e.g., `Orders Service`). |
+| `services[].version` | `string` | - | Version of the service (e.g., `1.0.0`). |
+| `services[].sends` | `array` | - | Array of schema filters for messages this service sends. |
+| `services[].receives` | `array` | - | Array of schema filters for messages this service receives. |
+| `services[].writesTo` | `array[{id: string, version?: string}]` | - | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service writes to. |
+| `services[].readsFrom` | `array[{id: string, version?: string}]` | - | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service reads from. |
+
+### Schema Filters (sends/receives)
+
+Each schema in `sends` and `receives` arrays can have the following properties:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | **Required** | The schema name in the Azure Schema Registry. |
+| `schemaGroup` | `string` | **Required** | The schema group name in the registry. |
+| `name` | `string` | `id` | Custom display name for the schema in EventCatalog. Useful for making technical schema names more user-friendly. |
+| `messageType` | `'event' \| 'command' \| 'query'` | `'event'` | The type of message this schema represents. |
+| `schemaRegistryUrl` | `string` | Global `schemaRegistryUrl` | Override the registry URL for this specific schema. Useful when schemas are in different Azure Schema Registries. |
+
+### Domains
+
+You can define and assign domains to organize your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain` | `object` | - | Optional domain configuration to group services. |
+| `domain.id` | `string` | - | EventCatalog ID for the domain (e.g., `orders-domain`). |
+| `domain.name` | `string` | - | Display name of the domain (e.g., `Orders Domain`). |
+| `domain.version` | `string` | - | Version of the domain (e.g., `1.0.0`). |
+
+### License
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `licenseKey` | `string` | From env var | EventCatalog license key. Can also be set via `EVENTCATALOG_LICENSE_KEY_AZURE_SCHEMA_REGISTRY` environment variable. |
+
+## Example Configurations
+
+### Basic Configuration
+
+Import schemas from Azure Schema Registry and assign them to services:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          name: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+            },
+          ],
+          receives: [
+            {
+              id: 'payment-received',
+              schemaGroup: 'com.example.payments',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Custom Schema Names
+
+Provide user-friendly display names for your schemas:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'app.orders.created.v1',
+              schemaGroup: 'com.example.orders',
+              name: 'Order Created Event', // Custom friendly name
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Message Types (Events, Commands, Queries)
+
+Document different message types to better represent your architecture:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              name: 'Order Created Event',
+              messageType: 'event', // Event message
+            },
+            {
+              id: 'create-order',
+              schemaGroup: 'com.example.orders',
+              name: 'Create Order Command',
+              messageType: 'command', // Command message
+            },
+          ],
+          receives: [
+            {
+              id: 'get-order',
+              schemaGroup: 'com.example.orders',
+              name: 'Get Order Query',
+              messageType: 'query', // Query message
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Multiple Schema Registries
+
+Fetch schemas from multiple Azure Schema Registries in one configuration:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      // Default registry URL
+      schemaRegistryUrl: 'https://primary-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              // Uses default schemaRegistryUrl
+            },
+            {
+              id: 'order-shipped',
+              schemaGroup: 'com.example.shipping',
+              name: 'Order Shipped Event',
+              // Override to fetch from different registry
+              schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### With Domains
+
+Organize your services into domains:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      services: [
+        {
+          id: 'orders-service',
+          name: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            { id: 'order-created', schemaGroup: 'com.example.orders' },
+          ],
+        },
+        {
+          id: 'inventory-service',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          receives: [
+            { id: 'order-created', schemaGroup: 'com.example.orders' },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Multiple Domains
+
+You can configure the plugin multiple times to document different domains:
+
+```js title="eventcatalog.config.js"
+generators: [
+  // Orders Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            { id: 'order-created', schemaGroup: 'com.example.orders' },
+          ],
+        },
+      ],
+    },
+  ],
+  // Payments Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'payments-domain',
+        name: 'Payments Domain',
+        version: '1.0.0',
+      },
+      services: [
+        {
+          id: 'payments-service',
+          version: '1.0.0',
+          sends: [
+            { id: 'payment-received', schemaGroup: 'com.example.payments' },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+## Schema Group Naming
+
+Azure Schema Registry organizes schemas into schema groups. When configuring the plugin, make sure to use the exact schema group name as it appears in your Azure Schema Registry.
+
+Common schema group naming patterns:
+- Namespace style: `com.example.orders`, `com.example.payments`
+- Application style: `myapp-orders`, `myapp-inventory`
+- Environment-based: `production.orders`, `staging.orders`
+
+You can find your schema groups in the Azure Portal under your Event Hubs namespace > Schema Registry.
+
+## Supported Schema Formats
+
+The plugin supports the following schema formats from Azure Schema Registry:
+
+- **Avro** - Schemas with `.avsc` file extension
+- **JSON Schema** - Schemas with `.json` file extension
+
+The plugin automatically detects the schema format and generates the appropriate documentation in EventCatalog.
+
+## Troubleshooting
+
+### Authentication Issues
+
+If you encounter authentication errors:
+
+1. **Token not set**: Ensure `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable is set
+2. **Token expired**: Azure access tokens expire after 1 hour. Re-run `az account get-access-token` to get a fresh token
+3. **Invalid token**: Verify you're using the correct resource (`https://eventhubs.azure.net`) when obtaining the token
+4. **Permission errors**: Ensure your Azure user/service principal has "Azure Event Hubs Data Receiver" or "Azure Event Hubs Data Owner" role on the Event Hubs namespace
+
+### Schema Not Found
+
+If the plugin can't find a schema:
+
+1. Verify the `schemaGroup` and `id` values match exactly what's in Azure Schema Registry
+2. Check that your authenticated user/identity has read permissions on the schema registry
+3. Ensure the schema exists in the specified schema group
+
+### License Key Issues
+
+If you have problems with your license key:
+
+1. Ensure `https://api.eventcatalog.cloud` is not blocked by your firewall
+2. Verify your license key is correctly set in the `.env` file or passed via configuration
+3. Check your license hasn't expired at [EventCatalog Cloud](https://eventcatalog.cloud)
+
+## Need Help?
+
+- [GitHub Issues](https://github.com/event-catalog/eventcatalog/issues)
+- [Discord Community](https://eventcatalog.dev/discord)
+- Email: hello@eventcatalog.dev