Proxylity

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,
  "LogGroupName" : String,
  "Formatter" : String (enum),
  "FilterExpression" : String,
  "Arguments" : Object
}
    

YAML

    Name: String
    Description: String
    Role: Role
    Batching: Batching
    DestinationArn: String
    MetricsEnabled: Boolean
    LogGroupName: String
    Formatter: String (enum)
    FilterExpression: String
    Arguments: Object
    

Properties

Name

Name of destination which must be unique within the AWS account. If no name is specified one will be generated for a destination defined inline in a listener's Destinations property, in the form dstn-<stack name>-<logical ID of the listener>-<n>. The number n counts the inline destinations of that listener, starting from zero, in the order they are declared. Entries in Destinations that reference an existing destination by name are not counted. To find the names of a listener's destinations, expose the listener's DestinationNames attribute (see Listener) in a stack output.

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. The role is specified with the Arn and optional Duration properties; the name RoleArn is not valid.

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 publish destination-level metrics into your AWS account under Proxylity/UDP Gateway, with dimension Destination set to this destination's Name. The destination's Role must grant cloudwatch:PutMetricData in addition to its delivery permissions. This does not enable listener metrics or require logging.

The published names are IngressPackets, IngressBytes, EgressPackets, EgressBytes, FilteredPackets, FilteredBytes, and Errors. Ingress counts accepted, queued packets; egress counts responses, not AWS delivery requests; filtered counters measure packets rejected by FilterExpression. Packet counts are size-weighted, and Errors counts reported error occurrences independently of logging. See the CloudWatch Metrics Reference for exact meanings, regions, traffic boundaries, IAM permissions, and alarm examples.

Required: No

Type: Boolean

Default: false

Update requires: No interruption

LogGroupName

CloudWatch Logs log group name for destination error and warning messages. When specified, Proxylity will create log streams within this group and write messages for errors and warnings that occur during packet delivery. This is particularly helpful for identifying issues such as IAM role permission problems, malformed destination ARNs, or service-specific delivery failures.

Destination logs are written in the region of the resolved destination ARN, or in the region where traffic entered the Proxylity network when the ARN has no region (an S3 ARN, for example). Create the log group in each region that can apply; where the log group does not exist, no logs are written. Destination metrics follow the same rule.

Important: The destination's IAM role must include permissions for logs:CreateLogStream and logs:PutLogEvents on the specified log group resource.

Required: No

Type: String

Update requires: No interruption

Formatter

Specifies how packet payloads are represented in the Data field delivered to the destination, and how the Data of replies is turned back into bytes. One of base64, hex, utf8, ascii, coap, coap+ or syslog. The default is utf8 for CloudWatch Logs destinations and base64 for all others. For destinations that reply (Lambda, Lambda MicroVMs, EXPRESS Step Functions and API Gateway) the formatter applies to both the request and the reply, so destination code needs to produce the matching format.

See Payload Formatters for the exact shapes, examples and error behavior of each formatter.

Note: The coap, coap+ and syslog options are only available for the main destination Formatter property. It is not supported by service-specific argument formatters such as TenantIdFormatter, MessageGroupIdFormatter, or TopicSuffixFormatter, which are limited to ascii, hex, base64, and utf8.

FilterExpression

An optional BREX expression evaluated against each inbound packet. Only packets that produce a truthy value are delivered to the destination. Packets that do not match are dropped — they are not delivered to the destination and are not billed.

The expression is evaluated against the decapsulated payload when DecapsulatedDelivery is enabled on the parent WireGuard listener, and against the raw packet otherwise (including all plain UDP listeners).

When MetricsEnabled is true, two additional metrics are published for filtered traffic: FilteredPackets (count) and FilteredBytes (total bytes of dropped packets).

Required: No

Type: String

Update requires: No interruption

Arguments

An object holding settings that are specific to the destination's service, such as the tenant settings for Lambda functions, the message group settings for SQS or the topic suffix settings for IoT Data. Service settings must be placed inside Arguments, not directly on the destination. A key that is not recognized in Arguments, or a key that does not apply to the service of the destination ARN, causes the stack operation to fail. See the page for each service under Destinations for the settings it accepts.

Required: No

Type: Object

Update requires: No interruption

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:

Regional Map

When DestinationArn is a map of AWS regions to ARNs, the ARN for each batch is chosen in this order:

  1. The entry whose key is the ingress region, the region where traffic first entered the Proxylity network.
  2. Otherwise, the entry whose key is *.
  3. Otherwise, the entry whose region is closest to the ingress region by network latency.

The key does not have to match the region inside its ARN. A single (string) ARN may use * as its region component, for example arn:aws:sqs:*:123456789012:my-queue; it then resolves to the ingress region. A single ARN with an explicit region is always used as written.

This routing provides:

Important: All ARNs in a regional map must be for the same AWS service type (e.g., all Lambda functions or all Lambda MicroVM images, 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": {
    "Arn": "arn:aws:iam::123456789012:role/ProxylitySnsRole"
  },
  "LogGroupName": "/proxylity/destinations/global-notifications",
  "MetricsEnabled": true
}
    

YAML

Name: global-notifications
Description: Global SNS topic for packet notifications
DestinationArn: "arn:aws:sns:us-east-1:123456789012:packet-notifications"
Role:
  Arn: "arn:aws:iam::123456789012:role/ProxylitySnsRole"
LogGroupName: /proxylity/destinations/global-notifications
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": {
    "Arn": "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:
  Arn: "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": {
    "Arn": "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:
  Arn: "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": {
    "Arn": "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:
  Arn: "arn:aws:iam::123456789012:role/ProxylityFirehoseRole"
Batching:
  Count: 100
  TimeoutInSeconds: 10.0
  SizeInMB: 1.0
Formatter: hex
MetricsEnabled: true