An Edge Gateway is a virtual router for organization VDC networks. You can configure it to provide network services such as DHCP, firewall, NAT, static routing, VPN, and load balancing.

You can create an Edge Gateway in either a compact or a full configuration. The full configuration provides increased capacity and performance. The compact configuration requires less memory and fewer compute resources. All services are supported in either configuration. You can enable either configuration for high availability, which enables automatic failover of the Edge Gateway to a backup instance that is running on a separate virtual machine.

An Edge Gateway can support up to ten interfaces. These interfaces are categorized as uplinks when they connect to an external network, and internal interfaces when they connect to an organization VDC network. You must specify at least one uplink interface when you create an Edge Gateway. All uplink interfaces on an Edge Gateway must connect to an external network available in the Provider VDC that backs the organization VDC in which you are creating the Edge Gateway. Internal interfaces are created automatically when you create a routed organization VDC network that connects to an Edge Gateway.

Verify that you are logged in to the vCloud API as a system administrator.

An Edge Gateway requires an organization VDC backed by a Provider VDC that contains at least one external network.

1

Choose an organization VDC to contain the Edge Gateway.

2

Choose an external network to use for the Edge Gateway's initial uplink interface.

This external network must be one of the networks listed in the AvailableNetworks element of the Provider VDC that backs the organization VDC in which you are creating the Edge Gateway. Follow these steps to find a suitable external network.

a

Retrieve the XML representation of the organization VDC in which you are creating the Edge Gateway.

Use a request like this one:

GET https://vcloud.example.com/api/admin/vdc/44

The ProviderVdcReference element in the response contains a reference to the Provider VDC that backs this organization VDC.

<AdminVdc ...>
   ...
   <ProviderVdcReference
      type="application/vnd.vmware.admin.providervdc+xml"
      name="PVDC-Example"
      href="https://vcloud.example.com/api/admin/extension/providervdc/35"
   ...
</AdminVdc>
b

Retrieve the the XML representation of the Provider VDC.

Use a request like this one:

GET https://vcloud.example.com/api/admin/extension/providervdc/35

The AvailableNetworks element in the response lists the external networks that are available to that Provider VDC, and to all the organization VDCs that it supports.

<vmext:VMWProviderVdc ... >
   ...
   <vcloud:AvailableNetworks>
      <vcloud:Network
         type="application/vnd.vmware.admin.network+xml"
         name="VC1-VLAN48"
         href="https://vcloud.example.com/api/admin/network/297" />
      <vcloud:Network ... />
      <vcloud:Network ... />
   </vcloud:AvailableNetworks>
   ...
</vmext:VMWProviderVdc>

Choose an available external network to provide the initial interface for the new Edge Gateway. See Example: Create an Edge Gateway for more information about criteria for choosing an external network.

3

Create an EdgeGateway element.

In the GatewayInterfaces element, create a GatewayInterface element that defines an uplink interface.

Specify uplink for the InterfaceType.

Include the external network reference you retrieved in Step 2 in the Network element.

If you plan to create a NAT service or load balancer service in the Edge Gateway, you must create an IP sub-allocation for the uplink by including a SubnetParticipation element in the GatewayInterface element. IP addresses in the range you specify in this element are reserved for use by this Edge Gateway.

For information about additional elements that an EdgeGateway can contain, see Example: Create an Edge Gateway and the schema reference.

4

POST the EdgeGateway element to the URL for adding Edge Gateways to the organization VDC.

The server takes the requested action and returns an XML representation of the partially-created object. This representation includes an href attribute, properties specified in the creation request, and an embedded Task element that tracks the creation of the object. When the task completes, the object has been created, and you can use the value of the href attribute with a GET request to retrieve the XML representation of the object.

See the response portion of Example: Create an Edge Gateway.

This example adds an Edge Gateway to the organization VDC created in Add a VDC to an Organization. The uplink interface specifies one of the networks shown in Step 2b. For the purposes of this example, assume that the external network has a Configuration element that includes this information:

<Configuration>
   <IpScopes>
      <IpScope>
         ...
         <Gateway>10.147.115.190</Gateway>
         <Netmask>255.255.255.0</Netmask>
         ...
         <IpRanges>
            <IpRange>
               <StartAddress>10.147.115.129</StartAddress>
               <EndAddress>10.147.115.189</EndAddress>
            </IpRange>
         </IpRanges>
         <AllocatedIpAddresses>
            <IpAddress>10.147.115.129</IpAddress>
            <IpAddress>10.147.115.133</IpAddress>
            <IpAddress>10.147.115.132</IpAddress>
            <IpAddress>10.147.115.130</IpAddress>
         </AllocatedIpAddresses>
      ... 
      </IpScope>
   </IpScopes>
   ...
</Configuration>

You can see the values from this external network's IpScope reflected in the SubnetParticipation element of the EdgeGateway. The address range specified in the IpRange element of this GatewayInterface must be within the IpRanges of the external network, and cannot include any IP addresses listed in the external network's AllocatedIpAddresses element. You can specify a contiguous IpRange, as we do in this example, or you can include multiple IpRange elements in the IpRanges if you need more IP addresses than are available in a contiguous block.

The external network specified in the GatewayInterface created in this example becomes the default route from this Edge Gateway (UseForDefaultRoute has a value of true). The default DNS service address is inherited from the network specified as the default route.

Request:

POST https://vcloud.example.com/api/admin/vdc/44/edgeGateways
Content-Type: application/vnd.vmware.admin.edgeGateway+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<EdgeGateway
   name="theEdge"
   xmlns="http://www.vmware.com/vcloud/v1.5">
   <Description>Example Edge Gateway</Description>
   <Configuration>
      <GatewayBackingConfig>compact</GatewayBackingConfig>
      <GatewayInterfaces>
         <GatewayInterface>
            <Name>uplink1</Name>
            <DisplayName>uplink1</DisplayName>
            <Network
               href="https://vcloud.example.com/api/admin/network/297" />
            <InterfaceType>uplink</InterfaceType>
            <SubnetParticipation>
               <Gateway>10.147.115.190</Gateway>
               <Netmask>255.255.255.0</Netmask>
               <IpRanges>
                  <IpRange>
                     <StartAddress>10.147.115.155</StartAddress>
                     <EndAddress>10.147.115.165</EndAddress>
                  </IpRange>
               </IpRanges>
            </SubnetParticipation>
            <UseForDefaultRoute>true</UseForDefaultRoute>
         </GatewayInterface>
      </GatewayInterfaces>
      <HaEnabled>false</HaEnabled>
      <UseDefaultRouteForDnsRelay>false</UseDefaultRouteForDnsRelay>
   </Configuration>
</EdgeGateway>

The response is an EdgeGateway element with an embedded Task element that tracks the creation of the Edge Gateway object.

The response includes a number of Link elements that you can use to manage the new Edge Gateway. It also includes an EdgeGatewayServiceConfiguration element that contains a simple FirewallService, which drops all incoming and outgoing packets, effectively blocking all traffic through the Edge Gateway. This service is created by default if you do not specify an EdgeGatewayServiceConfiguration when you create the EdgeGateway. To remove or modify it, see Configure Edge Gateway Services.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<EdgeGateway
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="theEdge"
   id="urn:vcloud:gateway:2000"
   type="application/vnd.vmware.admin.edgeGateway+xml"
   href="https://vcloud.example.com/api/admin/edgeGateway/2000" ... >
   <Link
      rel="edit"
      type="application/vnd.vmware.admin.edgeGateway+xml"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000" />
   <Link
      rel="remove"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000" />
   <Link
      rel="up"
      type="application/vnd.vmware.admin.vdc+xml"
      href="https://vcloud.example.com/api/admin/vdc/44" />
   <Link
      rel="edgeGateway:redeploy"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000/action/redeploy" />
   <Link
      rel="edgeGateway:configureServices"
      type="application/vnd.vmware.admin.edgeGatewayServiceConfiguration+xml"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000/action/configureServices" />
   <Link
      rel="edgeGateway:reapplyServices"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000/action/reapplyServices" />
   <Link
      rel="edgeGateway:syncSyslogSettings"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000/action/syncSyslogServerSettings" />
   <Link
      rel="edgeGateway:upgrade"
      href="https://vcloud.example.com/api/admin/edgeGateway/2000/action/upgradeConfig" />
   ...
   <Tasks>
      <Task
         status="running"
         ...
         operation="Creating EdgeGateway theEdge(2000)"
         ...
      </Task>
   </Tasks>
   <Configuration>
      <GatewayBackingConfig>compact</GatewayBackingConfig>
      <GatewayInterfaces>
         <GatewayInterface>
            <Network
               type="application/vnd.vmware.admin.network+xml"
               name=""
               href="https://vcloud.example.com/api/admin/network/297" />
            <InterfaceType>uplink</InterfaceType>
            <ApplyRateLimit>false</ApplyRateLimit>
            <UseForDefaultRoute>true</UseForDefaultRoute>
         </GatewayInterface>
      </GatewayInterfaces>
      <EdgeGatewayServiceConfiguration>
         <FirewallService>
            <IsEnabled>true</IsEnabled>
            <DefaultAction>drop</DefaultAction>
            <LogDefaultAction>false</LogDefaultAction>
         </FirewallService>
      </EdgeGatewayServiceConfiguration>
      <HaEnabled>false</HaEnabled>
      <UseDefaultRouteForDnsRelay>false</UseDefaultRouteForDnsRelay>
   </Configuration>
</EdgeGateway>