@byub/cli v0.3.0

Introduction

This repository is a collection of CLI tools for software developers at BYU Broadcasting. Currently the collection consists of a single tool :).

IMPORTANT:

Note that this is a public repository. Please do not commit sensitive information to this repository!

This repository was made public in order to play nice with the NPM registry and npx, but is still meant to be used as a tool for internal development of BYU Broadcasting.

Usage

Run npx @byub/cli --help to see available commands.

Create an Event Schema for use with Amazon EventBridge

Generate JSON-Schema for an Event

To create an event schema in JSON-schema format, run the following command:

npx @byub/cli create-event-schema MyFirstEvent

The generated JSON-schema is a skeleton for the event. After creating the event schema, you should modify the schema to match the event you want to create.

For example, if the payload of the MyFirstEvent event should have a required name field and an optional age field, then you should modify the schema as follows:

{
  "openapi": "3.0.0",
  "info": { ... },
  "paths": {},
  "components": {
    "schemas": {
      "AWSEvent": { ... },
      "MyFirstEvent": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          }
        }
      }
    }
  }
}

For more information on available data types and further schema customization, see JSON-Schema.

Generate Standalone Cloudformation Template

To create a Cloudformation template (without Serverless Framework support) for an EventSchema, run the following command:

npx @byub/cli create-event-schema MyFirstEvent --template=cloudformation

The generated template can be deployed as a stack to AWS CloudFormation.

~$ npx @byub/cli create-event-schema MyFirstEvent --template=cloudformation
~$ aws cloudformation create-stack --stack-name my-event-schema-stack --template-body file://MyFirstEvent.yml

The Cloudformation template contains three resources:

• AWS::EventSchemas::Schema: The schema itself.
• AWS::Events::Rule: A rule for EventBridge that routes events to a CloudWatch log group. This can be extremely useful for troubleshooting issues and inspecting the actual payload of events.
• AWS::Logs::LogGroup: The log group that the Event Rule will send events to.

Generate Cloudformation Template for Serverless Framework

To create a Cloudformation template that is compatible with Serverless Framework, run the following command:

npx @byub/cli create-event-schema MyFirstEvent --template=sls

The generated template is meant to be incorporated into a Serverless Framework project. For example, the previous command would generate a template that looks something like the following:

Resources:
  MyFirstEventSchema:
    Type: AWS::EventSchemas::Schema
    Properties:
      RegistryName: ${cf:regionbase.Platform5EventSchemaRegistryName}
      SchemaName: ${self:service}@MyFirstEvent
      Type: OpenApi3
      Content: |-
          <the JSON-schema for the event>

  MyFirstEventLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: /aws/events/${self:service}-MyFirstEvent-catchall
      RetentionInDays: 14

  MyFirstEventCatchAllRule:
    Type: AWS::Events::Rule
    Properties:
      Description: Catch all rule to send events to CloudWatch.
      EventBusName: ${cf:regionbase.BYUBEventBusName}
      Name: ${self:service}-MyFirstEvent-catchall
      Targets:
        - Arn:
            Fn::GetAtt: MyFirstEventLogGroup.Arn
          Id: ${self:service}-MyFirstEvent-catchall-rule
      EventPattern:
        source:
          - ${self:service}
        detail-type:
          - MyFirstEvent

After generating the template, simply copy/paste the Cloudformation resources to the resources.Resources section of your serverless.yml file.

service: service-abc

provider:
  name: aws
  # ...

functions:
  # ...

resources:
  Resources:
    MyFirstEventSchema:
      Type: AWS::EventSchemas::Schema
      Properties:
        # ...

    MyFirstEventLogGroup:
      Type: AWS::Logs::LogGroup
      Properties:
        # ...

    MyFirstEventCatchAllRule:
      Type: AWS::Events::Rule
      Properties:
        # ...