About virtual hosts

In Edge, a Router handles all incoming API traffic. That means all HTTP and HTTPS requests to an Edge API proxy are first handled by an Edge Router. Therefore, API proxy request must be directed to the IP address and open port on a Router.

A virtual host lets you host multiple domain names on a single server or group of servers. For Edge, the servers correspond to Edge Routers. By defining virtual hosts on a Router, you can handle requests to multiple domains.

A virtual host on Edge defines a protocol (HTTP or HTTPS), along with a Router port and a host alias. The host alias is typically a DNS domain name that maps to a Router's IP address.

For example, the following image shows a Router with two virtual host definitions:

In this example, you have two virtual host definitions. One handles HTTPS requests on the domain domainName1, the other handles HTTP requests on domainName2.

On a request to an API proxy, the Router compares the Host header of the incoming request to the list of host aliases defined by all virtual hosts to determine which virtual host handles the request.

About virtual host definitions

When you create a virtual host, you must specify the following information:

  • The name of the virtual host. You use that name to reference the virtual host in your API proxies and when configuring the virtual host.
  • The host alias of the virtual host. Typically the host alias is the DNS domain name that maps to the IP address on the Router.
  • An open port on the Router.
  • Whether TLS (HTTPS access) is enabled or not (HTTP access).

For example, you specify the following information when you create a virtual host:

  • name = myvhost
  • host alias = apis.acme.com
  • port = 443
  • TLS is enabled

For example, based on the setting above for the virtual host, a request to an API proxy uses the form:

https://apis.acme.com/{proxy-base-path}/{resource-path}

where:

  • {proxy-base-path} is defined when you create an API proxy and is unique for each API proxy.
  • {resource-path} the path to a resource accessible through the API proxy.

About virtual hosts in Edge for the Cloud

In Edge for the Cloud, when you first create an Edge organization, Apigee automatically created two environments (test and prod), two virtual hosts in each environment (default and secure), and DNS records for each host alias.

The host alias of each virtual host contains the name of the organization and environment, as shown in the following table:

Environment Virtual host name Host alias Port TLS enabled
prod default {org-name}-prod.apigee.net 80 No
secure {org-name}-prod.apigee.net 443 Yes
test default {org-name}-test.apigee.net 80 No
secure {org-name}-test.apigee.net 443 Yes

For example, the default domain name of an organization called "myorg" in the prod environment is "myorg-prod.apigee.net". Therefore, to access an API proxy in that organization, you use a URL in the form:

http://myorg-prod.apigee.net/{proxy-base-path}/{resource-path}
https://myorg-prod.apigee.net/{proxy-base-path}/{resource-path}

However, a domain name containing "apigee.net" may not be what you want to expose to your customers. Paid Apigee customers can use a DNS entry and CNAME record to map a domain name to your organization on Edge. They must also create a virtual host with the host alias set to that domain name. This lets developers access your API through a domain specific to your company.

For example:

https://apis.acme.com/{proxy-base-path}/{resource-path}

See About host aliases and DNS names below for more.

About virtual hosts on Edge for Private Cloud

When you install Apigee Edge for Private Cloud, there are no default organizations, environments, or virtual hosts created for you. After you complete the Edge installation process, your first action is typically to create an organization, environment, and virtual host through the "onboarding" process.

To perform onboarding, run the following command on the Edge Management Server node:

/opt/apigee/apigee-service/bin/apigee-service apigee-provision setup-org -f configFile

where configFile contains the information necessary to create a user, organization, environment, and virtual host.

For example, you create:

  • A user of your choosing to function as the organization administrator
  • An organization named example
  • An environment in the organization named prod
  • A virtual host in the environment named default that allows HTTP access on port 9001
  • A host alias of the DNS name used to access the Router, or the IP address of the Router and port of the virtual host in the form IP:9001.

You can later add any number of organizations, environments, and virtual hosts to your on-premises version of Edge. For more information, see:

Virtual hosts are opened on the Edge Router. Therefore, you have to ensure that the port that you specify for the virtual host is open on the Router. You can use a command in the form below to open a port:

iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 9001 -j ACCEPT --verbose

After running that command, you can access your APIs by using a URL in the form:

http://<router-ip>:9001/{proxy-base-path}/{resource-path}

Note that this URL uses the IP address of the Router and the virtual host port on the Router to access your APIs. Typically, you do not publish your APIs to customers with an IP address and port number. Instead, you define a DNS entry for the router and port. For example:

http://myAPI.myCo.com/{proxy-base-path}/{resource-path}

When you define the DNS entry, then you also must create a virtual host with a host alias that matches the domain name of the DNS entry. From the example above, you would specify a host alias of myAPI.myCo.com when you create the virtual host.

See About host aliases and DNS names below for more.

About host aliases and DNS names

One property that you set for a virtual host is the host alias. The host alias is typically the DNS name of the virtual host. How you set the host alias depends on your type of Edge installation: Cloud or Private Cloud.

Host aliases and DNS names for Edge for the Cloud

In Edge for the Cloud, when you first create an Edge organization, Apigee automatically creates two environments (test and prod), two virtual hosts in each environment (default and secure), and DNS records for each virtual host.

The host alias of the virtual hosts contains the name of the organization and environment. Therefore, a request through a virtual host has the form:

  • http://{org-name}-prod.apigee.net/{proxy-base-path}/{resource-path}
  • https://{org-name}-prod.apigee.net/{proxy-base-path}/{resource-path}
  • http://{org-name}-test.apigee.net/{proxy-base-path}/{resource-path}
  • https://{org-name}-test.apigee.net/{proxy-base-path}/{resource-path}

Typically, you want to create virtual hosts that use your domain name, rather than use the default apigee.net domain. To do so, you must first create your own DNS entry and CNAME record.

The following figure shows a typical configuration for how Edge processes an API request:

In this example:

  • api.acme.com is your desired domain name.
  • You define a DNS entry and CNAME record to point api.acme.com to acme-prod.apigee.net.
  • The request contains the Host header which the Router uses to determine the virtual host that handles the request.

In this example, you specify the following information in a virtual host definition:

  • name = myvhost
  • host alias = apis.acme.com
  • port = 443
  • Enable TLS access

See Configuring virtual hosts for the Cloud for more.

Host aliases and DNS names for Edge for Private Cloud

Like with the Cloud, you create virtual hosts that use your own domain name for the host alias. You then create your own DNS entry and CNAME record to access those virtual hosts.

One of the differences between Cloud and Private Cloud is that in the Cloud Apigee automatically created DNS names for your organizations, in the form:

  • name=default: http://{org-name}-{env-name}.apigee.net (Router port 80)
  • name=secure: https://{org-name}-{env-name}.apigee.net (Router port 443)

In Edge for the Private Cloud, you have to create the DNS entries to the IP address and port of your Router.

For example, you specify this information in a virtual host definition:

  • name = myvhost
  • host alias = apis.acme.com
  • port = 9001
  • Enable TLS access

The following figure shows a typical configuration for how Edge processes an API request:

In this example:

  • api.acme.com is your desired domain name.
  • You define a DNS entry and CNAME record to point api.acme.com to the IP address and port of the Router.
  • The request contains the Host header which the Router uses to determine the virtual host that handles the request.

See Configuring virtual hosts for the Private Cloud for more.

About virtual host properties

To create a virtual host, create an XML object that defines the virtual host. For example, the following XML object defines a virtual host.

The list of properties that you can set is based on whether you are using Edge for the Cloud or Edge for the Private Cloud. If you are using eEdge for the Private Cloud, the list of avialable properties is also dependent on your version of Edge. For a complete description of all properties of a virtual host, see Virtual host property reference:

<VirtualHost name="vhostName">
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <!-- Private Cloud only -->
        <Interface>interfaceName</Interface>
    <Port>portNumber</Port>
    <BaseURL>http://myCo.com<</BaseUrl>
    <OCSPStapling>off</OCSPStapling>
    <RetryOptions/>
   <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">timeout</Property>
        <Property name="keepalive_timeout">timeout</Property>
        <Property name="proxy_request_buffering">onOff</Property>
        <Property name="proxy_buffering">onOff</Property>
        <Property name="ssl_protocols">protocolList</Property>
        <Property name="ssl_ciphers">cipherList</Property>
    </Properties>
</VirtualHost>

A virtual host has several properties that you set when you create it. The most important are:

Property Description
name Use the virtual host name to reference the virtual host in an API proxy or in an API call.
host alias Typically the DNS name of the virtual host.

The host alias must be unique across all organizations and environments.

port The Router port of the virtual host. All requests through the virtual host go through a specific Router port. For example, port 443 for TLS access over HTTPS and port 80 for HTTP access.

Note: Cloud customers can only create TLS-enabled virtual hosts on port 443.

SSLInfo (TLS) For a virtual host that supports TLS, the keystore containing the TLS cert and key, key alias, and any other TLS information.

Note: Cloud customers can only create TLS-enabled virtual hosts on port 443.