Configuring virtual hosts for the Private Cloud

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.

    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.

Creating a simple virtual host

To create a virtual host that does not support TLS, 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:

  1. 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
    
  2. Create the DNS record for the virtual host that matches the host alias.
  3. 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.

Modifying a virtual host

To modify a virtual host, perform the following:

  1. 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
  2. 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.

Send feedback about...

Apigee Docs