Antipattern: Define multiple virtual hosts with same host alias and port number

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

In Apigee 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, there are 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 and port number of the incoming request to the list of host aliases defined by all virtual hosts to determine which virtual host handles the request.

Sample configuration for virtual hosts are shown below:

sample vhost config

Antipattern

Defining multiple virtual hosts with the same host alias and port number in the same/different environments of an organization or across organizations will lead to confusion at the time of routing API requests and may cause unexpected errors/behaviour.

Let's use an example to explain the implications of having multiple virtual hosts with same host alias.

Consider there are two virtual hosts sandbox and secure defined with the same host alias i.e., api.company.abc.com in an environment:

vhosts with same alias

With the above setup, there could be two scenarios as described in the following sections.

Scenario 1 : An API Proxy is configured to accept requests to only one of the virtual hosts sandbox 

<ProxyEndpoint name="default">
  ...
  <HTTPProxyConnection>
    <BasePath>/demo</BasePath>
    <VirtualHost>sandbox</VirtualHost>
  </HTTPProxyConnection>
  ...
</ProxyEndpoint>

In this scenario, when the client applications make the calls to specific API Proxy using the host alias api.company.abc.com, they will intermittently get 404 errors with the message:

Unable to identify proxy for host: secure

This is because the Router sends the requests to both sandboxand secure virtual hosts. When the requests are routed to sandbox virtual host, the client applications will get a successful response. However, when the requests are routed to secure virtual host, the client applications will get 404 error as the API Proxy is not configured to accept requests on secure virtual host.

Scenario 2 : An API Proxy is configured to accept requests to both the virtual hosts sandbox and secure

<ProxyEndpoint name="default">
  ...
  <HTTPProxyConnection>
    <BasePath>/demo</BasePath>
    <VirtualHost>sandbox</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
  ...
</ProxyEndpoint>

In this scenario, when the client applications make the calls to specific API Proxy using the host alias api.company.abc.com, they will get a valid response based on the proxy logic.

However, this causes incorrect data to be stored in Analytics as the API requests are routed to both the virtual hosts, while the actual requests were aimed to be sent to only one virtual host.

This can also affect the logging information and any other data that is based on the virtual hosts.

Impact

  1. 404 Errors as the API requests may get routed to a virtual host to which the API Proxy may not be configured to accept the requests.
  2. Incorrect Analytics data since the API requests get routed to all the virtual hosts having the same host alias while the requests were made only for a specific virtual host.

Best Practice

  • Don't define multiple virtual hosts with same host alias and port number in the same environment, or different environments of an organization.

  • If there's a need to define multiple virtual hosts, then use different host aliases in each of the virtual hosts as shown below:

    two vhosts

Further reading