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

Send a GET request to retrieve your NAT Gateway products.
GET {baseUrl}/v3/products/nat_gateways
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

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

Create a request with this URL:
POST {baseUrl}/v3/networkdesign/buy
Create the request Body with the configuration details.

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.

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:

: 300 milliseconds
: 300 milliseconds
: 3

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

Create a request with this URL:
POST {baseUrl}/v3/networkdesign/buy
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"}]
        }
      }
    }
  ]
}

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

​Prerequisites

​Creating a VXC between a NAT Gateway and AWS

​NAT Gateway pools

​BGP connections

​Bidirectional Forwarding Detection (BFD)

​Static routes

​Prefix lists

​Packet filters

​Autoconfiguration for CSPs

​AWS Hosted VIF

​Google Cloud

​Microsoft Azure

Prerequisites

Creating a VXC between a NAT Gateway and AWS

NAT Gateway pools

BGP connections

Bidirectional Forwarding Detection (BFD)

Static routes

Prefix lists

Packet filters

Autoconfiguration for CSPs

AWS Hosted VIF

Google Cloud

Microsoft Azure