Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

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 virtual host for an on-premises deployment of Edge. To create a virtual host for a Cloud deployment of Edge, see Configuring virtual hosts for the Cloud.

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

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

As of Edge for Private Cloud version 4.16.01, you must specify a host alias when creating a virtual host. In releases previous to 4.16.01, the host alias was optional. For more on setting the host alias, see Configuring TLS access to an API for the Private Cloud.

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 Updating an API proxy after creating a virtual host in About virtual hosts.
    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.

Help or comments?