—Rate this article—
 

Virtual hosts

About virtual hosts

Virtual hosts let multiple domain names connect to the same host. A virtual host on Edge defines the domains and ports on which an API proxy is exposed, and, by extension, the URL that apps use to access an API proxy. A virtual host also defines whether the API proxy is accessed by using the HTTP protocol, or by the encrypted HTTPS protocol.

One of the main uses of virtual hosts is to let you customize the domain name of your APIs hosted on Edge. For example, on a cloud-based version of Edge, the default domain name of an organization called "myorg" in the prod environment is "myorg-prod.apigee.net". Therefore, to access an API in that organization, a developer uses a URL in the form:

https://myorg-prod.apigee.net/v1/{project-base-path}/{resource-name}

However, a domain name containing "apigee.net" may not be what you want to expose to your customers. A virtual host can map your own domain name to your organization on Edge, letting developers access your API through a domain specific to your company, for example:

https://api.myCompany.com/v1/{project-base-path}/{resource-name}

Note that creating a virtual host does not also make the domain name accessible. You must still create a DNS record for the domain.

Learn more:

About virtual hosts on a cloud-based Edge installation

After you create an API proxy on Edge, you can make that API available for requests. However, the first thing you need to determine is the complete URL of the resources exposed by the API proxy. That URL has the form:

http://{org-name}-{env-name}.apigee.net/{project-base-path}/{resource-name}

https://{org-name}-{env-name}.apigee.net/{project-base-path}/{resource-name}

where:

  • {org-name} is your organization name.
  • {env-name} is the environment name. By default, all Apigee organizations created in the cloud are provisioned with two environments: 'test' and 'prod'. When deploying an API proxy, you can choose to deploy it to one or both environments.
  • {project-base-path} and {resource-name} are defined when you create an API proxy.

The domain name of the URL and the HTTP or HTTPS access protocol is defined by a virtual host on Edge. By default, Apigee creates two virtual hosts for every environment in an organization:

  • default: Defines HTTP access to your APIs on port 80.
  • secure: Defines HTTPS access to your APIs on port 443.

Apigee provides an SSL certificate and private key to support HTTPS on the secure virtual host so that you can quickly get started developing and testing your APIs. While many customers prefer to use their own certificate and private key at deployment time, you can deploy your APIs using the Apigee cert and key.

Apigee also creates DNS records for each virtual host. Therefore, you can use any or all of the following four URLs to access your API:

http://{org-name}-prod.apigee.net/{project-base-path}/{resource-name}

https://{org-name}-prod.apigee.net/{project-base-path}/{resource-name}

http://{org-name}-test.apigee.net/{project-base-path}/{resource-name}

https://{org-name}-test.apigee.net/{project-base-path}/{resource-name}

About virtual hosts on an on-premises Edge installation

When you install Edge on-premises, there are no default organizations, environments, or virtual hosts created for you. After you complete the Edge installation process, your first action is typically to create an organization, environment, and virtual host through the "onboarding" process.

To perform onboarding, run the following script on the Edge Management Server node:

/opt/apigee4/bin/setup-org.sh

This script prompts you to create a user, organization, environment, and virtual host.

For example, if you use the default values in the setup-org.sh script, you create:

  • An organization named example
  • An environment named prod
  • A virtual host named default that allows HTTP access on port 9001
  • No host alias

After running the onboarding script, you can later add any number of organizations, environments, and virtual hosts to your on-premises version of Edge.

Virtual hosts are opened on the Edge Router node. Therefore, you have to ensure that the port that you specify for the virtual host is open on the Router node. You can use a command in the form below to open a port:

$ iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 9001 -j ACCEPT --verbose 

After running that script, you can access your APIs by using a URL in the form:

http://<router-ip>:9001/{project-base-path}/{resource-name}

Note that this URL uses the IP address of the Router and the virtual host port on the Router to access your APIs. Until you create virtual hosts with host aliases, and DNS records for your virtual hosts, you can use the IP address and port explicitly to access your APIs.

Note also that the URL uses the HTTP protocol. To use the encrypted HTTPS protocol, you must create a virtual host that references a keystore. A keystore contains the certificate and private key required to support HTTPS. For more, see Creating a virtual host for an on-premises Edge installation.

Viewing information about a virtual host

You can use the Edge management UI to see the virtual hosts defined in an environment:

  1. Login to the Edge management UI at https://enterprise.apigee.com (cloud) or http://<ms-ip>:9000 (on-premises), where <ms-ip> is the IP address of the Management Server node.
  2. In the Edge management UI menu, select APIs > Environment Configuration.
  3. Select the environment, such as prod or test. The virtual hosts defined for the environment appear.

    If the virtual host is configured to use a keystore or truststore, select the Show button to see more information.

You can also use the Edge APIs to view information about virtual hosts. For example, the List Virtual Hosts API returns a list of all virtual hosts:

$ curl -X GET -H "accept:application/xml" \
https://api.enterprise.apigee.com/v1/o/{org}/environments/{env}/virtualhosts \
-u myname:mypass

Sample response:

[
 "default",
 "secure"
]

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}/environments/{env_name}/virtualhosts/default \
-u myname:mypass

Sample response:

{
 "hostAliases" : [apigeedocs-prod.apigee.net ],
 "interfaces" : [ ],
 "name" : "default",
 "port" : "9001"
}

For an on-premises version of Edge, replace the api.enterprise.apigee.com domain name with <ms-ip>:8080 where <ms-ip> is the IP of the Edge Management Server.

If the virtual host is configured to use SSL, a lock icon appears next to the name of the virtual host. That means an SSL certificate, key, and certificate chain has been uploaded to Edge and associated with the virtual host.

To see information about the available certificates:

  1. Login to the Edge management UI.
  2. In the Edge management UI menu, select Admin > SSL Certificates.
  3. Expand the keystores until you see the certificate.

To use the the Get a Cert from a Keystore or Truststore to view a cert:

$ curl -H 'accept: application/xml' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/23-apigee-wildcard.apigee.net.crt \
-u myname:mypass

Creating a virtual host

You can create a virtual host that uses the HTTP protocol or one that uses SSL and the encrypted HTTPS protocol. The way you create virtual hosts depends on your Edge installation: cloud or on-premises.

Creating a virtual host on a cloud-based Edge installation

If you have an Apigee Edge paid plan, Apigee creates virtual hosts for you. For technical and security reasons, virtual host creation and manipulation in Edge cloud accounts is not self-service. For assistance with virtual hosts, contact Apigee Customer Support at http://community.apigee.com/content/apigee-customer-support.

If you want to create a virtual host that supports SSL, then you must obtains the necessary SSL certificate and private key. Apigee then uses the cert and key to configure the virtual host.  

See Configuring SSL for a cloud-based Edge installation for more on creating virtual hosts for a cloud installation.

Creating a virtual host on a on-premises Edge installation

In an on-premises installation, you have complete control over virtual hosts. You can create virtual hosts for any org, in any environments, using SSL or not.

See Creating a virtual host for an on-premises Edge installation for more on creating virtual hosts for an on-premises installation.

Updating an API proxy after creating a virtual host

An API proxy references the virtual hosts that it supports in its ProxyEndpoint definition. When you create a new API proxy, Edge automatically configures its ProxyEndpoint to use all available virtual hosts.

After Apigee notifies you that your new virtual host has been created for a cloud installation, or after you create one directly in an on-premises installation, any new API proxies that you create automatically reference the virtual host.

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.

If you created any API proxies before requesting the virtual host, then you must edit the API proxy to add the new virtual hosts to its ProxyEndpoint. Otherwise, the API proxy is not accessible by the virtual host.

If you are developing your API proxies in XML, edit the XML file for the ProxyEndpoint to add or remove a virtual host.

To use the Edge management UI to edit the ProxyEndpoint:

  1. Login to the Edge management UI at https://enterprise.apigee.com.
  2. In the Edge management UI menu, select APIs.
  3. Select the name of the API proxy to update.
  4. Select the Development tab.
  5. Under Proxy Endpoints, select default.
  6. In the code area:
    1. Remove any <VirtualHost> elements for virtual hosts not supported by the API proxy.
    2. Add a new <VirtualHost> element with the name of the new virtual host. For example, if the new virtual host is named MyVirtualHost, add the following tag:

      <HTTPProxyConnection>
         <BasePath>/oauth10a/client_credential</BasePath>
         <VirtualHost>default</VirtualHost>
         <VirtualHost>secure</VirtualHost>
         <VirtualHost>MyVirtualHost</VirtualHost>
      </HTTPProxyConnection>
  7. Save the API proxy. If the API proxy has been deployed, saving it redeploys it with the new setting.
 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)