Lagoon Documentation

The Lagoon Actions Handler is a service designed to process background actions within the Lagoon platform. It is used for non-urgent, long-running operations that should not block the main user interface or critical API paths. Examples of handled actions include:

• Bulk deployments
• Bulk tasks
• Other non-urgent background processes

The actions-handler is a service responsible for processing messages received from message queues to synchronize state across the Lagoon platform. It acts as a central consumer for various inter-core events and remote-controller communications.

Key responsibilities include:

• Triggering bulk deploy environment commands.
• Updating environment storage information received from storage-calculator.
• Updating deployments and environments based on updates from Lagoon builds.
• Updating tasks based on updates from Lagoon tasks.
• Removing environments from Lagoon when they are deleted in remote systems.

The php-cli image is a specialized Docker image designed for daily operations within Lagoon. It is intended to be used as a base for any cli needs, specifically for containers (or pods) responsible for building code for Composer or Node.js based projects. It also includes database clients for MariaDB and PostgreSQL.

Key features include:

• Automatic folder permission adaptation via fix-permissions.
• COMPOSER_ALLOW_SUPERUSER=1 is pre-configured to allow Composer to run as root without warnings.
• An idle timeout script (80-shell-timeout.sh) that sets a 10-minute timeout for idle cli pods in Kubernetes.
• SSH key support via Lagoon injection or the SSH_PRIVATE_KEY environment variable.

The ssh service serves as the primary entrypoint for all SSH-related connections and commands within Lagoon projects. It facilitates two main types of authenticated actions using standard SSH public/private keys:

1. API Authentication: Requesting a token that can be used to authenticate against the Lagoon API.
2. Environment Access: Connecting via SSH directly to a Lagoon project environment.

While many users interact with this service transparently (for example, when using Drush for Drupal projects), it can be used directly for non-Drush workflows requiring command-line access to project environments.

Lagoon provides support for a variety of PHP-based application frameworks. Common supported applications include:

• Drupal
• Laravel
• WordPress
• Magento
• Symfony

Lagoon provides several categories of logs to help with debugging and monitoring:

• Kubernetes Routers: Detailed HTTP/HTTPS request logs including Source IP, URL, Path, HTTP verb, Cookies, Headers, User agent, Project, Container name, Response size, and Response time.
• Containers: Standard stdout and stderr messages, tagged with the Container name and Project.
• Lagoon Logs: System-level logs covering Webhooks parsing, Build logs, and Build errors.
• Application Logs: Specific logs generated by your application code (see below for implementation details).

The api-sidecar-handler is a microservice designed to run as a sidecar to the api service within Lagoon. Its primary responsibilities are performing validations and generations for SSH keys used throughout the Lagoon platform.

It serves two main purposes:

1. SSH Key Management: It replaces the functionality of the sshpk package to provide broader support for various SSH key types.
2. Task Orchestration: It can handle processes that were previously managed by webhooks2tasks.

Lagoon utilizes Keycloak as its central identity and access management service. It is responsible for:

• Storing user data.
• Managing authentication and authorization for all Lagoon clients (including the API, UI, and CLI).
• Facilitating Single Sign-On (SSO) with third-party identity providers.

Lagoon relies on three primary configuration mechanisms to manage deployments and local environments:

1. .lagoon.yml: The main configuration file used by Lagoon to determine what should be deployed and how the project is structured.
2. docker-compose.yml: Used by Docker Compose to start your local development environment. Lagoon also parses this file via labels to understand which services should be deployed, their types, and how to build them.
3. Dockerfiles: Used for customizing images. This is necessary for:
   • Application code: Injecting code (e.g., NGINX, PHP, Node.js) into images during the build step.
   • Image customization: Injecting environment variables, changing service configurations, or installing additional tools.

Lagoon uses the Aergia controller (installed in lagoon-remote) to automatically idle environments that have been unused for a defined period. This reduces Kubernetes cluster load and improves performance for active production and development environments.

Default Idling Behavior

Note: Defaults may vary depending on your specific Lagoon installation.

• Frequency: Idling checks are attempted every 4 hours.
• Production Protection: Production environments are never idled.
• CLI Pods: Idled if they do not include a cron job and no remote shell connection is active.
• Services/Pods: Idled if there has been no traffic on the environment in the last 4 hours.
• Build Protection: If an active build is in progress, idling will not occur.