Configuring virtual hosts for the Private Cloud

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

In an on-premises installation, you have complete control over virtual hosts. You can create virtual hosts for any org, in any environments, using TLS or not.

This document describes how to create a simple virtual host. That is, one that does not support TLS. For more examples, including examples on creating virtual hosts that support TLS, see Configuring TLS access to an API for the Private Cloud.

Learn more:

About host aliases

When you create the virtual host, you must specify the host alias of the virtual host. Typically this is the DNS name of the virtual host.

The Edge Router compares the Host header of the incoming request to the list of available host aliases as part of determining the API proxy that handles the request. When making a request through a virtual host, either specify a domain name that matches the host alias of a virtual host, or specify the IP address of the Router and the Host header containing the host alias.

For example, if you created a virtual host with a host alias of myapis.apigee.net on port 9001, then a cURL request to an API through that virtual host could use one of the following forms:

If you have a DNS entry for myapis.apigee.net:

curl http://myapis.apigee.net:9001/proxy-base-path/resource-path

If you do not have a DNS entry for myapis.apigee.net:
```
curl http://routerIP:9001/proxy-base-path/resource-path -H 'host:myapis.apigee.net'
```
In this form, you specify the IP address of the Router, and pass the host alias in the Host header.

Note: The curl command, most browsers, and many other utilities automatically append the Host header with the domain as part of the request, so you can actually use a curl command in the form:
```
curl http://routerIP:9001/proxy-base-path/resource-path
```

Options when you do not have a DNS entry for the virtual host

One option when you do not have a DNS entry is to set the host alias to the IP address of the Router and port of the virtual host, as routerIP:port. For example:

192.168.1.31:9001

When you make a curl command in the form below:

curl http://routerIP:9001/proxy-base-path/resource-path

This option is preferred because it works well with the Edge UI.

If you have multiple Routers, add a host alias for each Router, specifying the IP address of each Router and port of the virtual host.

Alternatively, you can set the host alias to a value, such as temp.hostalias.com. Then, you have to pass the Host header on every request:

curl -v http://routerIP:9001/proxy-base-path/resource-path -H 'Host: temp.hostalias.com'

Or, add the host alias to your /etc/hosts file. For example, add this line to /etc/hosts:

192.168.1.31 temp.hostalias.com

Then you can make a request as if you had a DNS entry:

curl -v http://myapis.apigee.net:9001/proxy-base-path/resource-path

About virtual host ports on Edge for Private Cloud 4.16.01 and later

When creating a virtual host, you specify the Router port used by the virtual host. For example, port 9001.

For Apigee for Private Cloud releases 4.16.01 and later, by default, the Router runs as the user "apigee" which does not have access to privileged ports, typically ports 1024 and below. If you want to create a virtual host that binds the Router to a protected port then you have to configure the Router to run as a user with access to those ports. See Setting up a virtual host for more.

Create virtual hosts

This section describes how to create virtual hosts for Apigee Edge for Private Cloud. Note that to create a new virtual host, you must be an organization administrator.

You can create virtual hosts for Apigee Edge for Private Cloud using either the API or the Edge UI. These are described in the following sections.

Create a virtual host using a browser

This section describes how to create a virtual host by using a browser (Edge UI only).

To create a new virtual host in the Edge UI:

Log in to the Edge management UI.
Select Admin > Virtual Hosts.
Select the environment from the drop-down list.

Edge displays a list of virtual hosts for that environment.
To create a new virtual host, select + Virtual Host.
Edge displays the Create Virtual Host form.

You can also click the name of an existing virtual host to edit it.
Define your new virtual host. Note that the Base URL field must include the protocol (ie, prefix the field's value with "http://" or "https://".)
Additionally, note that:
- There is no limit to the number of virtual hosts you can create
- TLS is optional, and can be version 1.0, 1.1, or 1.2
- The virtual host's port is configurable
Click the Create button to save your new virtual host.

Create a virtual host with the API

To create a virtual host with the API, create an XML object that defines the virtual host. For example, the following XML object defines a virtual host that uses the HTTP protocol:

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>DNS_name_or_IP:port</HostAlias>
   </HostAliases>
   <Interfaces/>
   <Port>9005</Port>
</VirtualHost>

Notice that the virtual host contains a name property. You use the value of the name property to configure an API proxy to use the virtual host.

You can then access an API proxy through this virtual host by making a request to:

http://routerIP:port/proxy-base-path/resource-path
https://routerIP:port/proxy-base-path/resource-path

Where:

http or https: If the virtual host is configured to support TLS, use HTTPS. If the virtual host does not support TLS, use HTTP.
routerIP:port is the IP address and port number of the virtual host.
proxy-base-path and resource-path are defined when you create the API proxy.

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://api.myCompany.com/proxy-base-path/resource-path
https://api.myCompany.com/proxy-base-path/resource-path

If you define the DNS entry, then you must create a host alias for the virtual host that matches the domain name of the DNS entry. The host alias must match the string that the client passes in the Host header. From the example above, you would specify a host alias of api.myCompany.com.

<VirtualHost name="myVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
</VirtualHost>

To create a virtual host that uses the HTTP protocol, perform the following:

Create the virtual host by using the Create a Virtual Host API, where ms-IP is the IP address or domain name of the Management Server node:

$ curl -X POST -H "Content-Type:application/xml" \
http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts \
-d '<VirtualHost name="newVHost">
    <HostAliases>
      <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
  </VirtualHost>' \
-u sysAdminEmail:password

Create the DNS record for the virtual host that matches the host alias.
If you have any existing API proxies, add the virtual host to the <HTTPConnection> element in the Proxy Endpoint. The virtual host is added automatically to all new API proxies. See Configuring an API proxy to use a virtual host.
Warning: All virtual hosts are automatically added to all new API proxies. Therefore, if you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.

Modifying a virtual host

To modify a virtual host, perform the following:

Update the virtual host by using the Update a Virtual Host API, where <ms-IP> is the IP address or domain name of the Management Server node. You must specify the complete definition of the virtual host in the request body, not just the elements that you want to change. In this example, you change the port number of the virtual host from 9008 to 9009:
```
curl -X PUT -H "Content-Type:application/xml" \
  http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts/vhost_name \
  -d '<VirtualHost name="newVHost">
    <HostAliases>
      <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9009</Port>
  </VirtualHost>' \
  -u email:password
```
For Edge for Private Cloud versions 4.16.01 and 4.16.05 only, If you modify an existing virtual host, and you either enable TLS or disable TLS without changing the port number, then:
1. Stop the Router:
```
/opt/apigee/apigee-service/bin/apigee-service edge-router stop
```
2. Delete any files in /opt/nginx/conf.d:
```
rm -f /opt/nginx/conf.d/*
```
3. Start the Router:
```
/opt/apigee/apigee-service/bin/apigee-service edge-router start
```
4. Repeat for all Routers.