Hummingbird Events Topic

An SNS topic for all Hummingbird project events. This topic serves as a central hub for distributing events from multiple sources (GitLab webhooks, Kubernetes, etc.) to multiple subscribers, enabling event-driven architectures and integrations.

Features

Central Event Hub: Single SNS topic for all project events from multiple sources
Multiple Subscribers: Supports Lambda, SQS, HTTP endpoints, email, SMS, and more
Event Filtering: Subscribers can filter events using SNS subscription filter policies

Prerequisites

AWS CLI configured with appropriate credentials (IAM permissions for SNS, CloudFormation)
Podman or Docker (for containerized SAM build/deploy)

Deployment

Build and deploy using containerized AWS SAM CLI:

cd hummingbird-events-topic
make build     # Build SAM application
make deploy    # First deployment (interactive/guided)
make redeploy  # Subsequent deployments (non-interactive)

Deployment outputs:

TopicArn - SNS topic ARN (for event publishers)
TopicName - SNS topic name

Parameters

Parameter	Description	Default
`TopicName`	SNS topic name	`myapp-prod-events`

Resource naming: The SNS topic uses the provided TopicName parameter.

Usage

Publishing Events

Event publishers need the topic ARN to publish messages:

# Get topic ARN from CloudFormation stack
aws cloudformation describe-stacks \
  --stack-name <stack-name> \
  --query 'Stacks[0].Outputs[?OutputKey==`TopicArn`].OutputValue' \
  --output text

Event publishers:

gitlab-event-forwarder - Publishes GitLab webhook events
kubernetes-event-forwarder - Publishes Kubernetes resource changes
Custom event sources

Subscribing to Events

Subscribe services to receive events:

Via AWS Console:

Open SNS console → Topics
Select the topic
Create subscription (choose protocol: Lambda, SQS, HTTP, Email, etc.)
Add subscription filter policy (optional)

Via AWS CLI:

aws sns subscribe \
  --topic-arn <topic-arn> \
  --protocol lambda \
  --notification-endpoint <lambda-arn>

Add filter policy:

aws sns set-subscription-attributes \
  --subscription-arn <subscription-arn> \
  --attribute-name FilterPolicy \
  --attribute-value '{"source": ["gitlab"], "event_type": ["push"]}'

Subscription Filter Examples

GitLab push events from specific project:

{
  "source": ["gitlab"],
  "event_type": ["push"],
  "project_path": ["redhat/hummingbird/containers"]
}

All merge request events:

{
  "source": ["gitlab"],
  "event_type": ["merge_request"]
}

All events from GitLab:

{
  "source": ["gitlab"]
}

Event metadata: See publisher documentation for available metadata:

gitlab-event-forwarder - GitLab webhook event metadata
kubernetes-event-forwarder - Kubernetes resource event metadata

Development

This is a pure infrastructure project (no application code). See the main README for SAM build/deploy commands.

Security & Limitations

Security:

SNS topic follows least privilege principle
Access controlled via IAM policies
Supports server-side encryption (optional)
Publishers require sns:Publish permission
Subscribers require appropriate protocol permissions

Limitations:

Message size: Up to 256 KB
Maximum subscriptions: 12,500,000 per topic
Message retention: Not supported (use SQS for durable queuing)
Delivery retries: Protocol-dependent

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.