Connecting your AWS Account

First, subscribe to UDP Gateway in the AWS Marketplace. Once subscribed, click the "Setup Product" button, then the "Setup Account" button which will take you to the Proxylity web application.

Account Configuration from S3

For each subscribed AWS account, Proxylity maintains an S3 object in each region containing the specific configuration information needed to use Proxylity CloudFormation custom resources. This object contains your account's:

• Service Token ARN - The ARN for Proxylity's service role that handles custom resource operations
• External ID - A unique identifier required in trust policies for security
• API Key ARN - The Secrets Manager ARN containing your API key

The exact S3 location is provided in your Proxylity account dashboard and follows the pattern:

s3://proxylity-config-${AWS::Region}/${AWS::AccountId}/customer-config.json

This S3 object is automatically created and managed by Proxylity, so you don't need to create it manually or attempt to modify it. Access to read the object is limited to the associated AWS account only.

CloudFormation Mappings Configuration

The recommended approach is to retrieve this configuration during stack deployment and populate CloudFormation Mappings. Here's the actual mapping structure from the dns-filter example:

  "Mappings": {
    "ProxylityConfig": {
      "Fn::Transform": {
        "Name": "AWS::Include",
        "Parameters": {
          "Location": {
            "Fn::Sub": "s3://proxylity-config-${AWS::Region}/${AWS::AccountId}/customer-config.json"
          }
        }
      }
    }
  }

This uses CloudFormation's Fn::Transform with AWS::Include to dynamically import the account configuration from the S3 object at deployment time, making the configuration values available throughout your template via Fn::FindInMap.

Best Practice: Infrastructure as Code with Destination-Specific Roles

While customers may create account-level IAM roles to give UDP Gateway access to resources, we strongly recommend using Infrastructure as Code (IaC) to deploy roles specific to each destination with only the permissions needed. This follows the principle of least privilege and provides better security and maintainability.

Each destination should have its own IAM role with minimal permissions - for example, lambda:InvokeFunction for Lambda destinations, sns:Publish for SNS destinations, etc.

Example IAM Role Configuration

Here's an example CloudFormation snippet for a Lambda destination role using the mapping configuration:

{
  "ProxylityDestinationRole": {
    "Type": "AWS::IAM::Role",
    "Properties": {
      "AssumeRolePolicyDocument": {
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {
            "AWS": { "Fn::FindInMap": ["ProxylityConfig", "Account", "ServiceTokenArn"] }
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": { "Fn::FindInMap": ["ProxylityConfig", "Account", "ExternalId"] }
            }
          }
        }]
      },
      "Policies": [{
        "PolicyName": "LambdaInvokePolicy",
        "PolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [{
            "Effect": "Allow",
            "Action": "lambda:InvokeFunction",
            "Resource": { "Fn::GetAtt": ["YourLambdaFunction", "Arn"] }
          }]
        }
      }]
    }
  }
}

Multi-Region Best Practices

For global deployments, consider using region-specific destination ARNs. This allows Proxylity to route traffic to the closest region, reducing latency and avoiding cross-region dependencies.

When using multi-region destinations with a single global IAM role, the role must provide permissions for all the necessary regions. A simple approach is to "wildcard" the regions and use a hard-coded resource name in the Resource property of the IAM policy statements.

Here's an example from the dns-filter example:

"Statement": [
  {
    "Sid": "Lambda",
    "Effect": "Allow",
    "Action": [
      "lambda:InvokeFunction"
    ],
    "Resource": [
      {
        "Fn::Sub": "arn:aws:lambda:*:${AWS::AccountId}:function:dns-filter"
      },
      {
        "Fn::Sub": "arn:aws:lambda:*:${AWS::AccountId}:function:dns-filter:*"
      }
    ]
  }
]

A similar approach using hard-coded function names and permissions scoped to regional ARNs is demonstrated in the packet-counter-multi-region example.