Proxylity

Infrastructure as Code with Proxylity

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.

Why Infrastructure as Code?

Managing UDP listeners, destinations, and routing configurations through code provides several key advantages:

CloudFormation Resource Types Reference

Proxylity provides the following custom CloudFormation resource types for comprehensive infrastructure management:

Core Resources

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

Configuration Types

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

Supported IaC Tools

Proxylity integrates with the AWS ecosystem through custom CloudFormation resource types, enabling support for multiple Infrastructure as Code tools:

AWS CloudFormation

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.

AWS SAM (Serverless Application Model)

SAM enhances CloudFormation in two key ways:

SAM Transform with Plain CloudFormation

You can use the SAM transform (Transform: AWS::Serverless-2016-10-31) in regular CloudFormation templates to access simplified resource types and helpful macros:

SAM CLI for Dependency Management

The SAM CLI excels when working with compiled Lambda functions (.NET, Java, Go) or complex dependencies:

Best for: Any serverless application, compiled Lambda functions, teams wanting simplified CloudFormation syntax, local development and testing workflows.

AWS CDK (Cloud Development Kit)

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

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.

Getting Started with CloudFormation

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}"

Getting Started with Terraform

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.

Choosing Your Deployment Tool

CloudFormation CLI

Use the AWS CLI CloudFormation commands when:

SAM CLI

Use the SAM CLI when:

Terraform CLI

Use Terraform when:

SAM Transform Examples

Simple Inline Function with SAM Transform

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

Compiled Function with SAM CLI

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

Configuration Patterns

Successful Infrastructure as Code implementations with Proxylity typically follow these patterns:

Environment Separation

Use separate templates or parameter files for different environments:

Modular Templates

Break complex configurations into reusable components:

Parameter Management

Use AWS Systems Manager Parameter Store or AWS Secrets Manager for sensitive configuration:

Best Practices

Security

Operational Excellence

Performance

Advanced Patterns

Multi-Environment Deployment

Use CloudFormation StackSets or deployment pipelines to maintain consistent configurations across multiple AWS accounts and regions while allowing for environment-specific customization.

Blue-Green Deployments

Implement blue-green deployments by creating new listeners with updated configurations and gradually migrating traffic. This approach minimizes downtime and provides easy rollback capabilities.

Disaster Recovery

Design cross-region deployments using CloudFormation to ensure business continuity. Proxylity's anycast architecture simplifies failover scenarios when combined with proper IaC practices.

Migration from Manual Configuration

If you're currently managing Proxylity resources through the dashboard or API calls, migrating to Infrastructure as Code provides significant benefits:

  1. Audit existing configuration - Document your current setup through the dashboard
  2. Create templates - Convert manual configurations to CloudFormation templates
  3. Test in development - Deploy templates in a test environment first
  4. Gradually migrate - Move one component at a time to minimize risk
  5. Retire manual processes - Update team procedures to use IaC workflows

Troubleshooting Stack Failures

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.

Subscription and API key problems

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:

ReasonWhat 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.

Operations not permitted for the key or plan

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.

Getting Help

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.