Routes and Domains

Page last updated: December 18, 2015

This page assumes you are using cf CLI v6.

Note: The term domain in this topic differs from its common use and is specific to Cloud Foundry. Likewise, shared domain and private domain refer to resources with specific meaning in Cloud Foundry. The use of domain name, root domain, and subdomain refers to DNS records.

Routes

HTTP requests are routed to applications pushed to Cloud Foundry by associating an application with a URL, known as a route. This association can be called a mapping. For example, a developer might say, “I mapped route myapp.shared-domain.com to app myapp”.

Many apps can be mapped to a single route resulting in load balanced requests for the route across all instances of all mapped apps. This approach makes the blue/green deploy strategy possible. An individual app can also be mapped to multiple routes, granting multiple URLs access to the app.

Routes belong to a space, so that only apps in the same space can be mapped to a route. Routes are globally unique, so that member users of one space cannot create a route with the same URL as members of another space, regardless of which orgs control these spaces.

Create a Route

Routes can be created and reserved for later use. They do not need to be immediately mapped to an application. Additionally, they will persist after being unmapped from an application.

Routes are based on a domain plus an optional hostname, where domain is a Cloud Foundry term. See Domains below for further detail. Three kinds of routes can be created depending on the domain and the accompanying hostname.

Create a Route with Hostname

Routes can be created and subsequently added to an app. See Map a Route to your App for further detail.

$ cf create-route my-space shared-domain.com -n myapp

Only requests for http://myapp.shared-domain.com, https://myapp.shared-domain.com, or any path under those URLs (for example http://myapp.shared-domain.com/bar), will be routed to apps mapped to this route.

Create a Route without Hostname

This approach creates a route for the domain itself and is permitted for Private Domains only.

$ cf create-route my-space private-domain.com

This example creates a route in space my-space from domain private-domain.com with no hostname. If DNS has been configured correctly, Cloud Foundry will route requests for http://private-domain.com, https://private-domain.com, or any path under those URLs (for example http://private-domain.com/foo) to applications that are mapped to the route. If there are no other routes for the domain, requests to any subdomain (for example http://foo.private-domain.com) will fail.

Domains can also be created in Cloud Foundry for subdomains, for example foo.private-domain.com. Assuming DNS has been configured for this subdomain, a route created from this domain with no added host would result in requests for http://foo.private-domain.com, https://foo.private-domain.com, or any path under those URLs (for example http://foo.private-domain.com/foo) to be routed to applications mapped to the route.

Create a Route with Wildcard Hostname

To create a wildcard route submit an asterix for the hostname.

$ cf create-route my-space foo.shared-domain.com -n *

An application mapped to a wildcard route acts as a fallback app for route requests if the requested route does not exist. For example, if a client sends a request to http://app.foo.shared-domain.com by accident, meaning to reach myapp.foo.shared-domain.com, the request will be routed to the application mapped to the route *.foo.shared-domain.com.

List Routes

You can list routes for the current space with the cf routes command. A route is uniquely identified by the combination of host and domain.

$ cf routes
Getting routes as [email protected] ...

space       host                     domain                        apps
my-space    myapp                    shared-domain.com             myapp
my-space    myapp2                   shared-domain.com             myapp
my-space    foo                      private-domain.com            myapp

Map a Route to your Application

For an application to receive requests to a route, the route must be assigned, or mapped, to the app. Map a route to an application with the cf map-route command. If the route does not already exist, this command will also create it.

Note: Applications running on the legacy runtime (DEA) must be restarted after routes for an app are mapped or unmapped. Applications running on the Diego runtime do not need to be restarted.

Manually Map a Route

The -n HOSTNAME option identfies the route to map to your application. Omit the -n flag if your route was created from a private domain without a hostname, as described in Routes without Hostnames.

$ cf map-route myapp shared-domain.com -n myapp

The command below maps the wildcard route *.foo.shared-domain.com to the application myfallbackapp.

$ cf map-route myfallbackapp foo.shared-domain.com -n *

Map a Route with Application Push

A route can be mapped to your application with the cf push command. The default route is based on the app name and default domain.

Push your myapp app to create the myapp.shared-domain.com route with the default shared domain shared-domain.com. If the route has not already been created in another space this command will also map it to the app.

$ cf push myapp

To customize the route during push, specify the domain using the -d flag and the hostname with the -n flag. The following command creates the foo.private-domain.com route for myapp.

$ cf push myapp -d private-domain.com -n foo

Map a Route Using Application Manifest

When you create or edit the manifest for an application, you can use the host and domain attributes to define the host and domain components of the application route, respectively. For more information, see Application Manifests.

Map a Route to Multiple Apps

Cloud Foundry allows multiple apps, or versions of the same app, to be mapped to the same route. This feature enables Blue-Green deployment. For more information see Using Blue-Green Deployment to Reduce Downtime and Risk.

Routing multiple apps to the same route may cause undesirable behavior in some situations by routing incoming requests randomly to one of the apps on the shared route. See Routing Conflicts for more information about troubleshooting this problem.

Unmap a Route

You can remove a route from an app using the cf unmap-route command. Unmapping a route makes the route available in the targeted space for later use.

$ cf unmap-route myapp private-domain.com -n myapp

Delete a Route

You can delete a route from a space using the cf delete-route command.

$ cf delete-route private-domain.com -n myapp

Domains

Domains in Cloud Foundry provide a namespace from which to create routes. The presence of a domain in Cloud Foundry indicates to a developer that requests for any route created from the domain will be routed to Cloud Foundry. This provision requires DNS to be configured out-of-band to resolve the domain name to the IP address of a load balancer configured to forward requests to the CF routers.

List Domains for an Org

You can view available domains for the targeted organization using the cf domains command. In following example, there are two available domains: a system-wide shared domain shared-domain.com, and the private private-domain.com domain.

$ cf domains
Getting domains in org my-org as [email protected]... OK

name                 status
shared-domain.com    shared
private-domain.com   owned

Shared Domains

The system admin manages shared domains and those domains are available to users in all orgs. An admin can offer multiple shared domains to users, one of which is configured as the default.

Routes created for shared domains must use a hostname.

Create a Private Domain

Admins can create a shared domain with the cf create-shared-domain command:

$ cf create-shared-domain shared-domain.com

The following example illustrates the point: CF admin John offers users the choice of creating routes for their apps from two domains by configuring CF with shared domains shared-domain.com and cf.some-company.com. John configures the former to be the default. When developer Jane pushes her app awesome to Cloud Foundry and does not specify a route, she automatically creates and maps the route awesome.shared-domain.com to her app. Requests to http://awesome.shared-domain.com route immediately to Jane’s app. If Jane wants her app to be accessible at awesome.cf.some-company.com, she can create this route and map it to her app.

Delete a Shared Domain

Admins can delete a domain from Cloud Foundry with the cf delete-shared-domain command:

$ cf delete-domain mydomain.com

Private Domains

Users can add private domains (or custom domains) with the Org Manager role and give members of the org permission to create routes for privately registered domain names. Private domains can additionally be shared with other organizations, enabling users of those orgs to create routes from the domain.

Create a Private Domain

To create a private domain:

$ cf create-domain my-org private-domain.com

To create a private domain for a subdomain:

$ cf create-domain my-org foo.private-domain.com

Sharing a Private Domain with One or More Orgs

As an Org Manager, you can grant or revoke access to a private domain to other orgs. You must have Org Manager permissions for all associated orgs.

$ cf share-private-domain test-org private-domain.com

$ cf unshare-private-domain test-org private-domain.com

Delete a Private Domain

Org Managers can delete a domain from Cloud Foundry with the cf delete-domain command:

$ cf delete-domain private-domain.com

Requirements for Parent and Child Domains

In the domain myapp.shared-domain.com, shared-domain.com is the parent domain of subdomain myapp.

• You can only create a private domain that is parent to a private subdomain.
• You can create a shared domain that is parent to either a shared or a private subdomain.

The domain foo.myapp.shared-domain.com is the child subdomain of myapp.shared-domain.com.

• You can create a private subdomain for a private parent domain only if the domains belong to the same org.
• You can create a private subdomain for a shared parent domain.
• You can only create a shared subdomain for a shared parent domain.
• You cannot create a shared subdomain for a private parent domain.

DNS for Domains

Configuring DNS for a Subdomain of your Registered Domain

To use a subdomain of your registered domain name with applications on Cloud Foundry, configure the subdomain as CNAME record with your DNS provider, pointing at any shared domain offered in Cloud Foundry.

Configuring DNS for Your Registered Root Domain

To use your root domain (for example mydomain.com) for applications on Cloud Foundry you can either use custom DNS record types like ALIAS and ANAME, if your DNS provider offers them, or subdomain redirection.

Note: Root domains are also called zone apex domains.

If your DNS provider supports using an ALIAS or ANAME record, configure your root domain with your DNS provider to point at a shared domain in Cloud Foundry.

If your DNS provider does not support ANAME or ALIAS records you can use subdomain redirection, also known as domain forwarding, to redirect requests for your root domain to a subdomain configured as a CNAME.

Note: If you use domain forwarding, SSL requests to the root domain may fail if the SSL certificate only matches the subdomain.

Configure the root domain to point at a subdomain (www), and configure the subdomain as a CNAME record pointing at a shared domain in Cloud Foundry.