app-routes

Managing CF App routes with an MTA

Table of Contents

• Overview
• Using routes
  • Deploy
  • Check out the result
• Deploy apps to hostless domains
  • Deploy
  • Check out the result
  • Check out the registered domain
• Using host
  • Deploy
  • Check out the result
• Using hosts
  • Deploy
  • Check out the result
• Deploy apps with no routes
  • Deploy
  • Check out the result
• Deploy app with HTTP2 route
  • Deploy
  • Check out the result
• Keep-existing-routes
• Clean up resources

Overview

This example shows how to model network route mapping to a CF application. The SAP Cloud Deployment service can create, map and unmap CF app routes. There are three major ways to do the modeling:

• Using routes parameter (recommended)

• Using host / protocol / domain parameters

• Using hosts / domains parameters

Using routes

This is the recommended way of modeling routes, both when using CF app manifests and the mtad.yaml.

Note	See mta.yaml or mtad.yaml in the current directory. Those examples include:

• modeling of two custom routes for a CF app

• consumption of the relevant default/generated parameter values as environment variables

The deployer will read the 'routes' parameter in a way consistent with CF app manifest files. It will interpret everything up to the first '.' as the host, then everything up to the '/' as the domain, and the rest (if present) - as the path.

Deploy

There are two ways of deploying the MTA. The first one is using an mtad.yaml deployment descriptor:

  $ cf deploy ./ -f ;

Alternatively, you can use an mta.yaml development descriptor and deploy the built mtar archive afterwards:

  $ mbt build -p cf -t . ;
  $ cf deploy a.cf.app_0.0.0.mtar -f ;

Check out the result

List the routes in the space and look for ones bound to your app

$ cf routes
Getting routes for org  ...
...host                                                      domain                             port   path         type   apps
   <org-name>-<space-name>-my-app-module-with-custom-suffix  cfapps.sap.hana.ondemand.com                                  my-app-module
   my-custom-host                                            at.some.domain                            /with/path          my-app-module
   *                                                         wildcard.for.host.at.some.domain                              my-app-module

List the environment variables in your app to see what the routing related paramters were resolved to during deployment
```bash
$ cf env my-cf-app
...
default-domain: cfapps.sap.hana.ondemand.com
default-host: <org-name>-<space-name>-my-app-module
default-uri: <org-name>-<space-name>-my-app-module.cfapps.sap.hana.ondemand.com
default-url: https://<org-name>-<space-name>-my-app-module.cfapps.sap.hana.ondemand.com
firstRoute: my-custom-host.at.some.domain
protocol: https
secondRoute: <org-name>-<space-name>-my-app-module-with-custom-suffix.cfapps.sap.hana.ondemand.com

Deploy apps to hostless domains

If you want an app to be to bound to a route that is a subdomain of an existing domain, without having a host attached, you need to use the routes parameter in combination with no-hostname. Note that no-hostname is a boolean parameter and must be included with each route it affects - if you have 2 or more hostless routes in your MTA, you need to add that parameter under each of those routes. If the parameter is not present for a route, the default value taken will be false.

Note	See no_hostname/mta.yaml or no_hostname/mtad.yaml.

Warning

The MTA deployer will attempt to create the subdomain if it doesn’t exist, but cannot resolve any specific corner cases about subdomain/domain ownership permissions. If the subdomain has already been created - the deployer will simply map the application to it.

Deploy

Using an mtad.yaml deployment descriptor:

  $ cd no_hostname ;
  $ cf deploy -f ;

Using an mta.yaml development descriptor and deploying the built mtar archive afterwards:

  $ cd no_hostname ;
  $ mbt build -p cf -t . ;
  $ cf deploy a.cf.app_0.0.0.mtar -f ;

Check out the result

Note the different routes mapped to the app:

$ cf apps
Getting apps in org <org-name> / space <space-name> as <user>...
OK

name                       requested state   instances   memory   disk   urls
my-app-module              started           1/1         1G       1G     host2.some-domain.com, host1.some-domain.com, subdomain.some-domain.com

Check out the registered domain

By running the following commands you can verify that one of the attached routes contains no host and has been registered as a domain:

$ cf routes
Getting routes for org <org-name> / space <space-name> as <user>...

space     host                                              domain                                            port   path       type   apps                       service
...
<space>   host2                                             some-domain.com                                                            my-app-module
<space>   host1                                             some-domain.com                                                            my-app-module
<space>                                                     subdomain.some-domain.com                                                  my-app-module

$ cf domains
Getting domains in org <org-name> as <user>...
name                                                                                          status   type
...
subdomain.some-domain.com                                                                     owned

Note	Upon undeploying the MTA, the deployer makes no attempt to delete this new domain. This action is left to the end user if desired.

Using host

This is NOT a recommended way of modeling routes in CF.

Note	See modelled_with_host_and_domain/mta.yaml or modelled_with_host_and_domain/mtad.yaml. Those examples include the use of single host, domain, protocol parameters.

Warning

When defining both hosts and domains the MTA deployer will generate a route for each host.domain combination. For example 4 hosts definitions x 4 domain definitions would result in 16 unique routes being mapped to your application.

Deploy

Using an mtad.yaml deployment descriptor:

  $ cd modelled_with_host_and_domain ;
  $ cf deploy -f ;
...
Application "my-app-module" started and available at "my-single-host-value.internal.cfapps.sap.hana.ondemand.com"
...

Using an mta.yaml development descriptor and deploying the built mtar archive afterwards:

$ cd modelled_with_host_and_domain ;
$ mbt build -p cf -t . ;
$ cf deploy a.cf.app_0.0.0.mtar -f ;
...
Application "my-app-module" started and available at "my-single-host-value.internal.cfapps.sap.hana.ondemand.com"
...

Check out the result

You can see that a route with the defined host and domain was created and mapped to the module’s app:

$ cf routes
Getting routes for org ..
space          host                         domain                                  port   path   type   apps             service
<space-name>   my-single-host-value         internal.cfapps.sap.hana.ondemand.com                        my-app-module

Using hosts

This is NOT a recommended way of modelling routes in CF.

Note	See modelled_with_hosts_and_domains/mta.yaml or modelled_with_hosts_and_domains/mtad.yaml. Those examples include the use of hosts and domains parameters.

Warning

When defining both hosts and domains the MTA deployer will generate a route for each host.domain combination. E.g. 4 hosts definitions x 4 domain definitions would result in 16 unique reoutes being mapped to your application.

Deploy

Using an mtad.yaml deployment descriptor:

  $ cd modelled_with_hosts_and_domains ;
  $ cf deploy -f ;

Using an mta.yaml development descriptor and deploying the built mtar archive afterwards:

  $ cd modelled_with_hosts_and_domains ;
  $ mbt build -p cf -t . ;
  $ cf deploy a.cf.app_0.0.0.mtar -f ;
...
Application "my-app-module" started and available at "my-single-host-value.internal.cfapps.sap.hana.ondemand.com"
...

Check out the result

You can see that the cartesian product of the hosts and routes was created in the form of routes:

$ cf routes
Getting routes for org ..
space          host                                                      domain                                  port   path   type   apps             service

<space-name>   my-custom-host                                            cfapps.sap.hana.ondemand.com                                 my-app-module
<space-name>   <org-name>-<space-name>-my-app-module-with-custom-suffix   cfapps.sap.hana.ondemand.com                                 my-app-module
<space-name>   my-custom-host                                            at.some.domain                                               my-app-module
<space-name>   <org-name>-<space-name>-my-app-module-with-custom-suffix   at.some.domain                                               my-app-module

hostname	domain
my-custom-host	cfapps.sap.hana.ondemand.com
<org-name>-<space-name>-my-app-module-with-custom-suffix	cfapps.sap.hana.ondemand.com
my-custom-host	at.some.domain
<org-name>-<space-name>-my-app-module-with-custom-suffix	at.some.domain

Deploy apps with no routes

If you want an app to be scheduled in CF but don’t want it reachable via HTTP, you can explicitly use the no-route parameter.

Note	See no_route/mta.yaml or no_route/mtad.yaml.

Deploy

Using an mtad.yaml deployment descriptor:

  $ cd no_route ;
  $ cf deploy -f ;

Using an mta.yaml development descriptor and deploying the built mtar archive afterwards:

  $ cd no_route ;
  $ mbt build -p cf -t . ;
  $ cf deploy a.cf.app_0.0.0.mtar -f ;

Check out the result

Note that no route(url) was mapped to that app:

$ cf apps
Getting apps in org <org-name> / space <space-name> as <space-name>...
OK

name                 requested state   instances   memory   disk   urls
my-routless-cf-app   started           1/1         1G       1G

Deploy app with HTTP2 route

If you want to enable http2 routing traffic to applications you can use protocol: http2 parameter on route level.

Note	See http2-routes/mta.yaml or http2-routes/mtad.yaml.

Deploy

Using an mtad.yaml deployment descriptor:

$ cd http2-routes ;
$ cf deploy -f ;

Using an mta.yaml development descriptor and deploying the built mtar archive afterwards:

$ cd http2-routes ;
$ mbt build -p cf -t . ;
$ cf deploy a.cf.app_0.0.0.mtar -f ;

Check out the result

Note that the app-protocol is http2:

$ cf routes
Getting routes for org <org> / space <space>

space    host                  domain   port  path  protocol   app-protocol   apps            service instance
<space>  my-app-route-http1   <domain>              http       http1           my-app-module
<space>  my-app-route-http2   <domain>              http       http2           my-app-module

In the example above two routes were created. One of them uses http1 app protocol for communication with the application and the other uses http2. Keep in mind that if no protocol is specified, the default protocol is http1, but if you already have configured an existing route to use http2 and re-deploy the MTA using normal deployment (not blue-green) it will continue to work this way unless you change it explicitly.

Keep-existing-routes

Feature is used if you don’t want the deployment to unmap existing routes, which are not maintained in the MTA description, Activated in 3 ways:

• global keep-existing-routes:true parameter

• module level keep-existing-routes:true parameter

• module level keep-existing: [routes:true] parameter

Parameter keep-existing-routes preserves the app-protocol as well.

See examples here

Clean up resources

It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command:

$ cf undeploy <mta-id> -f --delete-services