Skip to main content

Getting started

Added in eventcatalog@2.6.0
License: Dual-license

Amazon EventBridge is an AWS service that helps developers build event-driven applications at scale. Amazon EventBridge offers mutiple solutions including Event Bus, Amazon EventBridge Pipes and Amazon EventBridge Scheduler.

Amazon EventBridge also offers a schema registry. This registry help you store your events in JSON and OpenAPI formats, give you the ability to download code bindings and also manage schema versions with automatic schema discovery.

Using the schema discovery feature, as events are put onto the event bus they are versioned and stored in the registry. These schemas can be used to help you and your teams understand and discover events in your event-driven architecture.

Although EventBridge offers managed schema solutions, there is a still an issue of discoverabilty and documentation for your events, services and domains. It still remains difficult to organize your event-driven architecture for governance.

Why use EventCatalog with EventBridge?​

Using the EventCatalog EventBridge generator you can automate and generate your EventCatalog. Enable your teams to quickly find events from EventBridge, what services they belong too and how to start consuming them.

Core Features​

The EventCatalog Amazon EventBridge plugin can provide you with many features:

How it works​

Example

EventCatalog supports generators. These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an SDK to give developers easier access to their catalogs through custom scripts or generators.

The EventCatalog EventBridge plugin let's you map your events into domains and services. You can use custom filters (prefix, suffix, detailType and source) to map which events you want your service to produce and consume.

You can also use the EventCatalog plugin to map ALL events from your registry into your system and not map them into services if you wish to have a direct import.

Getting started​

1. Install the plugin​

npm i @eventcatalog/generator-eventbridge

2. Configure your generator in your eventcatalog.config.js file​

eventcatalog.config.js
import path from 'path';
import url from 'url';

const __dirname = path.dirname(url.fileURLToPath(import.meta.url));

/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
export default {
  title: 'OurLogix',
  tagline: 'A comprehensive logistics and shipping management company',
  organizationName: 'OurLogix',
  homepageLink: 'https://eventcatalog.dev/',
  landingPage: '',
  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
  // By default set to false, add true to get urls ending in /
  trailingSlash: false,
  // Change to make the base url of the site different, by default https://{website}.com/docs,
  // changing to /company would be https://{website}.com/company/docs,
  base: '/',
  // Customize the logo, add your logo to public/ folder
  logo: {
    alt: 'EventCatalog Logo',
    src: '/logo.png',
    text: 'OurLogix',
  },
  docs: {
    sidebar: {
      // Should the sub heading be rendered in the docs sidebar?
      showPageHeadings: true,
    },
  },
  generators: [
    [
      '@eventcatalog/generator-eventbridge',
      {
        region: 'us-east-1',
        registryName: 'discovered-schemas',
        services: [
          // Maps exact events to the service
          { id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted", eventBusName: 'inventory'}]} },

          // 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' },
      },
    ],
    // Just import all events into the Catalog from a registry
    [
      '@eventcatalog/generator-eventbridge',
      {
        region: 'us-east-1',
        registryName: 'discovered-schemas'
      },
    ],
    // Example using optional credentials
    [
      '@eventcatalog/generator-eventbridge',
      {
        region: 'us-east-1',
        registryName: 'discovered-schemas',
        credentials: {
          accessKeyId: 'X',
          secretAccessKey: 'X',
          accountId: 'X',
        },
      },
    ],
  ],
};

3. Run the generate command​

This command will run the generators in your eventcatalog.config.js file.

npm run generate

4. 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": "*"
        }
    ]
}

Commercial Use​

This plugin is governed by a dual-license. To ensure the sustainability of the project, you can freely make use of this software if usage is also Open Source. Otherwise for proprietary use, internal use, and private modifications you must obtain a commercial license.

To purchase a license you to login to the EventCatalog Dashboard or if you have any questions you you can email us at hello@eventcatalog.dev.

Login to EventCatalog Dashboard

Issues​

If you have any problems or feature requests please feel free to raise them on GitHub. https://github.com/event-catalog/generator-eventbridge