app-routes

Managing CF App routes with an MTA

Table of Contents

• Overview
• 1. Using routes
  • 1.1a Deploy
  • 1.2 Check out the result
• 2. Deploy apps to hostless domains
  • 2.1 Deploy
  • 2.2 Check out the result
  • 2.3 Check out the registered domain
• 3. Using host
  • 3.1 Deploy
  • 3.2 Check out the result
• 4. Using hosts
  • 4.1 Deploy
  • 4.2 Check out the result
• 5. Deploy apps with no routes
  • 5.1 Deploy
  • 5.2 Check out the result
• 6. Keep-existing-routes

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 a three major ways to do the modelling:

• 1. Using routes parameter (recommended)

• 3. Using host / protocol / domain parameters

• 4. Using hosts / domains parameters

1. Using routes

This is the recommended way of modelling 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:

• modelling 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 the '/' as the domain and the rest (if present) as the path.

1.1a Deploy

directly from an mtad.yaml

  $ cf deploy ./ -f ;

or start from an mta.yaml:

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

1.2 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

2. 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 then 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.

2.1 Deploy

directly from an mtad.yaml

  $cd no_hostname ;
  $ cf deploy -f ;

or start from an mta.yaml

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

2.2 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

2.3 Check out the registered domain

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

3. Using host

This is a NOT recommended way of modelling 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. E.g. 4 hosts definitions x 4 domain definitions would result in 16 unique reoutes being mapped to your application

3.1 Deploy

directly from an mtad.yaml

  $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"
...

or start from an mta.yaml:

$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"
...

3.2 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

4. Using hosts

This is a NOT 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

4.1 Deploy

directly from an mtad.yaml:

  $cd modelled_with_hosts_and_domains ;
  $ cf deploy -f ;

or start from an mta.yaml:

  $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"
...

4.2 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

5. 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.

5.1 Deploy

directly from an mtad.yaml

  $cd no_route ;
  $ cf deploy -f ;

or start from an mta.yaml

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

5.2 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

6. 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

See examples here