About virtual hosts

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

In Edge, a Router handles all incoming API traffic. That means all HTTP and HTTPS requests to an API proxy are first handled by an Edge Router.

A virtual host lets you host multiple domain names on a server. For Edge, the server corresponds to an Edge Router. By defining multiple virtual hosts on a Router, the Router can handle API requests to multiple domain names.

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

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

The first virtual host handles HTTPS requests on the domain domainName1 and the second 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.

Note: cURL commands, browsers, and many other utilities automatically set the Host header with the domain of the request. If for any reason your app is not setting the Host header automatically, you must set it manually.

About virtual host definitions

Virtual hosts contain the following information:

The internal 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. The Host header of an API proxy requests must contain the host alias of the virtual host.
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

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. For example:
```
https://apis.acme.com/characters
```
{resource-path} the path to a resource accessible through the API proxy. For example:
```
https://apis.acme.com/characters/coyote
https://apis.acme.com/characters/roadrunner
```

About virtual hosts in Edge for the Cloud

Each Edge organization automatically includes 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 Apigee-provided 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
prod	secure	`{org-name}-prod.apigee.net`	443	Yes
test	default	`{org-name}-test.apigee.net`	80	No
test	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}

Apigee paid plans: A domain name containing "apigee.net" may not be what you want to expose to your customers. You can use a DNS entry and CNAME record to map a domain name to your organization on Edge. You 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.

Here's an example of a custom domain in Edge:

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

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 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}

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

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 in 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 in Edge for Private Cloud

As with Edge for 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.

Host aliases and wildcards

You can include the "*" wildcard character in the host alias. The "*" wildcard character can only be at the start (preceding the first ".") of the host alias, and cannot be mixed with other characters.

The following is an example of a valid host alias using a wildcard:

*.example.com

The following examples are invalid:

  www.*.example.com
  w*.example.com

Using a wildcard in a virtual host alias lets API proxies handle calls addressed to multiple subdomains such as alpha.example.com, beta.example.com, or live.example.com. Using a wildcard alias also helps you use fewer virtual hosts per environment to stay within product limits, since a virtual host with a wildcard counts as only one virtual host.

The TLS cert for the virtual host must have a matching wildcard in the CN name of the cert. For example, *.example.com.

About virtual host properties

In Edge, a virtual host is represented by an XML object. For example, the following XML object defines a virtual host:

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

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 Edge for the Private Cloud, the list of available 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.

For more on creating virtual hosts for your specific version of Edge, see: