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
This is the recommended way of modeling routes, both when using CF app manifests and the mtad.yaml.
-
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.
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 ;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.comIf 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. |
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 ;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.comBy 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. |
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. |
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"
...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. |
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"
...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 |
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. |
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 ;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. |
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 ;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-moduleIn 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.
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:trueparameter -
module level
keep-existing-routes:trueparameter -
module level
keep-existing: [routes:true]parameter
Parameter keep-existing-routes preserves the app-protocol as well.