Routes

Route resources manage how HTTP traffic is directed to Lagoon environments. There are three route resource types: individual API-managed routes, and autogenerated route configuration at the project and environment levels.

Route resources require Lagoon v2.29.0 or later.

---

Route

A Route is an API-managed route attached to a project and optionally scoped to a specific environment. Both projectName and domain are force-new — changing either recreates the route.

Properties

Property	Type	Required	Description
projectName	string	Yes	Project name (force-new)
domain	string	Yes	Route domain — unique identifier within the project (force-new)
service	string	No	Service to route traffic to
environment	string	No	Environment name to attach the route to
tlsAcme	bool	No	Enable ACME TLS certificate
insecure	string	No	Insecure behavior: Allow, Redirect, or None
routeType	string	No	Route type: STANDARD, ACTIVE, or STANDBY
primary	bool	No	Whether this is the primary route
monitoringPath	string	No	Path for uptime monitoring
disableRequestVerification	bool	No	Disable request verification
hstsEnabled	bool	No	Enable HSTS
hstsMaxAge	int	No	HSTS max age in seconds
hstsPreload	bool	No	Enable HSTS preload
hstsIncludeSubdomains	bool	No	Include subdomains in HSTS
annotations	list of {key, value}	No	Route annotations (key/value pairs)
alternativeNames	list of string	No	Alternative domain names (max 25)
pathRoutes	list of {path, toService}	No	Path-based routing rules (max 10)

Outputs

Output	Type	Description
lagoonId	int	Lagoon internal route ID
source	string	Source of the route: API, YAML, or AUTOGENERATED
created	string	Timestamp when the route was created
updated	string	Timestamp when the route was last updated

The monitoringPath field uses a create-then-update pattern due to a Lagoon API limitation. If the follow-up update fails, the provider emits a warning and returns success with monitoringPath=nil in state. The next pulumi up will retry the update.

Import

Import using the project name and domain, separated by a colon:

pulumi import lagoon:lagoon:Route my-route my-site:www.example.com

Examples

Python TypeScript Go C#

import pulumi
import pulumi_lagoon as lagoon

# Standard route with TLS
main_route = lagoon.Route("www-route",
    lagoon.RouteArgs(
        project_name="my-site",
        domain="www.example.com",
        environment="main",
        service="nginx",
        tls_acme=True,
        insecure="Redirect",
        primary=True,
        monitoring_path="/health",
    )
)

# Route with alternative names and path routing
api_route = lagoon.Route("api-route",
    lagoon.RouteArgs(
        project_name="my-site",
        domain="api.example.com",
        environment="main",
        service="api",
        tls_acme=True,
        insecure="Redirect",
        alternative_names=["api-v2.example.com"],
        path_routes=[
            lagoon.RoutePathRouteArgs(path="/v1", to_service="api-v1"),
            lagoon.RoutePathRouteArgs(path="/v2", to_service="api-v2"),
        ],
    )
)

# Route with HSTS
secure_route = lagoon.Route("secure-route",
    lagoon.RouteArgs(
        project_name="my-site",
        domain="secure.example.com",
        environment="main",
        service="nginx",
        tls_acme=True,
        hsts_enabled=True,
        hsts_max_age=31536000,
        hsts_preload=True,
        hsts_include_subdomains=True,
    )
)

pulumi.export("main_route_id", main_route.lagoon_id)

import * as pulumi from "@pulumi/pulumi";
import * as lagoon from "@tag1consulting/pulumi-lagoon";

const mainRoute = new lagoon.Route("www-route", {
    projectName: "my-site",
    domain: "www.example.com",
    environment: "main",
    service: "nginx",
    tlsAcme: true,
    insecure: "Redirect",
    primary: true,
    monitoringPath: "/health",
});

export const mainRouteId = mainRoute.lagoonId;

package main

import (
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    lagoon "github.com/tag1consulting/pulumi-lagoon-provider/sdk/go/lagoon/lagoon"
)

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        mainRoute, err := lagoon.NewRoute(ctx, "www-route", &lagoon.RouteArgs{
            ProjectName:    pulumi.String("my-site"),
            Domain:         pulumi.String("www.example.com"),
            Environment:    pulumi.String("main"),
            Service:        pulumi.String("nginx"),
            TlsAcme:        pulumi.Bool(true),
            Insecure:       pulumi.String("Redirect"),
            Primary:        pulumi.Bool(true),
            MonitoringPath: pulumi.String("/health"),
        })
        if err != nil {
            return err
        }

        ctx.Export("mainRouteId", mainRoute.LagoonId)
        return nil
    })
}

using Pulumi;
using Tag1Consulting.Lagoon.Lagoon;

return await Deployment.RunAsync(() =>
{
    var mainRoute = new Route("www-route", new RouteArgs
    {
        ProjectName = "my-site",
        Domain = "www.example.com",
        Environment = "main",
        Service = "nginx",
        TlsAcme = true,
        Insecure = "Redirect",
        Primary = true,
        MonitoringPath = "/health",
    });

    return new Dictionary<string, object?>
    {
        ["mainRouteId"] = mainRoute.LagoonId,
    };
});

---

ProjectAutogeneratedRouteConfig

A ProjectAutogeneratedRouteConfig controls the autogenerated route settings at the project level. This resource uses upsert semantics — create and update use the same Lagoon mutation.

The resource ID is {projectName}, and projectName is force-new.

Properties

Property	Type	Required	Description
projectName	string	Yes	Project name (force-new)
enabled	bool	No	Enable autogenerated routes for this project
allowPullRequests	bool	No	Allow autogenerated routes for pull request environments
prefixes	list of string	No	Domain prefixes for autogenerated route URLs
pathRoutes	list of {fromService, path, toService}	No	Default path-based routing rules
disableRequestVerification	bool	No	Disable request verification on autogenerated routes
insecure	string	No	Insecure behavior string
tlsAcme	bool	No	Enable ACME TLS on autogenerated routes

Import

pulumi import lagoon:lagoon:ProjectAutogeneratedRouteConfig my-site-routes my-site

Example

import pulumi
import pulumi_lagoon as lagoon

project_routes = lagoon.ProjectAutogeneratedRouteConfig("my-site-routes",
    lagoon.ProjectAutogeneratedRouteConfigArgs(
        project_name="my-site",
        enabled=True,
        allow_pull_requests=True,
        tls_acme=True,
        insecure="Redirect",
        prefixes=["www"],
    )
)

---

EnvironmentAutogeneratedRouteConfig

An EnvironmentAutogeneratedRouteConfig enables or disables autogenerated routes at the environment level, overriding the project-level setting.

The resource ID is {projectName}:{environmentName}. Both projectName and environmentName are force-new.

Properties

Property	Type	Required	Description
projectName	string	Yes	Project name (force-new)
environmentName	string	Yes	Environment name (force-new)
enabled	bool	No	Enable or disable autogenerated routes for this environment
allowPullRequests	bool	No	Allow autogenerated routes for pull request environments
prefixes	list of string	No	Custom prefixes for autogenerated route domains
pathRoutes	list of {fromService, path, toService}	No	Path-based routing rules for autogenerated routes
disableRequestVerification	bool	No	Disable request verification on autogenerated routes
insecure	string	No	How to handle insecure (HTTP) traffic: Allow, Redirect, or None
tlsAcme	bool	No	Enable Let’s Encrypt TLS for autogenerated routes

Import

pulumi import lagoon:lagoon:EnvironmentAutogeneratedRouteConfig main-routes my-site:main

Example

import pulumi
import pulumi_lagoon as lagoon

# Disable autogenerated routes for the develop environment
env_routes = lagoon.EnvironmentAutogeneratedRouteConfig("develop-routes",
    lagoon.EnvironmentAutogeneratedRouteConfigArgs(
        project_name="my-site",
        environment_name="develop",
        enabled=False,
    )
)