Configuring Virtual Hosts FAQ

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

Edge Cloud customers can now create, modify, and delete virtual hosts. Previously, these actions had to be performed by Apigee Edge Support.

Who can configure a virtual host in Edge Cloud?

Only a Cloud customer with a paid account can create, modify, and delete a virtual host. The user creating the virtual host must be in the role of organization administrator, or in a custom role with permissions to modify a virtual host. Users in other roles do not have authorization to create virtual hosts.

The custom role requires GET, PUT and DELETE permissions on /environments/*/virtualhosts, or any of its parent resources. See Creating roles with the API for more.

What if I have an existing virtual host created by Apigee?

Existing Edge Cloud customers already have virtual hosts created by Apigee. You can now modify those virtual hosts.

However, review the requirements for modifying a virtual host at Configuring virtual hosts for the Cloud before you make any changes. For example, if your existing virtual host is configured to use a port other than 443, you cannot change the port number or the TLS setting. That means you cannot change the TLS setting from enabled to disabled, or from disabled to enabled.

What port can I use in a virtual host in the Cloud?

You can only use port 443 in a virtual host in the Cloud. You cannot use port 80 or any other port.

Why can't I use port 80 in a virtual host in the Cloud?

We encourage Apigee customers to move away from utilizing port 80 virtual hosts for API runtime traffic for the reason that port 80 is not secure. Secondly, because we are not able to validate the ownership of domains, port 80 virtual hosts cannot be made self serviceable for Cloud. Changes to the port 80 virtual hosts is considered a non-standard and as such, Apigee Edge Support reserves the rights to decline such changes.

Is TLS required on all new virtual hosts in the Cloud?

To create a virtual host, you must enable TLS on the virtual host. That means you must first create a keystore with the TLS cert and key before creating the virtual host.

You must have a cert signed by a trusted entity, such as Symantec or VeriSign. You cannot use a self-signed cert, or leaf certificates signed by a self-signed CA.

See Configuring virtual hosts for the Cloud for more.

Can I pin the Apigee free trial cert?

For security reasons, Apigee free trial certificates expire every three months. At the end of that three months, Apigee rotates the expiring cert with a new cert. Therefore, Apigee does not recommend or support pinning the free trial certificate.

Can I update the TLS cert used by a virtual host?

If you have a virtual host with an expiring TLS cert, then you can update the virtual host to use a different keystore that contains a valid cert.

What is a reference?

A reference is a variable that contains the name of the keystore. To change the keystore used by a virtual host, you update the reference variable, not the virtual host itself.

Older virtual hosts on Apigee Edge might not be configured to use references. In this case, you must request Apigee Edge Support to update the virtual host to use a reference. Do not update a virtual host yourself to change it to use a reference.

How do I determine if my virtual host uses a reference?

To see information about a specific virtual host, use the Get Virtual Host API:

curl -X GET -H "accept:application/xml" \
  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
  -u orgAdminEmail:pWord

where vhost_name is the name of the virtual host. For example, you can specify the vhost_name as "secure" to see the configuration of the default secure virtual host:

<VirtualHost name="secure">
    <HostAliases>
        <HostAlias>orgname-prod.apigee.net</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>443</Port>
    <Properties/>
    <SSLInfo>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <Enabled>true</Enabled>
        <KeyAlias>freetrial</KeyAlias>
        <KeyStore>ref://freetrial</KeyStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Notice that in this example, the value of the <KeyStore> element in the response begins with ref://. That prefix signifies that the keystore use a reference.

If the value of the <KeyStore> element is a string literal, then it does not use a reference. For example:

<KeyStore>mykeystore</KeyStore>

Do not update a virtual host yourself to change it to use a reference. You must request Apigee Edge Support to update the virtual host to use a reference. After Apigee updates the virtual host to use a reference, you can then change the keystore by updating the reference variable.

See Configuring virtual hosts for the Cloud for more.

How do I create a virtual host?

Use the following procedure to create the virtual host:

  1. Create a DNS entry and CNAME record for your publicly facing domain that points to [org]-[environment].apigee.net. See "About host aliases and DNS names" at About virtual hosts for more.
  2. Create and configure a keystore by using the procedure as described in Creating keystores and truststore using the Edge UI.
  3. Upload your cert and key to the keystore.
  4. Create a reference to the keystore as described in Configuring virtual hosts for the Cloud.
  5. Create the virtual host by using the Create a Virtual Host API as described in Configuring virtual hosts for the Cloud. Make sure to specify the correct keystore reference.
  6. If you have any existing API proxies, add the virtual host to the <HTTPConnection> element in the ProxyEndpoint. The virtual host is added automatically to all new API proxies. See Configuring an API proxy to use a virtual host.

Can I ask Apigee to block TCP ports 80, 443, or 15999 on Apigee Edge Cloud?

Since our customers configure Virtual Hosts on TCP port 443 and sometimes on TCP port 80 (although using port 80 is not recommended), we cannot block these ports as doing so would lead to failure of all API runtime traffic.

TCP port 15999 is used internally in Cloud to determine if the Routers are healthy or not and therefore should not be blocked either as that can cause unforeseen API runtime impact.