Installation
eventcatalog@2.6.0The EventBridge plugin is a generator that can be used to generate your EventCatalog from an EventBridge registry.
You can map your schemas to services, domains and messages. You can also map all events from your registry into your catalog.
Installation
Run the following command to install the plugin.
If you don't have an EventCatalog project yet, you can follow the instructions in the Getting Started guide.
- Install on existing catalog
- Create new catalog with the EventBridge template
npm i @eventcatalog/generator-eventbridge
npx @eventcatalog/create-eventcatalog@latest my-catalog --template eventbridge
Configuration
Configure the plugin in your eventcatalog.config.js file.
Add the plugin to the generators array.
- Import all schemas
- Map schemas to producers and consumers
- Multiple domains, services and events
In this example we import all schemas from an EventBridge registry.
We don't map them to any services or domains.
// ...
generators: [
// Import all schemas into your catalog
[
'@eventcatalog/generator-eventbridge',
{
// The region of your EventBridge registry
region: 'us-east-1',
// The name of your EventBridge registry
registryName: 'discovered-schemas'
},
],
],
// ...
In this example we map schemas to producers and consumers (services).
Every time you run the plugin, it will check if the service already exists in your catalog.
If the service already exists, it will not create a new one and just maintain the schema mappings.
We create two services, the orders service and the inventory service.
// ...
generators: [
[
'@eventcatalog/generator-eventbridge',
{
// The region of your EventBridge registry
region: 'us-east-1',
// The name of your EventBridge registry
registryName: 'discovered-schemas',
// Creating producers and consumers, and mapping them to your catalog
services: [
// We map schemas to the orders service
// Using the detailType we can map specific events to the service
{ id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted", eventBusName: 'inventory'}] },
// Map events to the Inventory Service
// Filter by source (all events that match the source get assigned). This example shows any event matching the source
// "myapp.orders" will be assigned to the inventory service. The inventory service will publish these events.
{ id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders", eventBusName: 'orders'}], receives:[{ detailType: "UserCheckedOut", eventBusName: 'inventory'}] },
// This service sends events that match the SchemaName prefixing myapp, and will receive events that end with Payment
// this also does not map any event buses to your events
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
],
// all services are mapped to this domain
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
],
],
// ...
In this example we have two domains, orders and inventory.
We map schemas to the orders and inventory services, and we assign these services to new domains.
If the domain or service already exists in your catalog, the plugin will not create a new one and just maintain the schema mappings.
The plugin can be defined multiple times in your eventcatalog.config.js file.
In this example we define the plugin twice, the first time we import the schemas and create the orders domain.
The second time we map the inventory service to the inventory domain.
// ...
generators: [
[
'@eventcatalog/generator-eventbridge',
{
// The region of your EventBridge registry
region: 'us-east-1',
// The name of your EventBridge registry
registryName: 'discovered-schemas',
// Creating producers and consumers, and mapping them to your catalog
services: [
// We map schemas to the orders service
// Using the detailType we can map specific events to the service
{ id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted", eventBusName: 'inventory'}] },
],
// all services are mapped to this domain
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
],
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
services: [
// Create the inventory service and map schemas to it (producer/consumer relationship)
{ id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders", eventBusName: 'orders'}], receives:[{ detailType: "UserCheckedOut", eventBusName: 'inventory'}] },
],
// create the inventory domain and assign the inventory service to it
domain: { id: 'inventory', name: 'Inventory', version: '0.0.1' },
},
],
],
// ...
This plugin is open source under the MIT License and doesn't need a license key. If your config still sets licenseKey or an EVENTCATALOG_LICENSE_KEY_* variable, you can remove it; it's ignored.
Run the plugin
This command will run the generators in your eventcatalog.config.js file.
npm run generate
View your catalog
Run your catalog locally to see the changes
npm run dev
AWS Configuration
Policy for AWS
This plugin will require some read access to your Schema Registry and Versions.
It's recommended you create a new IAM user with the following policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EventCatalog",
"Effect": "Allow",
"Action": [
"schemas:ExportSchema",
"schemas:SearchSchemas",
"schemas:ListSchemas",
"schemas:ListSchemaVersions",
"schemas:DescribeSchema",
"schemas:GetDiscoveredSchema"
],
"Resource": "*"
}
]
}
Issues
If you have any problems or feature requests please feel free to raise them on GitHub. https://github.com/event-catalog/generators