feat: support for path based routing to other services

[shreddedbacon]

This adds support for path based routing. This can be used to allow a path on an existing route to be directed to a different service within the environment.

For example you have an application that serves a static or other site on www.example.com via nginx, but you need to pass www.example.com/api/v1 to a node application running in the environment. Currently the only way to do that would be via nginx configuration.

This feature allows you to define paths on a route to a different backend.

Usage

Here is an example .lagoon.yml file that shows how path based routes can be defined. There is support for global autogenerated routes, per environment autogenerated routes, and custom routes.

docker-compose-yaml: docker-compose.yml

# if an environment has `autogeneratePathRoutes` defined like `environments.main.autogeneratePathRoutes`
# then thes global lagoon yaml `routes.autogenerate.pathRoutes` are ignored
routes:
  autogenerate:
    pathRoutes:
      - fromService: nginx
        toService: node
        path: /api/v1

environments:
  main:
    # path routes for autogenerated routes for this environment only
    autogeneratePathRoutes:
      - fromService: nginx
        toService: node
        path: /api/v1
    routes:
      - nginx:
        - a.example.com:
            pathRoutes:
              - toService: node
                path: /api/v1

Autogenerated Routes

Firstly, there are global autogenerated route configurations, these would apply to ALL environments that this .lagoon.yml file would cover. Second is per environment autogenerated route configurations, the fields are the same, just where they are defined is different.

routes:
  autogenerate:
    pathRoutes:
      - fromService: nginx
        toService: node
        path: /api/v1

environments:
  main:
    # path routes for autogenerated routes for this environment only
    autogeneratePathRoutes:
      - fromService: nginx
        toService: node
        path: /api/v1

Note: if the per environment path routes are defined on an environment, any global defined ones are ignored.

The 3 fields are

• fromService - the autogenerated route for the service you want to add the path based route to
• toService - the backend service you want to route to
• path - the path to send to the toService

Custom Routes

It is possible to turn on path based routes for a specific route too, the following .lagoon.yml example shows how.

environments:
  main:
    routes:
      - nginx:
        - a.example.com:
            pathRoutes:
              - toService: node
                path: /api/v1

The fields are the same, except that fromService is omit because of the way that custom routes are defined to already be associated to a fromService in their normal configuration.

Conditions

Autogenerated Route configurations

If the global path routes for autogenerated routes are defined, but an environment has overrides, the global defined path routes are ignored by that environment.

Additional Ports/Docker Compose Ports reference

If the docker compose label lagoon.service.usecomposeports=true has been defined on a service, then the service name with the port number as a suffix to any ports beyond the default (first defined port) must be used as the toService.

The following docker-compose.yml has an example of this label and the ports. This would create the default service port named node referencing port 1234, but also another service node-4321. If you need to create a path based route to port 4321, you would need to define the toService as node-4321.

services:
  node:
    build:
      context: .
      dockerfile: basic.dockerfile
    labels:
      lagoon.type: basic
      lagoon.service.usecomposeports: true
    volumes:
      - ./api:/api:delegated
    ports:
      - '1234'
      - '4321'

URLs

The path defined in the pathRoute will be passed to whichever toService is defined in all URL queries. This means if you're using the path defined as /api/v1 for example, then you may need to cater for this in your backend depending on how your backend is built.

Path Types

Currently only Prefix is supported (see Ingress path types). If there is a need, the pathRoutes could be extended to include a type that accepts Prefix or Exact, with the default being Prefix if not provided.

Example repo

An example repo was created to show how this could be used, it will be completely unmaintained, do not build off this example.

Closing Issues

closes uselagoon/lagoon#3642

[shreddedbacon]

One thing I have not checked yet is the additive nature of Lagoon with applying manifests, and if a path based route definition is removed from a route, it may leave the path route in the ingress still.

Will need to confirm this behaviour, because there is currently no way to selectively modify objects that Lagoon provisions, the workaround would be that the path would require manual intervention to remove from the ingress. In the case of autogenerated routes simply enabling and disabling them in a 2 build cycle would delete and recreate them.

Custom defined routes could be done a similar way, but it would result in outage while the ingress is removed and recreated over a 2 build cycle, the other option is manually (not ideal)

---

Update: Removing a pathRoute from an autogenerated route or a custom route does remove the path from the ingress automatically during a deployment 🥳

[tobybellwood]

This looks good to me, nice fix on the path ports.