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.
- About virtual hosts
- Configuring virtual hosts
- Configuring TLS
- Keystores and Truststores
- Configuring TLS access to an API for the Private Cloud
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:
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
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:
When you make a
curl command in the form below:
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:
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:
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:
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
From the example above, you would specify a host alias of
<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
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.
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
Stop the Router:
/opt/apigee/apigee-service/bin/apigee-service edge-router stop
Delete any files in
rm -f /opt/nginx/conf.d/*
Start the Router:
/opt/apigee/apigee-service/bin/apigee-service edge-router start
- Repeat for all Routers.