action.skip
Megaport Documentation
Creating a NAT Gateway VXC
Copy for LLM ▼
Copy Page Content Open in ChatGPT Open in Claude Open in VS Code View Markdown
PDF

Creating a NAT Gateway VXC with the API

This topic describes the API procedure to create a Virtual Cross Connect (VXC) on a Megaport NAT Gateway (NAT Gateway). The example shows how to create a VXC to an AWS cloud service and configure BGP peering on the NAT Gateway A-End.

Prerequisites

Before you begin, obtain a valid access token. For more information, see Creating an API Key.

You also need a provisioned NAT Gateway. For more information, see Creating a NAT Gateway with the API.

Creating a VXC between a NAT Gateway and AWS

This example creates an AWS private VXC. The steps include how to:

  • get the NAT Gateway product ID
  • find the AWS location ID
  • configure a BGP connection on the NAT Gateway A-End
  • validate and order the VXC

To create the VXC, you need the productUid for the NAT Gateway.

To get the productUid for the NAT Gateway

  1. Send a GET request to retrieve your NAT Gateway products.

    GET {baseUrl}/v3/products/nat_gateways

  2. From the response, locate the productUid for the NAT Gateway you want to connect.

    This example uses this value: abc12345-1234-1234-1234-abc123456789

To find the locationId where AWS is available

  1. Get the list of all interfaces Megaport has with Cloud Service Providers (CSPs).

    GET {baseUrl}/v2/dropdowns/partner/megaports

    You can filter the response to show only interfaces from a specific cloud provider using the connectType query parameter, such as:

    GET {baseUrl}/v2/dropdowns/partner/megaports?connectType=AWS&vxcPermitted=true

  2. Search the response for a site in your preferred region.

    For this example, select a US West site with "locationId": 57.

    {
  "connectType": "AWS",
  "productUid": "d5518ee1-e915-4e3d-a4e1-a2c7e04f2fdd",
  "vxcPermitted": true,
  "companyUid": "605cb850-dfb4-4a05-a171-8bf17757b3a2",
  "companyName": "AWS",
  "title": "US West (Oregon) (us-west-2) [DZ-RED]",
  "locationId": 57
}

    To order the VXC, you need the following IDs from the response:

    • locationId - The ID of the location.
    • productUid - The port to connect to.
    • companyUid - The ID of the Cloud Service Provider (CSP).

To create the VXC

The A-End partnerConfig uses connectType: "VROUTER", and includes IP addresses and BGP connections for the NAT Gateway interface. The B-End specifies the AWS connection details.

The B-End configuration needs the following IDs from the previous step:

  • locationId – The locationId of the location
  • productUid – The productUid of the port at the location
  • OwnerUid – The companyUid of the CSP

In the request Body, you need to specify the UID of the NAT Gateway (productUid).

  1. Create a request with this URL:

    POST {baseUrl}/v3/networkdesign/buy

  2. Create the request Body with the configuration details.

Tip

To test your request before you order, use POST {baseUrl}/v3/networkdesign/validate.

Example Request Body

[
  {
    "productUid": "abc12345-1234-1234-1234-abc123456789",
    "associatedVxcs": [
      {
        "productName": "Test NAT Gateway VXC",
        "rateLimit": 100,
        "term": 12,
        "shutdown": false,
        "aEnd": {
          "partnerConfig": {
            "connectType": "VROUTER",
            "interfaces": [
              {
                "ipAddresses": ["10.0.0.1/30"],
                "bgpConnections": [
                  {
                    "peerAsn": 64512,
                    "localIpAddress": "10.0.0.1",
                    "peerIpAddress": "10.0.0.2",
                    "shutdown": false,
                    "description": "BGP to AWS",
                    "bfdEnabled": false
                  }
                ],
                "ipRoutes": []
              }
            ]
          }
        },
        "bEnd": {
          "locationId": 57,
          "ownerUid": "605cb850-dfb4-4a05-a171-8bf17757b3a2",
          "productUid": "d5518ee1-e915-4e3d-a4e1-a2c7e04f2fdd",
          "partnerConfig": {
            "connectType": "AWS",
            "type": "private",
            "ownerAccount": "123456789012"
          }
        },
        "productType": "VXC"
      }
    ]
  }
]

If the request is successful, the response includes the details of the created VXC.

{
  "message": "VXC [xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx] created.",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": [
    {
      "serviceName": "Test NAT Gateway VXC",
      "technicalServiceUid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "provisioningStatus": "DEPLOYABLE",
      "productType": "VXC",
      "rateLimit": 100,
      ...
    }
  ]
}

NAT Gateway pools

You can configure NAT Gateway pools to control how the NAT Gateway translates outgoing traffic to public IP addresses. Each pool contains IP address ranges that are used as the source addresses for translated traffic.

Note

NAT Gateway pools are only required on VXCs connecting to resources outside your private network, such as CSPs or the internet. VXCs connecting resources inside your network to the NAT Gateway do not require pool configuration.

You can configure pools on a VXC when you create it or after it is provisioned. To configure pools using the Portal, see Using NAT Gateway Pools.

BGP connections

You can configure multiple BGP connections per interface by adding a bgpConnections array to the interfaces array of the A-End partner configuration:

"bgpConnections": [
  {
    "peerAsn": 64512,
    "localIpAddress": "10.0.0.1",
    "peerIpAddress": "10.0.0.2",
    "password": "yourBgpPassword",
    "shutdown": false,
    "description": "Primary BGP session",
    "medIn": 100,
    "medOut": 100,
    "bfdEnabled": true,
    "asOverride": false,
    "importWhitelist": 1,
    "exportWhitelist": 2
  },
  {
    "peerAsn": 64513,
    "localIpAddress": "10.0.0.5",
    "peerIpAddress": "10.0.0.6",
    "shutdown": false,
    "description": "Secondary BGP session",
    "bfdEnabled": false
  }
]
Parameter Description Required Valid input
peerAsn The ASN of the remote BGP peer. Yes 1 – 4294967294
localAsn Overrides the NAT Gateway ASN for this peer. No 1 – 4294967294
localIpAddress The IPv4 address on this interface to use for the BGP peer. Yes Valid IPv4 address
peerIpAddress The IPv4 or IPv6 address of the BGP peer. Yes Valid IP address
password A shared key to authenticate the BGP peer. No 0 – 32 characters
importWhitelist Permit filter applied to inbound BGP advertisements. Must be the id of an existing prefix list. See Prefix lists. No Integer (prefix list ID)
importBlacklist Deny filter applied to inbound BGP advertisements. Must be the id of an existing prefix list. See Prefix lists. No Integer (prefix list ID)
exportWhitelist Permit filter applied to outbound BGP advertisements. Must be the id of an existing prefix list. See Prefix lists. No Integer (prefix list ID)
exportBlacklist Deny filter applied to outbound BGP advertisements. Must be the id of an existing prefix list. See Prefix lists. No Integer (prefix list ID)
shutdown Temporarily disables the BGP session without removing it. No true/false. Defaults to false.
description Description of the BGP connection. No 0 – 100 characters
medIn MED applied to all routes received on this BGP connection. No 0 – 4,294,967,295
medOut MED applied to all routes transmitted on this BGP connection. No 0 – 4,294,967,295
asPathPrependCount Number of times the local AS number is prepended on outgoing announcements. No 1 – 10
bfdEnabled Enables Bidirectional Forwarding Detection on this BGP connection. No true/false. Defaults to false.
asOverride Enables AS Override for eBGP peering. When enabled, replaces the peer’s ASN with the local ASN in the AS path. This is useful when connecting sites that share the same ASN. Only valid for eBGP connections. No true/false. Defaults to false.

Bidirectional Forwarding Detection (BFD)

The bfd configuration object applies to all BGP connections on the interface that have bfdEnabled = true.

When you enable BFD, the system automatically applies these fixed settings:

  • Transmit IntervalThe minimum time that the BGP neighbor transmits liveness detection BFD packets to the BGP neighbor.
    : 300 milliseconds
  • Receive IntervalThe minimum time that the BGP neighbor sends liveness detection BFD packets to the interface.
    : 300 milliseconds
  • MultiplierThe minimum number of BFD packets that can be missed before the BGP session is considered down.
    : 3

Note

These settings apply to all BGP connections on the VXC where BFD is enabled.

Static routes

You can configure static routes per interface by adding an ipRoutes array to the interfaces array of the A-End partner configuration:

"ipRoutes": [
  {
    "prefix": "10.1.0.0/24",
    "nextHop": "10.0.0.2",
    "description": "Route to private subnet"
  }
]
Parameter Description Required Valid input
prefix The IP prefix (IPv4 or IPv6) to route to the next hop. Yes IPv4 or IPv6 CIDR
nextHop The next hop address. Must be in the same subnet as the interface. Yes IPv4 or IPv6 address
description Description of the static route. No Max 100 characters

Prefix lists

Prefix lists are named sets of IP prefixes that you can apply to BGP connections to filter route advertisements. You reference a prefix list by its id in the BGP connection parameters importWhitelist, importBlacklist, exportWhitelist, and exportBlacklist.
For more information, see BGP connections.

For more information about prefix filtering, see Megaport NAT Gateway BGP Prefix Filtering.

The tasks in this section include how to:

  • get a summary of all prefix lists
  • create a prefix list
  • get a prefix list
  • update a prefix list
  • delete a prefix list

To get a summary of all prefix lists

Send a GET request to retrieve all prefix lists on a NAT Gateway.

Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/prefix_list_summaries

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-1234-1234-1234-abc123456789/prefix_list_summaries

Response

The response includes the ID, description, and address family for each prefix list:

{
  "message": "List prefix list summaries.",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": [
    {
      "id": 1,
      "description": "Allowed routes",
      "addressFamily": "IPv4"
    }
  ]
}

To create a prefix list

Send a POST request to the prefix lists endpoint with the configuration as the request Body.

Endpoint

POST {baseUrl}/v3/products/nat_gateways/{productUid}/prefix_lists

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.

Example Request Body

{
  "description": "Allowed routes",
  "addressFamily": "IPv4",
  "entries": [
    {
      "prefix": "10.0.0.0/8",
      "action": "permit",
      "ge": "24",
      "le": "32"
    },
    {
      "prefix": "192.168.0.0/16",
      "action": "deny"
    }
  ]
}

Response

A successful response (HTTP 200) includes the created prefix list with its assigned id.

{
  "message": "Prefix list created.",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": {
    "id": 1,
    "description": "Allowed routes",
    "addressFamily": "IPv4",
    "entries": [
      {
        "prefix": "10.0.0.0/8",
        "action": "permit",
        "ge": "24",
        "le": "32"
      },
      {
        "prefix": "192.168.0.0/16",
        "action": "deny"
      }
    ]
  }
}
Parameter Description Required Valid input
description The name used to reference this prefix list in BGP connection configuration. Yes String
addressFamily The IP address family for all entries in this list. Yes IPv4, IPv6
entries The list of prefix rules. Yes Array
entries.prefix The network address in CIDR notation. Yes IPv4 or IPv6 CIDR
entries.action The action to take for matching prefixes. Yes permit, deny
entries.ge The minimum prefix length to match (greater than or equal). No 0 – 32 (IPv4), 0 – 128 (IPv6)
entries.le The maximum prefix length to match (less than or equal). Must be >= ge if both are specified. No 0 – 32 (IPv4), 0 – 128 (IPv6)

To get a prefix list

Send a GET request. Replace {prefixListId} with the ID from the prefix list summary.

Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/prefix_lists/{prefixListId}

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.
prefixListId The unique identifier of the prefix list.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-1234-1234-1234-abc123456789/prefix_lists/1

Response

A successful response (HTTP 200) returns the prefix list details.

{
  "message": "Action completed successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": {
    "id": 1,
    "description": "Allowed routes",
    "addressFamily": "IPv4",
    "entries": [
      {
        "prefix": "10.0.0.0/8",
        "action": "permit",
        "ge": "24",
        "le": "32"
      },
      {
        "prefix": "192.168.0.0/16",
        "action": "deny"
      }
    ]
  }
}

To update a prefix list

To replace all existing entries in the list, send a PUT request with the full prefix list configuration in the request Body.

Endpoint

PUT {baseUrl}/v3/products/nat_gateways/{productUid}/prefix_lists/{prefixListId}

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.
prefixListId The unique identifier of the prefix list.

Example Request Body

{
  "description": "Allowed routes",
  "addressFamily": "IPv4",
  "entries": [
    {
      "prefix": "10.0.0.0/8",
      "action": "permit",
      "ge": "24",
      "le": "32"
    },
    {
      "prefix": "192.168.0.0/16",
      "action": "deny"
    }
  ]
}

Response

A successful response (HTTP 200) returns the updated prefix list.

{
  "message": "Action completed successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": {
    "id": 1,
    "description": "Allowed routes",
    "addressFamily": "IPv4",
    "entries": [
      {
        "prefix": "10.0.0.0/8",
        "action": "permit",
        "ge": "24",
        "le": "32"
      },
      {
        "prefix": "192.168.0.0/16",
        "action": "deny"
      }
    ]
  }
}

To delete a prefix list

Send a DELETE request to the prefix lists endpoint.

Endpoint

DELETE {baseUrl}/v3/products/nat_gateways/{productUid}/prefix_lists/{prefixListId}

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.
prefixListId The unique identifier of the prefix list.

Example Request

DELETE {baseUrl}/v3/products/nat_gateways/abc12345-1234-1234-1234-abc123456789/prefix_lists/1

Response

A successful response (HTTP 200) confirms the prefix list was deleted.

{
  "message": "Prefix List '1' deleted successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy"
}

Packet filters

Packet filters control traffic flow to and from the NAT Gateway by defining ordered rules that match packets based on protocol, source and destination addresses, and ports. Entries are evaluated in order, and the first matching rule determines the action.
For more information, see Using Packet Filters with NAT Gateway.

The tasks in this section include how to:

  • get a summary of all packet filters
  • create a packet filter
  • get a packet filter
  • update a packet filter
  • delete a packet filter

To get a summary of all packet filters

Send a GET request to retrieve all packet filters on a NAT Gateway.

Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/packet_filter_summaries

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-1234-1234-1234-abc123456789/packet_filter_summaries

Response

The response includes the ID and description for each packet filter:

{
  "message": "List packet filter summaries.",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": [
    {
      "id": 1,
      "description": "Allow web traffic"
    }
  ]
}

To create a packet filter

Send a POST request to the packet filters endpoint with the configuration as the request Body.

Endpoint

POST {baseUrl}/v3/products/nat_gateways/{productUid}/packet_filters

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.

Example Request Body

{
  "description": "Allow web traffic",
  "entries": [
    {
      "action": "permit",
      "sourceAddress": "10.0.0.0/8",
      "destinationAddress": "0.0.0.0/0",
      "ipProtocol": 6,
      "sourcePorts": "1-65535",
      "destinationPorts": "443",
      "description": "Allow outbound HTTPS"
    },
    {
      "action": "deny",
      "sourceAddress": "0.0.0.0/0",
      "destinationAddress": "0.0.0.0/0",
      "description": "Deny all other traffic"
    }
  ]
}

Response

A successful response (HTTP 200) includes the created packet filter with its assigned id.

{
  "message": "Packet filter created.",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": {
    "id": 1,
    "description": "Allow web traffic",
    "entries": [
      {
        "action": "permit",
        "sourceAddress": "10.0.0.0/8",
        "destinationAddress": "0.0.0.0/0",
        "ipProtocol": 6,
        "sourcePorts": "1-65535",
        "destinationPorts": "443",
        "description": "Allow outbound HTTPS"
      },
      {
        "action": "deny",
        "sourceAddress": "0.0.0.0/0",
        "destinationAddress": "0.0.0.0/0",
        "description": "Deny all other traffic"
      }
    ]
  }
}
Parameter Description Required Valid input
description The name for this packet filter. Yes String
entries The list of packet filter rules, evaluated in order. Yes Array
entries.action The action to take on matching packets. Yes permit, deny
entries.sourceAddress The source IP address or CIDR range. Yes IPv4 or IPv6 CIDR
entries.destinationAddress The destination IP address or CIDR range. Yes IPv4 or IPv6 CIDR
entries.ipProtocol The IP protocol number. Common values: 1 (ICMP), 6 (TCP), 17 (UDP). No Integer
entries.sourcePorts Source port or port range. Only applies to TCP and UDP. No Integer or range (for example, 80 or 1-65535)
entries.destinationPorts Destination port or port range. Only applies to TCP and UDP. No Integer or range (for example, 443 or 8080-8090)
entries.description Description of the entry. No String

To get a packet filter

Send a GET request. Replace {packetFilterId} with the ID from the packet filter summary.

Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/packet_filters/{packetFilterId}

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.
packetFilterId The unique identifier of the packet filter.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-1234-1234-1234-abc123456789/packet_filters/1

Response

A successful response (HTTP 200) returns the packet filter details.

{
  "message": "Action completed successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": {
    "id": 1,
    "description": "Allow web traffic",
    "entries": [
      {
        "action": "permit",
        "sourceAddress": "10.0.0.0/8",
        "destinationAddress": "0.0.0.0/0",
        "ipProtocol": 6,
        "sourcePorts": "1-65535",
        "destinationPorts": "443",
        "description": "Allow outbound HTTPS"
      },
      {
        "action": "deny",
        "sourceAddress": "0.0.0.0/0",
        "destinationAddress": "0.0.0.0/0",
        "description": "Deny all other traffic"
      }
    ]
  }
}

To update a packet filter

To replace all existing entries in the configuration, send a PUT request with the full packet filter configuration in the request Body.

Endpoint

PUT {baseUrl}/v3/products/nat_gateways/{productUid}/packet_filters/{packetFilterId}

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.
packetFilterId The unique identifier of the packet filter.

Example Request Body

{
  "description": "Allow web traffic",
  "entries": [
    {
      "action": "permit",
      "sourceAddress": "10.0.0.0/8",
      "destinationAddress": "0.0.0.0/0",
      "ipProtocol": 6,
      "sourcePorts": "1-65535",
      "destinationPorts": "443",
      "description": "Allow outbound HTTPS"
    },
    {
      "action": "deny",
      "sourceAddress": "0.0.0.0/0",
      "destinationAddress": "0.0.0.0/0",
      "description": "Deny all other traffic"
    }
  ]
}

Response

A successful response (HTTP 200) returns the updated packet filter.

{
  "message": "Action completed successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": {
    "id": 1,
    "description": "Allow web traffic",
    "entries": [
      {
        "action": "permit",
        "sourceAddress": "10.0.0.0/8",
        "destinationAddress": "0.0.0.0/0",
        "ipProtocol": 6,
        "sourcePorts": "1-65535",
        "destinationPorts": "443",
        "description": "Allow outbound HTTPS"
      },
      {
        "action": "deny",
        "sourceAddress": "0.0.0.0/0",
        "destinationAddress": "0.0.0.0/0",
        "description": "Deny all other traffic"
      }
    ]
  }
}

To delete a packet filter

Send a DELETE request to the packet filters endpoint.

Endpoint

DELETE {baseUrl}/v3/products/nat_gateways/{productUid}/packet_filters/{packetFilterId}

Path Parameters

Parameter Description
productUid The unique identifier of the NAT gateway product.
packetFilterId The unique identifier of the packet filter.

Example Request

DELETE {baseUrl}/v3/products/nat_gateways/abc12345-1234-1234-1234-abc123456789/packet_filters/1

Response

A successful response (HTTP 200) confirms the packet filter was deleted.

{
  "message": "Packet Filter '1' deleted successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy"
}

Autoconfiguration for CSPs

For AWS Hosted VIF, Azure, and Google Cloud, Megaport can set up IP addressing and BGP on both the NAT Gateway and the CSP side. This minimizes the amount of switching between the CSP and Megaport portals.

While the Portal handles autoconfiguration by default, you can also use the API to trigger it. The functionality is triggered when the interfaces key in partnerConfig does not exist or is null.

To configure BGP peering for CSPs

  1. Create a request with this URL:

    POST {baseUrl}/v3/networkdesign/buy

  2. Create the request Body with the configuration details. Templates for the most popular CSPs are available below.

AWS Hosted VIF

{
  "productUid": "{{natGatewayUid}}",
  "associatedVxcs": [
    {
      "productName": "Test AWS VIF VXC",
      "rateLimit": 100,
      "term": 12,
      "aEnd": {
        "partnerConfig": {
          "connectType": "VROUTER"
        }
      },
      "bEnd": {
        "productUid": "{{awsPortUid}}",
        "partnerConfig": {
          "connectType": "AWS",
          "type": "private",
          "ownerAccount": "{{yourAWSAccountNumber}}"
        }
      }
    }
  ]
}

Google Cloud

{
  "productUid": "{{natGatewayUid}}",
  "associatedVxcs": [
    {
      "productName": "Test Google VXC",
      "rateLimit": 100,
      "term": 12,
      "aEnd": {
        "partnerConfig": {
          "connectType": "VROUTER"
        }
      },
      "bEnd": {
        "productUid": "{{googlePortUid}}",
        "partnerConfig": {
          "connectType": "GOOGLE",
          "pairingKey": "{{googlekey}}"
        }
      },
      "productType": "VXC"
    }
  ]
}

Microsoft Azure

{
  "productUid": "{{natGatewayUid}}",
  "associatedVxcs": [
    {
      "productName": "Azure Primary VXC",
      "rateLimit": 200,
      "aEnd": {
        "partnerConfig": {
          "connectType": "VROUTER"
        }
      },
      "bEnd": {
        "productUid": "{{azurePortUid}}",
        "innerVlan": 12,
        "partnerConfig": {
          "connectType": "AZURE",
          "serviceKey": "{{azureServiceKey}}",
          "peers": [{"type": "private"}]
        }
      }
    }
  ]
}

Tip

To see all options for the requests used in this example, see https://dev.megaport.com.