Merge pull request #3833 from uselagoon/docs/ports-and-pathroutes

docs/concepts-advanced/service-types.md

@@ -2,11 +2,21 @@
 
 The below lists all service types that can be defined via `lagoon.type` within a [`docker-compose.yml` file](../concepts-basics/docker-compose-yml.md).
 
-For more information on the `lagoon.volumes.X.path` label, please see [Additional Volumes](../concepts-basics/docker-compose-yml.md/#additional-volumes)
-
 !!! Warning
     Once a `lagoon.type` is defined and the environment is deployed, changing it to a different type is not supported and could result in a broken environment.
 
+## Additional Volumes
+
+Some service types allow for additional volumes to be added, for more information on the `lagoon.volumes.X.path` label, please see [Additional Volumes](../concepts-basics/docker-compose-yml.md/#additional-volumes)
+
+If you're provisioning a new project, we recommend avoiding the usage of `-persistent` service types, and use additional volumes as required for any persistent data.
+
+## Additional Service Ports
+
+Most services provide a default port, in cases where you want to use the services already defined in your `docker-compose.yml` file, you can configure a service to use those ports instead.
+
+To use this feature, you set the `lagoon.service.usecomposeports: true` label on the service in your `docker-compose.yml` file. For more information on how to use this feature, see [Additional Service Ports](../concepts-basics/docker-compose-yml.md/#additional-service-ports)
+
 ## `basic`
 
 Basic container, good to use for most applications that don't have an existing template. No persistent storage. The port can be changed using a label. If an [autogenerated route](../concepts-basics/docker-compose-yml.md#auto-generated-routes) is not required (e.g. for an internal-facing service, set `lagoon.autogeneratedroute: false` in the docker-compose.yml)

docs/concepts-basics/docker-compose-yml.md

@@ -167,7 +167,37 @@ volumes:
       lagoon.type: persistent
 ```
 
-This volume can then be referenced in each service that requires it, along with the path
+This volume can then be referenced in each service that requires it, along with the path.
+
+### Add additional volumes to an existing non `-persistent` service type
+
+If you have a `basic` or other supported standalone service type and you want to add volumes, you can use the additional volumes to do this without chaning the service type to a `-persistent` type.
+
+```yaml title="docker-compose.yml volume usage snippet"
+services:
+  basic:
+    build:
+      context: .
+      dockerfile: basic.dockerfile
+    labels:
+      lagoon.type: basic
+      lagoon.volumes.data.path: /data # basic-persistent provides a default volume, this needs to be defined
+      lagoon.volumes.extravol.path: /extra
+    volumes: # these volumes are ignored by lagoon, only the labels above are consumed to handle volume mapping
+      - data:/data:delegated
+      - extravol:/extra
+
+volumes:
+  data:
+    labels:
+      lagoon.type: persistent
+  extravol:
+    labels:
+      lagoon.type: persistent
+      lagoon.backup: false
+```
+
+### Add additional volume to an existing `-persistent` service type
 
 ```yaml title="docker-compose.yml volume usage snippet"
 services:
@@ -182,6 +212,12 @@ services:
     volumes: # these volumes are ignored by lagoon, only the labels above are consumed to handle volume mapping
       - ./data:/data:delegated
       - extravol:/extra
+
+volumes:
+  extravol:
+    labels:
+      lagoon.type: persistent
+      lagoon.backup: false
 ```
 Note that the original volume created for this service still exists.
 
@@ -219,6 +255,60 @@ Currently, the only service types that support additional volumes are the follow
 
 Adding a volume to any other type will result in an error during a build.
 
+## Additional Service Ports
+
+If you have a service that has many ports, you can use the `lagoon.service.usecomposeports: true` label to inform Lagoon to use the ports defined on the service.
+
+!!! info
+    Only TCP based ports will be allowed to have a route attached, but UDP ports can be used for internal communications.
+
+For example, if you have a `basic` service that requires ports `8080` and `10009`.
+
+* port 8080 could be a HTTP based port and you want to route to this using a route in `.lagoon.yml`
+* port 10009 could be used by other services within the environment for internal communications
+
+
+You would define your service to consume the `ports` like so:
+
+```yaml title="docker-compose.yml service port snippet"
+version: '2'
+services:
+  custom:
+    build:
+      context: internal/testdata/basic/docker
+      dockerfile: Dockerfile
+    labels:
+      lagoon.type: basic
+      lagoon.service.usecomposeports: true
+    ports:
+      - "8080"
+      - "10009"
+```
+
+The first port in the list of ports will be the "default" port for the service, so standard routes like so will route to the default port.
+An example `.lagoon.yml` is show how this looks the same as any other standard service route.
+
+```yaml title=".lagoon.yml default port route"
+environments:
+  main:
+    routes:
+      - custom:
+        - example.com
+```
+
+Alternatively, if you wanted to also have a route specifically for port 10009, you could define the route like so in your `.lagoon.yml`.
+
+```yaml title=".lagoon.yml default and alternative port route"
+environments:
+  main:
+    routes:
+      - custom-10009:
+        - otherport.example.com
+```
+
+!!! info
+    You can define both the "default" route and a custom port route together, as long as they have different domains used.
+
 ## Multi-Container Pods
 
 Kubernetes and OpenShift don't deploy plain containers. Instead, they deploy pods, with each one or more containers. Usually Lagoon creates a single pod with a container inside for each defined `docker-compose` service. For some cases, we need to put two containers inside a single pod, as these containers are so dependent on each other that they should always stay together. An example for such a situation is the PHP and NGINX containers that both contain PHP code of a web application like Drupal.

docs/concepts-basics/lagoon-yml.md

@@ -61,6 +61,144 @@ routes](#environmentsnameroutes) are defined per environment.
         - it
   ```
 
+### Path Based Routes
+
+Path based routes allows you to define paths on a route to a different backend. This can be used if you have a separate backend within the environment that you want to route traffic to on the same domain as another service within your environment.
+
+!!! warning
+    Path based routes can get quite complex and should only be used if you have a need to use them.
+
+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.
+
+```yaml title=".lagoon.yml path based 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
+
+It is possible to configure global autogenerated routes, these would apply to ALL environments that this `.lagoon.yml` file would cover.
+
+Additionally, per environment autogenerated route configurations are supported, the fields are the same, just where they are defined is different.
+
+```yaml title=".lagoon.yml autogenerated path based routes"
+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
+```
+!!! info
+    If the per environment path routes are defined on an environment, any global defined ones are ignored.
+
+The supported fields for autogenerated path routes 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.
+
+```yaml title=".lagoon.yml custom route path based routes"
+environments:
+  main:
+    routes:
+      - nginx:
+        - a.example.com:
+            pathRoutes:
+              - toService: node
+                path: /api/v1
+```
+The fields are the same, except that you can omit `fromService` due to the way that custom routes are defined already 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 Service Ports
+
+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`. See [Additional Service Ports](docker-compose-yml.md/#additional-service-ports) for more information on this label.
+
+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`.
+
+```yaml title="docker-compose.yml path based routes"
+services:
+  nginx:
+    build:
+      context: .
+      dockerfile: basic.dockerfile
+    labels:
+      lagoon.type: nginx
+      lagoon.service.usecomposeports: true
+    ports:
+      - '8080'
+  node:
+    build:
+      context: .
+      dockerfile: basic.dockerfile
+    labels:
+      lagoon.type: basic
+      lagoon.service.usecomposeports: true
+    ports:
+      - '1234'
+      - '4321'
+```
+Then you could create a route that would route `a.example.com` traffic to the `nginx` service. But any traffic destined for `a.example.com/api/v1` would go to the `node` service on port `4321`
+
+```yaml title=".lagoon.yml custom route path based routes"
+environments:
+  main:
+    routes:
+      - nginx:
+        - a.example.com:
+            pathRoutes:
+              - toService: node-4321
+                path: /api/v1
+```
+
+##### 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
+
+In Lagoon, currently only `Prefix` type is supported on ingress (see [Ingress path types](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types)).
+
 ## Tasks
 
 There are different type of tasks you can define, and they differ in when exactly they are executed in a build flow: