From 099381df954aae0b201337c74044bc69b3a8c62e Mon Sep 17 00:00:00 2001 From: shreddedbacon Date: Wed, 30 Oct 2024 11:13:55 +1100 Subject: [PATCH] docs: add docs for compose ports and path routes --- docs/concepts-advanced/service-types.md | 12 +- docs/concepts-basics/docker-compose-yml.md | 93 +++++++++++++- docs/concepts-basics/lagoon-yml.md | 138 +++++++++++++++++++++ 3 files changed, 240 insertions(+), 3 deletions(-) diff --git a/docs/concepts-advanced/service-types.md b/docs/concepts-advanced/service-types.md index 37840c6c22..ed1b26de88 100644 --- a/docs/concepts-advanced/service-types.md +++ b/docs/concepts-advanced/service-types.md @@ -2,11 +2,19 @@ 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) + +## 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) diff --git a/docs/concepts-basics/docker-compose-yml.md b/docs/concepts-basics/docker-compose-yml.md index 0fa495623e..6fab1d395e 100644 --- a/docs/concepts-basics/docker-compose-yml.md +++ b/docs/concepts-basics/docker-compose-yml.md @@ -167,7 +167,9 @@ 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 volume to an existing `-persistent` service type ```yaml title="docker-compose.yml volume usage snippet" services: @@ -182,6 +184,41 @@ 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. + +### 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 ``` Note that the original volume created for this service still exists. @@ -219,6 +256,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. diff --git a/docs/concepts-basics/lagoon-yml.md b/docs/concepts-basics/lagoon-yml.md index 8eb4c67799..3b7b2736f2 100644 --- a/docs/concepts-basics/lagoon-yml.md +++ b/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: