You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/hybrid/v1.9/base-path-routing). info A Cloud customer with a paid account can create a virtual host in an organization. > [!NOTE] > **Note:** **Virtual hosts for Edge for the Cloud > require that you enable TLS. For information about TLS, see > [About TLS/SSL](https://docs.apigee.com/api-platform/system-administration/about-ssl).** > [!WARNING] > **Caution:** Apigee does not support static virtual host IPs for northbound Apigee Edge traffic. Northbound refers to traffic that moves from clients to Apigee. Apigee recommends that you do not try to allowlist or otherwise pin specific northbound IPs (or their mapped DNS names). Note that Apigee is not responsible for sending announcements or notifications when changes occur to your northbound IPs. - [About virtual hosts](https://docs.apigee.com/api-platform/fundamentals/virtual-hosts) - [Configuring virtual hosts](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts) - [Configuring TLS](https://docs.apigee.com/api-platform/system-administration/configuring-ssl) - [Keystores and Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores) ## Who can create and modify virtual hosts in the Cloud Virtual host creation and modification is available to paid accounts only in Edge Cloud. 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. For example, paid customers can: - Enable one-way and two-way TLS - Specify the keystore/truststore used by the virtual host Free and trial accounts cannot create or modify virtual hosts and are limited to the virtual hosts created for them at Edge registration time. For more information on Edge pricing plans, see . > [!NOTE] > **Note:** Free and trial accounts cannot create or modify virtual hosts and are limited to the virtual hosts created for them at Edge registration time. Instead, Apigee automatically provides a TLS certificate and private key to support HTTPS on a secure virtual host so that trial customers can get started developing and testing APIs. Trial customers are allowed to use one-way TLS to API proxies hosted on the \*.apigee.net domain. For more information on Edge pricing plans, see . ## Requirements for configuring a virtual host for the Cloud The following table summarizes the requirements for creating a virtual host: | **Category** | **Requirement** | **Description** | |---|---|---| | Account type | Paid | Free and trial accounts cannot create or modify virtual hosts. | | User role | organization admin | Only an org admin can create a virtual host, or a user in a custom role that has permissions to modify a virtual host. | | Number of virtual hosts | 20 maximum | You are limited to a maximum of 20 virtual hosts per organization/environment in the Cloud. **Note**: There is no limit to the number of virtual hosts in the Private Cloud. Most organizations/environments use two virtual hosts: one for HTTP and one for HTTPS access. You might need additional virtual hosts if your organization/environment allows access using different domain names. | | Base URL | Includes the protocol | When defining the base URL for the virtual host, either in the UI or with the API, you must specify the protocol (ie, "http://" or "https://") as part of the URL. | | Port | 443 | You can only create a virtual host on port 443. Note that you can create multiple virtual hosts on port 443 as long as they have unique host aliases and all support TLS. | | TLS | Required | You can only create a virtual host that supports TLS over HTTPS. You must have already created a keystore, and optionally a truststore, containing your TLS cert and key. You must have a cert signed by a trusted entity, such as Symantec or VeriSign. You cannot use a self-signed cert.
> [!NOTE] > **Note:**If you have a paid Edge for Cloud account and do not yet have a TLS cert and key, you can create a virtual host that uses the Apigee free trial cert and key. If you require HTTP access, contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). | | TLS protocol | TLS 1.2 | Edge in the Cloud supports TLS version 1.2 only. | | Host alias | Unique in the organization and environment | The host alias does not exist for another organization/environment combination. | | Domain name | Owned by customer | You must own the domain name specified in the virtual host. Edge checks to make sure that the domain name, as defined by the host alias, matches the metadata in the TLS cert. Specifically, Edge checks the following information in the cert: - CN - Common Name - SAN - Subject Alternative Name Wildcards are allowed in the SAN or CN, for example, `*.myco.net`. Edge also validates that the cert has not expired. | | Client app SNI support | All client apps accessing the virtual host must support SNI. | SNI support is required by all apps. | ## Create a virtual host using a browser Most of the examples in this section use the Edge API to create or modify virtual hosts, but you can create a virtual host in the Edge UI. > [!NOTE] > **Note**: You cannot create a virtual host using the Classic Edge UI. To create a virtual host using the Edge UI: 1. Sign in to [apigee.com/edge](https://apigee.com/edge). 2. Select **Admin \> Virtual Hosts**. 3. Select the environment, such as **prod** or **test**. 4. Select **+ Virtual Host** to create a virtual host or select the name of an existing virtual host to edit it. 5. See the table above for detailed information on populating the virtual host fields. ## Defining a virtual host for one-way TLS An XML object that defines the virtual host. For example, the following XML object defines a virtual host for one-way TLS: ``` api.myCompany.com 443 true false ref://myTestKeystoreRef myKeyAlias ``` In this definition you: - Specify the **name** as **myTLSVHost**. Use the name to reference the virtual host in an API proxy or in an API call. - Specify the **host alias** as **api.myCompany.com**. This is the publicly facing domain used to access your APIs as defined by a DNS definition and CNAME record. - Specify the **port** number as **443**. If omitted, by default the port is set to 443. - Enable TLS as required. The `` element is set to true to enable one-way TLS, and the and `` elements specify the keystore and key alias used by the TLS connection. To enable two-way TLS, set `` to true, and specify a truststore using the `` element. The truststore holds the client's certificate issuer and the certificate's CA chain, which is required. **Note:** Because Edge originally supported SSL, the tag that you use to configure TLS is named ``. Note that there are additional properties that you can set in the virtual host. For a reference for all properties, see [Virtual host property reference](https://docs.apigee.com/api-platform/fundamentals/virtual-host-property-reference). ### Deciding how to specify the keystore and truststore name in the virtual host When configuring a virtual host to support TLS, you specify a keystore by using a *reference*. A reference is a variable that contains the name of the keystore or truststore, rather than specifying the keystore or truststore name directly, as shown below: ``` true false ref://myTestKeystoreRef myKeyAlias ``` The advantage to using a reference is that you can change the value of the reference to change the keystore used by the virtual host, usually because the cert in the current keystore is expiring in the near future. Changing the value of the reference does not require you to restart the Edge Router. See [Working with references](https://docs.apigee.com/api-platform/system-administration/working-references) for more on creating and modifying references. You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore. > [!WARNING] > **Warning:** Alternatively, you can use a literal keystore name in the virtual host. However, if you ever modify the virtual host to change the keystore name, you have to restart the Edge Routers, meaning you have to contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). **Apigee > strongly recommends that you use references to keystores and truststores in a virtual host and do > not use direct names.** ### Restrictions in using references to keystores and truststore You must take into account the following restriction when using references to keystores and truststores: - You can only use keystore and truststore references in virtual hosts if you support SNI and you terminate SSL on the Apigee Routers. - If you have a load balancer in front of the Apigee Routers, and you terminate TLS on the load balancer, then you cannot use keystore and truststore references in virtual hosts. ## Defining a virtual host for two-way TLS > [!IMPORTANT] > **Important:** Public Certificate Authorities (CAs) are discontinuing the inclusion of the `clientAuth` Extended Key Usage (EKU) in latest publicly-trusted SSL/TLS certificates. This industry-wide change affects Apigee mutual TLS (mTLS) configurations in [Apigee platform](https://login.apigee.com/login). > > > Apigee requires the `clientAuth` EKU to be present in client certificates for mTLS handshakes. Without this EKU, mTLS connections will fail for both northbound (client to Apigee) and southbound (Apigee to backend) traffic. For a detailed explanation of the issue, timelines, and recommended solutions, refer to this [blog post](https://discuss.google.dev/t/navigating-the-industry-shift-in-client-authentication-for-apigee-mtls/289627). To enable two-way TLS, set the `` element to `true`, and specify a truststore by using a *reference* with the `` element. The truststore holds the client's certificate issuer and the certificate's CA chain, which is required. The client must also be configured correctly for two-way TLS. To create a virtual host for two-way TLS, create an XML object that defines the virtual host: ``` api.myCompany.com 443 true true ref://myTestKeystoreRef myKeyAlias ref://myTestTruststoreRef ``` In this definition you: - Enable two-way TLS by setting `` to true. - Specify the reference to the truststore using the `` element. The truststore holds the client's certificate issuer and the certificate's CA chain, which is required. ## Defining a virtual host that uses the Apigee free trial cert and key If you have a paid Edge for Cloud account and do not yet have a TLS cert and key, you can create a virtual host that uses the Apigee free trial cert and key. That means you can create the virtual host without first creating a keystore. The Apigee free trial cert is defined for a domain of `*.apigee.net`. Therefore, the `` of the virtual host must also be in the form `*.apigee.net`. > [!NOTE] > **Note:**For security reasons, Apigee free trial certificates expire every three months. At the end of that three month, Apigee rotates the expiring cert with a new cert. Therefore, Apigee does not recommend or support you pinning the free trial certificate. If you are performing two-way TLS, you must still set the `` element to `true`, and specify a truststore by using a *reference* with the `` element as described above in [Defining a virtual host for two-way TLS](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts-cloud#definingavirtualhostfortwowaytls). An XML object that defines the virtual host using the Apigee free trial cert and key omits the `` and `` elements, and replaces them with the `` element, as shown below: ``` myapi.apigee.net 443 true false true ``` The default value of the `` element is false. For two-way TLS, define the virtual host as: ``` myapi.apigee.net 443 true true ref://myTestTruststoreRef true ``` In the Edge UI, select the **Use built-in free trial certificate** option when creating the virtual host to use the free Apigee cert and key: ![Select Use built-in free trial certificate](https://docs.apigee.com/static/api-platform/images/freetrialcert.png) ## Creating 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, `api.myCompany.com` for this example, that points to `[org]-[environment].apigee.net`. 2. Create and configure a keystore, named **myTestKeystore** in this example, by using the procedure described here: [Creating keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui). For this example, ensure that the keystore uses an alias name of **myKeyAlias** for the cert and private key. 3. Upload your cert and key to the keystore. Ensure that the domain name specified by your cert matches the host alias that you want to use for the virtual host. 4. Create a reference to the keystore by using the Edge UI or API. The reference specifies the name of the keystore and the reference type as `KeyStore`. See [Working with references](https://docs.apigee.com/api-platform/system-administration/working-references) for more on creating and modifying references. 5. Create the virtual host by using the [Create a Virtual Host](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/virtualhosts) API. Make sure to specify the correct keystore reference and key alias. To use the API, use the following POST API call to create the keystore named **myTLSVHost** : ``` curl -X POST -H "Content-Type:application/xml" \ https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \ -d ' api.myCompany.com 443 true false ref://myTestKeystoreRef myKeyAlias ' \ -u orgAdminEmail:password ``` If you are performing two-way TLS with the client, then set `` to true and specify the truststore using the `` element. The client must be configured correctly for two-way TLS, meaning Edge has a truststore containing the client's cert issuer and certificate chain. Create the truststore by using the procedure described here: [Creating keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui). 6. If you have any existing API proxies, add the virtual host to the `` 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](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts#configuringanapiproxytouseavirtualhost). > [!WARNING] > **Caution:** 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. After updating an API proxy to use the virtual host, and creating the DNS entry and CNAME record for the host alias, you can access the API proxy as shown below: ``` https://api.myCompany.com/v1/{project-base-path}/{resource-path} ``` For example: ``` https://api.myCompany.com/v1/weather/forecastrss?w=12797282 ``` ## Modifying a virtual host There are two main tasks paid Cloud customers perform to modify an existing virtual host: 1. Modifying the value of a reference to a keystore or truststore. **Note** : Once you set a `` or `` to use a reference, you can change the value of the reference at any time. However, if you ever want to change `` or `` to use a different reference, or change `` to use a different alias, you must contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). 2. Modifying the TLS properties of the virtual host. ### Modifying the value of a reference You can modify the value of a reference to change the keystore or truststore used by a virtual host. > [!WARNING] > **Warning:** When changing the reference to a keystore, ensure that the alias in the new keystore has the same name as the alias in the old keystore. Before you modify the value of the reference: 1. Create a new keystore and upload a cert and key as described in [Creating keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui). In the new keystore, **ensure that you use the same name for the key alias as was used in the existing key store**. 2. If necessary, create a new truststore and upload a cert as described in [Creating keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui). 3. Modify the reference as described in [Working with references](https://docs.apigee.com/api-platform/system-administration/working-references). ### Modifying the TLS properties of the virtual host Paid customers can use the [Update a Virtual Host](https://docs.apigee.com/management/apis/put/organizations/{org_name}/environments/{env_name}/virtualhosts/{virtualhost_name}) API to update a virtual host. This API lets you set all of the properties for the virtual host described at [Virtual host property reference](https://docs.apigee.com/api-platform/fundamentals/virtual-host-property-reference). > [!NOTE] > **Note:** Free and trial accounts cannot create or modify virtual hosts and are limited to the four virtual hosts created for them at Edge registration time. > [!WARNING] > **Caution:** Before you modify a virtual host: > > - Ensure that the virtual host uses references to set `` and ``. Do not set them directly to the name of a keystore or truststore. > - If the `` and `` use references, update the value of the reference to change the keystore or truststore. If you want to change `` and `` to use a different reference variable, you must work with [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support) because this change requires a Router restart. > - If the `` and `` are directly set to the name of a keystore or truststore, you must work with [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support) to convert them to references. See [Modifying a virtual host to use references to the keystore and truststore](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts-cloud#modifying-a-virtual-host-to-use-references-to-the-keystore-and-truststore) for more. > - If the virtual host already has a value for ``, do not change it. The new keystore must use an alias with the same name as the current alias. To change the alias name, you must work with [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). > - You cannot enable TLS on a virtual host using port 80. > - You cannot disable TLS on a virtual host using port 443. > - If Apigee Support configured the virtual host for you to use a port other than 443, then you can still update the virtual host but cannot change the port. A port other than 443 is typically required if your app does not support SNI. If you need to change the port, contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). When you modify the virtual host, Edge performs a validation similar to when you create a virtual host. That is, on a modify, Edge validates that: - The domain as specified by the host alias is not used in another organization and environment. - You own the domain name. Specifically, Edge checks that the following information in the cert matches the host alias: - CN - Common Name - SAN - Subject Alternative Name - Edge validates that the cert has not expired. To modify a virtual host by using the Edge API, perform the following: 1. Update the virtual host by using the [Update a Virtual Host](https://docs.apigee.com/management/apis/put/organizations/{org_name}/environments/{env_name}/virtualhosts/{virtualhost_name}) API. When using the API, 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 set the value of the `proxy_read_timeout` property: ``` curl -X PUT -H "Content-Type:application/xml" \ https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \ -d ' api.myCompany.com 443 true false ref://myTestKeystoreRef myKeyAlias 50 ' \ -u orgAdminEmail:password ``` ## Modifying a virtual host to use references to the keystore and truststore All new virtual hosts for Edge in the Cloud use reference to the keystore and truststore. References let you change the keystore and truststore without contacting [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). Older virtual hosts on Apigee Edge might not be configured to use references for keystores and truststores. In this case, you can update the virtual host to use a reference. > [!WARNING] > **Warning:** To change the virtual host to use a reference to the keystore you must work with [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support). ### Updating a virtual host to use a reference Use the following procedure to update the virtual host: 1. If required, create a new keystore and upload a cert as described in [Creating keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui). If you already have a keystore, then you can configure a reference to point to it. 2. Create a new reference to the keystore. 3. If required, create a new truststore and upload a cert. If you already have a truststore, then you can configure a reference to point to it. 4. Create a new reference to the truststore. 5. Update the virtual host to set the keystore, alias, truststore, and any other TLS properties. The payload for the call is: ``` curl -X PUT -H "Content-Type:application/xml" \ https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \ -d ' api.myCompany.com 443 off true true ref://myKeyStore2Way keyAlias ref://myTrustStore2Way false ' \ -u orgAdminEmail:pWord ``` 6. Contact [Apigee Support](https://cloud.google.com/apigee/support) to restart the Edge Routers to complete the process.