Route Policy Examples

Routes are resources that allow network traffic into the job (ingress). Policy for routes is a two-way handshake. Both the route and the job must permit the mapping.

Route permissions

The following policy establishes route permissions:

route::/ {
  if (permit == all) {
    permit create, read, update, delete, map
  }
}

Route example 1

Consider that you have the deployed an app to the namespace job::/purchasing with the network route http://purchasing.acme.com. For this example, assume you are part of the networking team. You've set up DNS and any other settings required to route network traffic to http://purchasing.acme.com. You want to ensure that the only jobs that can claim this network path are part of the job::/purchasing namespace.

To map a job to a route, you reverse the endpoint hostname and use it for the route::/ realm FQN, then permit the mapping. Note that the URL (http://purchasing.acme.com) is reversed in realm.

route::/http/com/acme/purchasing {
  if (job fqnMatch "job::/purchasing") {
    permit map
  }
}

The networking team has granted 1/2 of the permission required to map http://purchasing.acme.com to the app in job::/purchasing. The team responsible for the purchasing app would likely want assurance that their app is only being accessed from the url http://purchasing.acme.com.

To complete the handshake, this team needs the following policy:

job::/purchasing{
  if (route fqnMatch "route::/http/com/acme/purchasing") {
    permit map
  }
}

In order for the networking team to be able to fully manage the routes on the cluster, be sure to grant permissions.

route::/ {
  if (team == "networking") {
    permit all
  }
}

Route example 2

Here is another example of routing policy that templatizes the route:

route::/http/com/cluster/sandbox/[name] {
  if (job fqnMatch "job::/sandbox/[name]") {
    permit map
  }
}

Then you would need the corresponding policy on the job:

job::/sandbox/jay {
   if (auth_server@apcera.me->name == jay) {
      permit create, read , update , delete
      permit start, stop, promote, ssh
      permit map, link, bind
    }
}

Matching on route FQNs

Here are some example FQNs for matching on custom routes.

URL Realm
http://server.acme.com route::/http/com/acme/server
http://server.acme.com/ route::/http/com/acme/server
http://10.1.1.167 route::/http/10/1/1/167
tcp://10.1.1.167 route::/tcp/10/1/1/167
https://server.acme.com/path route::/https/com/acme/server::/path
tcp://10.1.1.167:8081 route::/tcp/10/1/1/167::/8081
tcp://10.1.1.167:8081/ route::/tcp/10/1/1/167::/8081
udp://10.0.0.1:1212 route::/udp/10/0/0/1::/1212
http auto-provisioned route::/http/auto
tcp auto-provisioned route::/tcp/auto

For auto-provisioned routes you can use the following policy realms:

URL Realm
http auto-provisioned route::/http/auto
tcp auto-provisioned route::/tcp/auto

Custom route suffix

Apcera defines a default route name URL for you when you create an app, unless you disable it. See the job routes documentation for details.

If you want to use the default route scheme but customize the cluster-name value, you can use policy to define a default route suffix, that is, the domain name portion of the route.

To do this you use the new defaultRouteSuffix policy claim type for job resources to override the default route suffix. This claim instructs the system to use this value instead of what the cluster domain is. Note that this only applies to default routes, not custom routes.

You must have a DNS record for the custom domain suffix that points to the Apcera router.

For example, if your cluster-name is cluster.example.com, you can set foo.bar.com as the route suffix using the following policy on the host job:

on job::/sandbox/user {
  { defaultRouteSuffix foo.bar.com }
}

Or, if you wanted to template one of the tokens in the default route suffix, specify it with quotes. For example:

on job::/some/team/[ldapgroup]/public {
  if (LDAP->group == [ldapgroup])
    { permit all defaultRouteSuffix "[ldapgroup].route.example.com" }
}