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.
To declare this entity in your AWS CloudFormation template, use the following syntax:
{
"Name" : String,
"Description" : String,
"Role" : Role,
"Batching" : Batching,
"DestinationArn" : String or Map,
"MetricsEnabled" : Boolean,
"LogGroupName" : String,
"Formatter" : String (enum),
"FilterExpression" : String,
"Arguments" : Object
}
Name: String
Description: String
Role: Role
Batching: Batching
DestinationArn: String
MetricsEnabled: Boolean
LogGroupName: String
Formatter: String (enum)
FilterExpression: String
Arguments: Object
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
Short description of the destination for user reference.
Required: No
Type: String
Update requires: No interruption
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
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
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
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
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
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.
base64, hex, utf8 and ascii encode the payload bytes as
text. Hex is convenient in Step Functions, which can't work with binary content; utf8 suits
text protocols such as RTSP.coap decodes each CoAP
message into a JSON object with a base64 Payload, and encodes JSON replies back into CoAP.coap+ does the same, and also decodes and encodes Payload according to its
Content-Format (text, JSON, CBOR, SenML, link-format and XML).syslog parses RFC 5424 and RFC 3164
syslog messages into a JSON object of fields, and builds
syslog messages from the same shape.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.
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
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
When DestinationArn is a single string value, all packets are delivered to that resource regardless of the ingress region. This is ideal for:
When DestinationArn is a map of AWS regions to ARNs, the ARN for each batch is chosen in this
order:
*.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.
When using a single ARN, all traffic is routed to that resource regardless of where it originates:
{
"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
}
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
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:
{
"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
}
}
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
Similar multi-region setup using SNS topics:
{
"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"
}
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
Using Kinesis Firehose for data streaming with custom formatting:
{
"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
}
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