Proxylity UDP Gateway is designed from the ground up to support Infrastructure as Code (IaC) practices. This approach allows you to define, version, and manage your UDP infrastructure using declarative configuration files, bringing the same benefits to network infrastructure that you already enjoy with your application deployments.
Managing UDP listeners, destinations, and routing configurations through code provides several key advantages:
Proxylity provides the following custom CloudFormation resource types for comprehensive infrastructure management:
| Resource Type | Purpose | Documentation |
|---|---|---|
Custom::ProxylityUdpGatewayListener |
UDP, DTLS, and WireGuard listeners with assigned ports and domains | Listener Reference |
Custom::ProxylityUdpGatewayDestinationArn |
Connect ingress regions to Destination resources | DestinationArn Reference |
Custom::ProxylityUdpGatewayPacketSource |
Server-initiated delivery via SNS topic | PacketSource Reference |
| Type | Purpose | Documentation |
|---|---|---|
Destination |
AWS resources that process incoming packets | Destination Reference |
ClientRestriction |
IP address and network access controls | ClientRestriction Reference |
Peer |
WireGuard peer configurations and cryptographic keys | Peer Reference |
Role |
IAM role specifications for destination access | Role Reference |
Batching |
Packet batching and delivery optimization settings | Batching Reference |
Proxylity integrates with the AWS ecosystem through custom CloudFormation resource types, enabling support for multiple Infrastructure as Code tools:
Proxylity provides native CloudFormation custom resource types that integrate seamlessly with your existing AWS infrastructure. CloudFormation templates can define listeners, destinations, and all associated configuration in a declarative YAML or JSON format.
The AWS CLI CloudFormation commands work well for deployments involving inline Lambda functions and straightforward AWS resources. For more complex scenarios involving compiled dependencies or advanced template features, consider using SAM CLI even with plain CloudFormation templates.
Best for: Teams already using CloudFormation, simple inline Lambda functions, complex AWS integrations, and enterprise environments requiring AWS-native tooling.
SAM enhances CloudFormation in two key ways:
You can use the SAM transform (Transform: AWS::Serverless-2016-10-31) in regular CloudFormation
templates to access simplified resource types and helpful macros:
AWS::Serverless::Function,
AWS::Serverless::StateMachine, and others reduce boilerplateFn::ForEach for loops, enhanced Fn::FindInMap
capabilitiesAWS::Serverless::Application and
Fn::Transform includes for modular templatesThe SAM CLI excels when working with compiled Lambda functions (.NET, Java, Go) or complex dependencies:
sam localBest for: Any serverless application, compiled Lambda functions, teams wanting simplified CloudFormation syntax, local development and testing workflows.
The AWS CDK allows you to define infrastructure in a programming language and synthesize it into CloudFormation. The official Proxylity UDP Gateway CDK library provides L1 constructs that closely represent the custom resources and L2 constructs that simplify listener configuration, destination permissions, and dependencies.
Install from npm
(@proxylity/cdk-udp-gateway),
PyPI
(proxylity-cdk-udp-gateway), or
NuGet
(Proxylity.CDK.UdpGateway). See the
announcement and working TypeScript example
for an introduction to both construct levels.
Best for: Development teams that prefer programmatic infrastructure definition and want to leverage existing programming skills.
Terraform support for Proxylity is available through an official module published to the Terraform Registry. The module provides the same functionality as our CloudFormation resources, enabling multi-cloud deployments and integration with existing Terraform workflows.
The official Proxylity UDP Gateway module is available at:
Best for: Multi-cloud environments, teams already standardized on Terraform, and complex infrastructure with dependencies across cloud providers.
The fastest way to get started with Proxylity Infrastructure as Code is through AWS CloudFormation. Here's a simple example that creates a UDP listener with a Lambda destination:
AWSTemplateFormatVersion: '2010-09-09'
Description: 'Simple Proxylity UDP Gateway setup'
Resources:
UdpListener:
Type: Custom::ProxylityUdpGatewayListener
Properties:
ServiceToken: !Ref ProxylityServiceToken
ApiKey: !Ref ProxylityApiKey
Protocols:
- "udp"
ClientRestrictions:
Networks:
- "203.0.113.0/24"
Destinations:
- Name: packet-handler
DestinationArn: !GetAtt PacketHandler.Arn
Role:
Arn: !GetAtt ProxylityRole.Arn
PacketHandler:
Type: AWS::Lambda::Function
Properties:
Runtime: python3.9
Handler: index.handler
Code:
ZipFile: |
def handler(event, context):
# Process UDP packets here
return {'Replies': []}
Outputs:
ListenerEndpoint:
Description: "UDP endpoint for sending traffic"
Value: !Sub "${UdpListener.Domain}.proxylity.com:${UdpListener.Port}"
The Terraform module provides the same functionality as CloudFormation resources with familiar Terraform syntax. Here's a simple example that creates a UDP listener with a Lambda destination:
module "udp_gateway" {
source = "proxylity/udp-gateway/aws"
version = "~> 1.0"
listeners = [
{
name = "packet-processor"
destinations = [
{
name = "lambda-handler"
destination_arn = aws_lambda_function.packet_processor.arn
role = {
role_arn = aws_iam_role.lambda_role.arn
}
}
]
}
]
}
resource "aws_lambda_function" "packet_processor" {
filename = "packet_processor.zip"
function_name = "packet-processor"
role = aws_iam_role.lambda_role.arn
handler = "index.handler"
runtime = "python3.9"
}
resource "aws_iam_role" "lambda_role" {
name = "packet-processor-role"
assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Action = "sts:AssumeRole"
Effect = "Allow"
Principal = {
Service = "lambda.amazonaws.com"
}
}
]
})
}
output "udp_endpoint" {
description = "UDP endpoint for sending traffic"
value = "${module.udp_gateway.listeners[0].domain}.proxylity.com:${module.udp_gateway.listeners[0].port}"
}
For complete examples and documentation, visit the Terraform Registry page.
Use the AWS CLI CloudFormation commands when:
Use the SAM CLI when:
AWS::Serverless::Function)Fn::ForEach or Fn::TransformUse Terraform when:
Even plain CloudFormation templates benefit from SAM's simplified syntax:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: 'Serverless UDP packet processing with simplified syntax'
Resources:
PacketHandler:
Type: AWS::Serverless::Function
Properties:
Runtime: python3.9
Handler: index.handler
InlineCode: |
def handler(event, context):
# Process UDP packets here
return {'Replies': []}
UdpListener:
Type: Custom::ProxylityUdpGatewayListener
Properties:
ServiceToken: !Ref ProxylityServiceToken
ApiKey: !Ref ProxylityApiKey
Protocols:
- "udp"
ClientRestrictions:
Networks:
- "203.0.113.0/24"
Destinations:
- Name: packet-handler
DestinationArn: !Ref PacketHandler
Role:
Arn: !GetAtt ProxylityRole.Arn
For compiled functions, SAM CLI handles building and packaging:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: 'Compiled .NET Lambda with Proxylity'
Resources:
PacketProcessor:
Type: AWS::Serverless::Function
Properties:
CodeUri: src/PacketProcessor/
Handler: PacketProcessor::PacketProcessor.Function::FunctionHandler
Runtime: dotnet6
MemorySize: 256
Timeout: 30
UdpListener:
Type: Custom::ProxylityUdpGatewayListener
Properties:
ServiceToken: !Ref ProxylityServiceToken
ApiKey: !Ref ProxylityApiKey
Protocols:
- "udp"
Destinations:
- Name: compiled-handler
DestinationArn: !Ref PacketProcessor
Deployment:
# SAM CLI automatically builds, packages, and deploys
sam build
sam deploy --guided
Successful Infrastructure as Code implementations with Proxylity typically follow these patterns:
Use separate templates or parameter files for different environments:
Break complex configurations into reusable components:
Use AWS Systems Manager Parameter Store or AWS Secrets Manager for sensitive configuration:
Use CloudFormation StackSets or deployment pipelines to maintain consistent configurations across multiple AWS accounts and regions while allowing for environment-specific customization.
Implement blue-green deployments by creating new listeners with updated configurations and gradually migrating traffic. This approach minimizes downtime and provides easy rollback capabilities.
Design cross-region deployments using CloudFormation to ensure business continuity. Proxylity's anycast architecture simplifies failover scenarios when combined with proper IaC practices.
If you're currently managing Proxylity resources through the dashboard or API calls, migrating to Infrastructure as Code provides significant benefits:
When a Proxylity resource cannot be created, updated or deleted, CloudFormation shows the reason in the stack
events for that resource. Match on the text of the message rather than its prefix, because some messages start
with Resource handler error: and others do not.
Every operation on a Proxylity resource, including deleting it, checks your AWS Marketplace subscription and the
ApiKey you supplied. If the check fails, the resource operation fails with a message of the form
Resource handler error: Subscription validation error: <reason>, where the reason is one of:
| Reason | What to check |
|---|---|
No subscription found for this AWS account. |
The AWS account deploying the stack has no Proxylity subscription. |
Subscription is not active. Please contact Proxylity support. |
The subscription for the account is not currently active. |
Multiple subscriptions found for this AWS account. Please contact Proxylity support. |
Contact support. |
Subscription data error. Please contact Proxylity support. |
Contact support. |
ApiKey is not valid. |
The value is not a usable ApiKey. Use the value from your customer configuration. |
ApiKey is not valid for this AWS account. |
The key was issued for a different AWS account. |
ApiKey is not valid yet. |
The key's start time has not been reached. |
ApiKey has expired. |
The key has expired. Obtain a current key. |
ApiKey is invalid. |
The key could not be verified. Check that it was copied completely and is current. |
A missing ApiKey property fails with Resource handler error: ApiKey property is
required.
A read-only ApiKey cannot create, update or delete Proxylity resources, and Packet Sources are not
available on every plan. In these cases the operation fails with a message of the form
Resource handler error: Invalid <resource type> request type '<Create|Update|Delete>' with given
permissions., for example Resource handler error: Invalid listener request type 'Create' with given
permissions.
Need assistance with Infrastructure as Code implementation?
Infrastructure as Code with Proxylity transforms UDP network management from a manual, error-prone process into a reliable, version-controlled, and automated practice. Start with simple configurations and gradually adopt more sophisticated patterns as your team's expertise grows.