Manage EventBridge event buses and rules with the ACK EventBridge Controller

Create and manage EventBridge event buses and rules directly from Kubernetes

EventBridge is a serverless service that uses events to connect application components together, making it easier for you to build scalable event-driven applications. Use it to route events from sources such as home-grown applications, AWS services, and third-party software to consumer applications across your organization. EventBridge provides a simple and consistent way to ingest, filter, transform, and deliver events so you can build new applications quickly.

In this tutorial you will learn how to create and manage a custom EventBridge event bus and rule to filter and forward messages to an SQS target from an Amazon Elastic Kubernetes (EKS) deployment.

Setup

Although it is not necessary to use Amazon Elastic Kubernetes Service (Amazon EKS) with ACK, this guide assumes that you have access to an Amazon EKS cluster. If this is your first time creating an Amazon EKS cluster, see Amazon EKS Setup. For automated cluster creation using eksctl, see Getting started with Amazon EKS - eksctl and create your cluster with Amazon EC2 Linux managed nodes.

Prerequisites

This guide assumes that you have:

  • Created an EKS cluster with Kubernetes version 1.24 or higher.
  • AWS IAM permissions to create roles and attach policies to roles.
  • AWS IAM permissions to manages queues and send messages to a queue.
  • Installed the following tools on the client machine used to access your Kubernetes cluster:
    • AWS CLI - A command line tool for interacting with AWS services.
    • kubectl - A command line tool for working with Kubernetes clusters.
    • eksctl - A command line tool for working with EKS clusters.
    • Helm 3.8+ - A tool for installing and managing Kubernetes applications.
    • jq to parse AWS CLI JSON output

Install the ACK service controller for EventBridge

Log into the Helm registry that stores the ACK charts:

aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws

Deploy the ACK service controller for Amazon EventBridge using the eventbridge-chart Helm chart. Resources should be created in the us-east-1 region:

helm install --create-namespace -n ack-system oci://public.ecr.aws/aws-controllers-k8s/eventbridge-chart --version=v1.0.0 --generate-name --set=aws.region=us-east-1

For a full list of available values to the Helm chart, please review the values.yaml file.

Configure IAM permissions

Once the service controller is deployed, you will need to configure the IAM permissions for the controller to query the EventBridge API. For full details, please review the AWS Controllers for Kubernetes documentation for how to configure the IAM permissions. If you follow the examples in the documentation, use the value of eventbridge for SERVICE.

Create an EventBridge Custom Event Bus and Rule with an SQS Target

Create the target SQS queue

To keep the scope of this tutorial simple, the SQS queue and IAM permissions will be created with the AWS CLI. Alternatively, the ACK SQS Controller and ACK IAM Controller can be used to manage these resources with Kubernetes.

Execute the following command to define the environment variables used throughout the example.

Make sure environment variables are set
If you followed the steps in the IAM permissions section above, the required environment variables ${AWS_REGION} and ${AWS_ACCOUNT_ID} are already set. Otherwise please set these variables before executing the following steps. The value for ${AWS_REGION} must also match the --set=aws.region value used in the helm install command above.
export EVENTBRIDGE_NAMESPACE=eventbridge-example
export EVENTBUS_NAME=custom-eventbus-ack
export RULE_NAME=custom-eventbus-ack-sqs-rule
export TARGET_QUEUE=custom-eventbus-ack-rule-sqs-target

Create the target queue.

cat <<EOF > target-queue.json
{
    "QueueName": "${TARGET_QUEUE}",
    "Attributes": {
        "Policy": "{\"Statement\":[{\"Sid\":\"EventBridgeToSqs\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"events.amazonaws.com\"},\"Action\":[\"sqs:SendMessage\"],\"Resource\":\"arn:aws:sqs:${AWS_REGION}:${AWS_ACCOUNT_ID}:${TARGET_QUEUE}\",\"Condition\":{\"ArnEquals\":{\"aws:SourceArn\":\"arn:aws:events:${AWS_REGION}:${AWS_ACCOUNT_ID}:rule/${EVENTBUS_NAME}/${RULE_NAME}\"}}}]}"
    }
}
EOF

aws sqs create-queue --cli-input-json file://target-queue.json

The output of above commands looks like

{
    "QueueUrl": "https://sqs.us-east-1.amazonaws.com/1234567890/custom-eventbus-ack-rule-sqs-target"
}

Create a Custom Event Bus

Execute the following command to create the example namespace and a custom event bus.

kubectl create ns ${EVENTBRIDGE_NAMESPACE}

cat <<EOF > bus.yaml
apiVersion: eventbridge.services.k8s.aws/v1alpha1
kind: EventBus
metadata:
  name: ${EVENTBUS_NAME}
spec:
  name: ${EVENTBUS_NAME}
EOF

kubectl -n ${EVENTBRIDGE_NAMESPACE} create -f bus.yaml

The output of above commands looks like

namespace/eventbridge-example created
eventbus.eventbridge.services.k8s.aws/custom-eventbus-ack created

Verify the event bus resource is synchronized.

kubectl -n ${EVENTBRIDGE_NAMESPACE} get eventbus ${EVENTBUS_NAME}

The output of above commands looks like

NAME                  SYNCED   AGE
custom-eventbus-ack   True     64s

Create a Rule with an SQS Target

Execute the following command to retrieve the ARN for the SQS target created above needed for the Kubernetes manifest.

export TARGET_QUEUE_ARN=$(aws --output json sqs get-queue-attributes --queue-url "https://sqs.${AWS_REGION}.amazonaws.com/${AWS_ACCOUNT_ID}/${TARGET_QUEUE}" --attribute-names QueueArn | jq -r '.Attributes.QueueArn')

Execute the following command to create a Kubernetes manifest for a rule, forwarding events matching the specified rule filter criteria to the target queue. The EventBridge filter pattern will match any event received on the custom event bus with a detail-type of event.from.ack.v0. Alternatively, the filter pattern can be omitted to forward all events from the custom event bus.

cat <<EOF > rule.yaml
apiVersion: eventbridge.services.k8s.aws/v1alpha1
kind: Rule
metadata:
  name: $RULE_NAME
spec:
  name: $RULE_NAME
  description: "ACK EventBridge Filter Rule to SQS using event bus reference"
  eventBusRef:
    from:
      name: $EVENTBUS_NAME
  eventPattern: |
    {
      "detail-type":["event.from.ack.v0"]
    }
  targets:
    - arn: $TARGET_QUEUE_ARN
      id: sqs-rule-target
      retryPolicy:
        maximumRetryAttempts: 0 # no retries
EOF

kubectl -n ${EVENTBRIDGE_NAMESPACE} create -f rule.yaml

The output of above commands looks like

rule.eventbridge.services.k8s.aws/custom-eventbus-ack-sqs-rule created

Verify the rule resource is synchronized.

kubectl -n ${EVENTBRIDGE_NAMESPACE} get rule ${RULE_NAME}

The output of above commands looks like

NAME                           SYNCED   AGE
custom-eventbus-ack-sqs-rule   True     18s

Verify the event filtering and forwarding is working

Execute the following command to send an event to the custom bus matching the rule filter pattern.

cat <<EOF > event.json
[
    {
        "Source": "my.aws.events.cli",
        "DetailType": "event.from.ack.v0",
        "Detail": "{\"hello-world\":\"from ACK for EventBridge\"}",
        "EventBusName": "${EVENTBUS_NAME}"
    }
]
EOF

aws events put-events --entries file://event.json

The output of above commands looks like

{
    "FailedEntryCount": 0,
    "Entries": [
        {
            "EventId": "ccd21ee8-339d-cabe-520d-b847c98ba2cb"
        }
    ]
}

Verify the message was received by the SQS queue with

aws sqs receive-message --queue-url https://sqs.${AWS_REGION}.amazonaws.com/${AWS_ACCOUNT_ID}/${TARGET_QUEUE}

The output of above commands looks like

{
    "Messages": [
        {
            "MessageId": "80cef2f3-ff25-4441-9217-665bb0217ec5",
            <snip>
            "Body": "{\"version\":\"0\",\"id\":\"def3d99b-806b-5d92-d036-9e0884bdc387\",\"detail-type\":\"event.from.ack.v0\",\"source\":\"my.aws.events.cli\",\"account\":\"1234567890\",\"time\":\"2023-03-22T11:22:34Z\",\"region\":\"us-east-1\",\"resources\":[],\"detail\":{\"hello-world\":\"from ACK for EventBridge\"}}"
        }
    ]
}

Next steps

The ACK service controller for Amazon EventBridge is based on the Amazon EventBridge API.

Refer to API Reference for EventBridge to find all the supported Kubernetes custom resources and fields.

Cleanup

Remove all the resource created in this tutorial using kubectl delete command.

kubectl -n ${EVENTBRIDGE_NAMESPACE} delete -f rule.yaml
kubectl -n ${EVENTBRIDGE_NAMESPACE} delete -f bus.yaml
kubectl delete ns ${EVENTBRIDGE_NAMESPACE}

The output of delete command should look like

rule.eventbridge.services.k8s.aws "custom-eventbus-ack-sqs-rule" deleted
eventbus.eventbridge.services.k8s.aws "custom-eventbus-ack" deleted
namespace "eventbridge-example" deleted

Remove the manually created SQS resource.

aws sqs delete-queue --queue-url https://sqs.${AWS_REGION}.amazonaws.com/${AWS_ACCOUNT_ID}/${TARGET_QUEUE}

If the command executes successfully, no output is generated.

To remove the EventBridge ACK service controller, related CRDs, and namespaces, see ACK Cleanup.

To delete your EKS clusters, see Amazon EKS - Deleting a cluster.

Edit this page on GitHub