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. Configure license key​

Go to EventCatalog Cloud to get a trial license key for this plugin. Once you have a license key for EventBridge plugin you can set it in your environment variables or in your eventcatalog.config.js file.

eventcatalog.config.js
export default {
  generators: [
    [
      '@eventcatalog/generator-eventbridge',
      {
        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_EVENTBRIDGE
        region: 'us-east-1',
        registryName: 'discovered-schemas'
      },
    ],
  ],
};

or you can set the license key as an environment variable on the machine building/running the plugin.

Setting license key as environment variable
EVENTCATALOG_LICENSE_KEY_EVENTBRIDGE={INSERT_YOUR_LICENSE_KEY}

4. Run the generate command​

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

npm run generate

5. 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 and License​

This plugin is governed by a dual-license. To ensure the sustainability of the project.

You can get a 14 day trial license key to try the plugin out by going to EventCatalog Cloud.

After the trial you can purchase a license to continue using this plugin.

Have any questions? You can email us at hello@eventcatalog.dev.

License FAQ​

What is the license key for?​

The license key is required to use the OpenAPI plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.

How do I get a license key?​

You can obtain a license key by visiting EventCatalog Cloud. New users can start with a 14-day free trial.

Terms​

  • Usage: Any many catalogs as you like in your organization
  • Trial Period: 14 days free trial no credit card required
  • Support: Discord community support (extra for priority support)

After your trial period ends, you can purchase a full license through EventCatalog Cloud to continue using the plugin.

Issues​

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