Skip to content

Overlays

An overlay is essentially an extra compose file that is generated by the tool when starting a project (or running any other command to interact with it). This makes use of how you can supply many files to a docker compose command, and they are merged together behind the scenes.

Example merging

If we supplied the below files to docker compose with docker compose -f docker-compose.yaml -f docker-compose.extra.yaml, behind the scenes docker compose would start the services seen in the "Resulting compose file" tab.

services:
    api:
        image: myapi:latest

services:
    monitoring:
        image: mymonitor:latest

services:
    api:
        image: myapi:latest
    monitoring:
        image: mymonitor:latest

This gives this tool the ability to modify the docker compose config at runtime in various (and arguably powerful) ways. The overlays are generated and stored on disk before being included in the docker compose commands we run within the tool (for commands like up). If you want to inspect what the overrides file looks like you'll find it in ~/.orca/overlays/{workspace}/{project}.yaml; where workspace is the name of the workspace, and project is the name of project. There is only ever 1 overlay per project to keep things simple, all modifications made by orca will be included in this file.

Overlay scope

There are two ways to enable an overlay, and these depend mostly on whether the overlay is configured to be "workspace scoped" or "service scoped".

workspace scoped overlays are configured in the orca.workspace.yaml file. In the overlays section of the config is a sub-section for each globally scoped overlay. Each overlay may have it's own configuration within which would enable other overlays (see the network overlay).

service scoped overlays are configured by adding a label to the service in the original docker-compose file. When orca runs it will parse the docker compose file and if it detects one of these labels will generate the relevant overlay configuration for that service.

orca.panoptescloud.overlay-enabled/{overlay}

Whenever a workspace scoped overlay has been used for a project, you'll se this label orca.panoptescloud.overlay-enabled/{overlay} is added to each container that the overlay affected. The {overlay} part here, is the name fo the overlay that was enabled. This is to aid in debugging and understanding the affect that orca is having on the compose environment; hopefully everything just works, and it's never needed!

Note: only workspace-scoped overlays add this label, as the service scoped overlays are already configure via a label so that information would be present anyway.

Available Overlays

Overlay
Network & Aliases
TLS Injection