Routes

What are routes?

Routes describe how to direct traffic from the edge of a network to a particular workload. They are normally described by matching things like URL fragments and/or DNS names on incoming requests.

In Kubernetes there are many ways of modeling routing. For example:

Each of these routing systems has its own unique approach to configuration. Many do more than just routing, and also include traffic shaping, authorization, and more.

Routes in the Platform Orchestrator

The Platform Orchestrator aims to simplify routes for the developer as much as possible. Developers only need to depend on a dns Resource and include one or more route Resources in their Score file. For the route they can provide parameters such as the path to match, DNS name to match, and the port to forward traffic to on the Workload. An example can be found further down this page.

Platform engineers can use the route Resource alongside related Resources such as dns, ingress, and tls-cert to model a wide range of different configurations. For example, by limiting ourselves to just the Kubernetes Ingress system, the following configurations are possible:

  • All routes defined in a single Ingress object serving multiple DNS names
  • A single Ingress object per domain holding all of the routes for that domain
  • A single Ingress object per service each covering multiple DNS names

In addition, TLS might be terminated at the ingress controller or at the LoadBalancer fronting the ingress controller.

The configuration approach chosen will depend on factors such as the Ingress Controller(s) being used, how TLS is managed, and how additional concerns such as authorization, rate limiting, global load balancing, or canary deployments are handled.

Despite the vast number of possible configurations to implement, the developer should only have to worry about the route that their Workload expects to handle and the DNS name the route maps from. Platform engineers define how a Resource Graph is built to satisfy all of these requirements.

Default Humanitec route handling

To help platform engineering teams get started, the Platform Orchestrator comes with a default configuration for handling routes. This configuration creates a single Kubernetes Ingress object for each DNS name used in a namespace.

The Platform Orchestrator comes with a number of pre-defined default Resource Definitions. These are used if no Resource Definitions are matched for the context the Workload is being deployed into.

For routes, the following default Resource Definitions are involved:

  • default-humanitec-dns
    Provisions a new DNS subdomain under the newapp.io domain.
  • default-humanitec-ingress
    Injects a Kubernetes Ingress object into the cluster.
  • default-humanitec-route
    Holds the route.
  • default-humanitec-tls-cert
    Provisions a TLS certificate for the DNS name.

Here is an example Score file for a Workload that has three routes from one DNS name:

apiVersion: score.dev/v1b1
metadata:
  name: routes-example
service:
  ports:
    www:
      port: 80
      targetPort: 8080
containers:
  webserver:
    image: my-webservice:latest
resources:
  api-dns:
    type: dns
  users-route:
    type: route
    params:
      host: ${resources.api-dns.host}
      path: /users
      port: 80
  products-route:
    type: route
    params:
      host: ${resources.api-dns.host}
      path: /products
      port: 80
  checkout-route:
    type: route
    params:
      host: ${resources.api-dns.host}
      path: /checkout
      port: 80

When this Score file is processed by the Platform Orchestrator, it will match the Resources to Resource Definitions. The Score file defines dependencies on dns and route Resources. These are therefore provisioned directly by the Platform Orchestrator.

The ingress and tls-cert Resources are provisioned indirectly. The ingress is co-provisioned by the dns Resource. This means that for every dns Resource provisioned, an ingress Resource will be provisioned. The ingress depends on a tls-cert via a Resource Reference. This references the name of the Kubernetes Secret that the tls-cert Resource creates. The tls-cert in turn depends on a dns Resource using a Resource Reference to determine the DNS name. This means that one tls-cert will be provisioned for every ingress Resource provisioned.

Here is an example of the Resource Graph generated for this configuration:

Resource Graph for route

Some or all of these elements can be overridden to model different routing architectures for your applications. This is done by defining new Resource Definitions that affect the configuration generated and the shape of the Resource Graph.

Next Steps

Familiarize yourself with how the Resource Graph is built.

DNS

TLS certificates