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:

• Version Control - Track changes to your network configuration alongside your application code
• Reproducibility - Deploy identical configurations across development, staging, and production environments
• Collaboration - Use standard development workflows like pull requests for infrastructure changes
• Automation - Integrate infrastructure deployment into your CI/CD pipelines
• Documentation - Your infrastructure configuration serves as living documentation

CloudFormation Resource Types Reference

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

Core Resources

Configuration Types

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:

• Simplified Resources - AWS::Serverless::Function, AWS::Serverless::StateMachine, and others reduce boilerplate
• Powerful Macros - Fn::ForEach for loops, enhanced Fn::FindInMap capabilities
• Template Decomposition - AWS::Serverless::Application and Fn::Transform includes for modular templates

SAM CLI for Dependency Management

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

• Automatic Building - Compiles and packages Lambda functions from source code
• Dependency Resolution - Handles package management for various runtimes
• Local Development - Test Lambda functions locally with sam local
• Simplified Deployment - Manages S3 uploads and CloudFormation packaging automatically

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 Proxylity resources using familiar programming languages like TypeScript, Python, Java, and C#. CDK ultimately compiles to CloudFormation, so all Proxylity custom resource types are fully supported.

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:

• Terraform Registry - Browse documentation and examples
• GitHub Repository - Source code, issues, and contributions

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:
            RoleArn: !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:

• Working with inline Lambda functions (using ZipFile or InlineCode)
• All resources are standard AWS types or custom resources
• No compiled dependencies or complex packaging requirements
• Integration with existing CloudFormation-based CI/CD pipelines

SAM CLI

Use the SAM CLI when:

• Working with compiled Lambda functions (.NET, Java, Go, Rust)
• Lambda functions have external dependencies requiring packaging
• You want to use SAM's simplified resource types (AWS::Serverless::Function)
• You need local development and testing capabilities
• Templates use SAM macros like Fn::ForEach or Fn::Transform

Terraform CLI

Use Terraform when:

• You're already using Terraform for other infrastructure
• You need multi-cloud deployments or cloud-agnostic configurations
• You prefer HCL syntax over JSON/YAML
• You want to leverage Terraform's state management and planning capabilities
• You need to integrate with existing Terraform workflows and modules

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:
            RoleArn: !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:

• Development - Permissive client restrictions, minimal destinations
• Staging - Production-like configuration with test data
• Production - Strict security, comprehensive monitoring, multiple destinations

Modular Templates

Break complex configurations into reusable components:

• Network template - Listeners and client restrictions
• Processing template - Lambda functions and destinations
• Security template - IAM roles and policies

Parameter Management

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

• API keys and service tokens
• WireGuard private keys
• Environment-specific settings

Best Practices

Security

• Use least-privilege IAM roles - Grant only the minimum permissions needed for each destination
• Restrict client access - Always configure ClientRestrictions to limit traffic sources
• Rotate keys regularly - Especially important for WireGuard peer configurations
• Use AWS Secrets Manager - Store sensitive configuration like API keys securely

Operational Excellence

• Tag all resources - Use consistent tagging for cost tracking and organization
• Monitor deployments - Set up CloudWatch alarms for deployment failures
• Test configurations - Validate templates in development before production deployment
• Document dependencies - Clearly document relationships between templates and stacks

Performance

• Optimize batching - Configure appropriate batch sizes for your use case
• Monitor latency - Track packet processing times and destination performance
• Scale destinations - Ensure Lambda functions and other destinations can handle traffic volume
• Use multiple destinations - Distribute load across multiple processing endpoints when needed

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

Getting Help

Need assistance with Infrastructure as Code implementation?

• Documentation - Each resource type has comprehensive reference documentation
• Getting Started Guide - Check the Getting Started guide for complete working examples
• Example Repository - Browse the Proxylity Examples Repository for real-world CloudFormation templates and SAM applications
• Support - Contact our team for architecture guidance and best practices
• Community - Share patterns and solutions with other Proxylity users

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.