Custom::ProxylityUdpGatewayListener Destination

A destination specified an AWS resource that will be used to handle UDP packets. The resource specification may be a single ARN, or a map of ARNs by AWS Region name. The properties also specify the batching configuration and the IAM Role to be used (via sts:AssumeRole) by Proxylity to make use of the resource.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Name" : String,
  "Description" : String,
  "Role" : Role,
  "Batching" : Batching,
  "DestinationArn" : String or Map,
  "MetricsEnabled" : Boolean,
  "Formatter" : String (enum)
}

YAML

    Name: String
    Description: String
    Role: Role
    Batching: Batching
    DestinationArn: String
    MetricsEnabled: Boolean
    Formatter: String (enum)

Properties

Name

Name of destination which must be unique within the AWS account. If no name is specified one will be generated.

Required: No

Type: String

Pattern: [a-zA-Z0-9\-]+

Update requires: No interruption

Description

Short description of the destination for user reference.

Required: No

Type: String

Update requires: No interruption

Role

Indicates the execution role to be assumed by Proxylity, allowing use of the destination resource.

Required: No

Type: Role

Update requires: No interruption

Batching

Determines the number of packets that will be passed to the destination in each batch. Can be specified in count, time or total size.

Required: No

Type: Batching

Update requires: No interruption

DestinationArn

AWS resource ARN(s) to which packet batches will be delivered. A string value can be used when all packets, regardless of where they originate, will be handled by a single global resource.

A Map can be provided where each key is the name of an AWS region and the value is an ARN in that region. When a Map is used, all ARN values must specify the same AWS service.

Required: Yes

Type: String

Pattern: .*

Update requires: No interruption

MetricsEnabled

Set to true to track ingress and egress traffic (packet count and bytes) through the destination sent to your account as CloudWatch metrics. The default is false (no metrics).

Required: No

Type: Boolean

Update requires: No interruption

Formatter

Specifies the formatter to be used for the packets sent to (and responses from) the destination. The default is base64. The other options are hex, ascii, and utf8. In the case of synchronous response destinations (Lamnda and StepFunctions) the formatter applies to both the request and response, so destination code needs to produce the appropriate format. Note that when using CloudWatch Logs as a destination the delivery format will always be utf-8.

In some use cases it may be convenient to use hex or text formatting of the packet content rather than the default base64 encoding. For example, AWS StepFunctions isn't able to work with binary content, and base64 content is inconvenient, but hex encoding (a character per 4 bit 'nibble') can be parsed via JSONata expressions. Likewise, for a protocols like SYSLOG or RTSP it may be convenient to deliver packet data as UTF-8 strings.

Routing Behavior

Single ARN

When DestinationArn is a single string value, all packets are delivered to that resource regardless of the ingress region. This is ideal for:

Simple deployments with a single processing endpoint
Global services that can handle traffic from any region
Cost optimization when regional distribution isn't required

Regional Map

When DestinationArn is a map of AWS regions to ARNs, Proxylity routes traffic to the "closest" region based on network latency between:

The ingress region - where traffic first enters the Proxylity network
The destination regions - regions specified in your map

This routing provides:

Lower latency - Packets are processed closer to their entry point
Better performance - Reduced cross-region data transfer
Cost optimization - Minimizes AWS data transfer charges
Resilience - Automatic failover if a region becomes unavailable

Important: All ARNs in a regional map must be for the same AWS service type (e.g., all Lambda functions, all SNS topics, all Kinesis streams). Mixing service types within a single destination is not supported.

Examples

Single Global Destination

When using a single ARN, all traffic is routed to that resource regardless of where it originates:

JSON

{
  "Name": "global-notifications",
  "Description": "Global SNS topic for packet notifications",
  "DestinationArn": "arn:aws:sns:us-east-1:123456789012:packet-notifications",
  "Role": {
    "RoleArn": "arn:aws:iam::123456789012:role/ProxylitySnsRole"
  },
  "MetricsEnabled": true
}

YAML

Name: global-notifications
Description: Global SNS topic for packet notifications
DestinationArn: "arn:aws:sns:us-east-1:123456789012:packet-notifications"
Role:
  RoleArn: "arn:aws:iam::123456789012:role/ProxylitySnsRole"
MetricsEnabled: true

Multi-Region Lambda Destinations

When using a map of regions to ARNs, traffic is routed to the closest region based on latency. All ARNs must be for the same service type:

JSON

{
  "Name": "regional-lambda-processor",
  "Description": "Lambda functions deployed across multiple regions",
  "DestinationArn": {
    "us-east-1": "arn:aws:lambda:us-east-1:123456789012:function:packet-handler",
    "us-west-2": "arn:aws:lambda:us-west-2:123456789012:function:packet-handler",
    "eu-west-1": "arn:aws:lambda:eu-west-1:123456789012:function:packet-handler",
    "ap-southeast-1": "arn:aws:lambda:ap-southeast-1:123456789012:function:packet-handler"
  },
  "Role": {
    "RoleArn": "arn:aws:iam::123456789012:role/ProxylityLambdaRole"
  },
  "Batching": {
    "Count": 10,
    "TimeoutInSeconds": 5.0
  }
}

YAML

Name: regional-lambda-processor
Description: Lambda functions deployed across multiple regions
DestinationArn:
  us-east-1: "arn:aws:lambda:us-east-1:123456789012:function:packet-handler"
  us-west-2: "arn:aws:lambda:us-west-2:123456789012:function:packet-handler"
  eu-west-1: "arn:aws:lambda:eu-west-1:123456789012:function:packet-handler"
  ap-southeast-1: "arn:aws:lambda:ap-southeast-1:123456789012:function:packet-handler"
Role:
  RoleArn: "arn:aws:iam::123456789012:role/ProxylityLambdaRole"
Batching:
  Count: 10
  TimeoutInSeconds: 5.0

Multi-Region SNS Destinations

Similar multi-region setup using SNS topics:

JSON

{
  "Name": "regional-sns-notifier",
  "Description": "SNS topics for regional packet notifications",
  "DestinationArn": {
    "us-east-1": "arn:aws:sns:us-east-1:123456789012:packet-notifications",
    "us-west-2": "arn:aws:sns:us-west-2:123456789012:packet-notifications",
    "eu-west-1": "arn:aws:sns:eu-west-1:123456789012:packet-notifications"
  },
  "Role": {
    "RoleArn": "arn:aws:iam::123456789012:role/ProxylitySnsRole"
  },
  "Formatter": "utf8"
}

YAML

Name: regional-sns-notifier
Description: SNS topics for regional packet notifications
DestinationArn:
  us-east-1: "arn:aws:sns:us-east-1:123456789012:packet-notifications"
  us-west-2: "arn:aws:sns:us-west-2:123456789012:packet-notifications"
  eu-west-1: "arn:aws:sns:eu-west-1:123456789012:packet-notifications"
Role:
  RoleArn: "arn:aws:iam::123456789012:role/ProxylitySnsRole"
Formatter: utf8

Single Kinesis Firehose Destination

Using Kinesis Firehose for data streaming with custom formatting:

JSON

{
  "Name": "packet-stream",
  "Description": "Stream packets to S3 via Kinesis Firehose",
  "DestinationArn": "arn:aws:firehose:us-east-1:123456789012:deliverystream/packet-stream",
  "Role": {
    "RoleArn": "arn:aws:iam::123456789012:role/ProxylityFirehoseRole"
  },
  "Batching": {
    "Count": 100,
    "TimeoutInSeconds": 10.0,
    "SizeInMB": 1.0
  },
  "Formatter": "hex",
  "MetricsEnabled": true
}

YAML

Name: packet-stream
Description: Stream packets to S3 via Kinesis Firehose
DestinationArn: "arn:aws:firehose:us-east-1:123456789012:deliverystream/packet-stream"
Role:
  RoleArn: "arn:aws:iam::123456789012:role/ProxylityFirehoseRole"
Batching:
  Count: 100
  TimeoutInSeconds: 10.0
  SizeInMB: 1.0
Formatter: hex
MetricsEnabled: true