OpenMCF logoOpenMCF

Loading...

Scaleway Load Balancer

Deploys a managed Scaleway Load Balancer that bundles a Flexible IP, the LB appliance, backend server pools, frontend listeners, and optional TLS certificates into a single declarative resource. The Load Balancer distributes incoming Layer 4/7 traffic across backend servers based on configurable forwarding rules, health checks, and load-balancing algorithms.

What Gets Created

When you deploy a ScalewayLoadBalancer resource, OpenMCF provisions:

  • Flexible IP — a dedicated loadbalancers.Ip public IPv4 address with independent lifecycle that survives LB replacement
  • Load Balancer — a loadbalancers.LoadBalancer appliance of the specified type, with optional Private Network attachment
  • Backend(s) — one or more loadbalancers.Backend server pools with health checks and load-balancing configuration
  • Frontend(s) — one or more loadbalancers.Frontend listeners that route inbound traffic to backends
  • Certificate(s) — zero or more loadbalancers.Certificate resources (Let's Encrypt or custom PEM) for HTTPS frontends
  • Scaleway Tags — resource kind, name, organization, and environment labels applied as flat key=value tags

Prerequisites

  • Scaleway credentials configured via environment variables or OpenMCF provider config
  • A target zone — Load Balancers are zonal resources (e.g., fr-par-1, nl-ams-1, pl-waw-1)
  • Backend server IPs — at least one server IP per backend, reachable from the LB (public IPs or private IPs if attached to a Private Network)
  • (Optional) A Private Network — either a literal Private Network UUID or an OpenMCF-managed ScalewayPrivateNetwork resource whose output can be referenced via valueFrom

Quick Start

Create a file load-balancer.yaml:

apiVersion: scaleway.openmcf.org/v1
kind: ScalewayLoadBalancer
metadata:
  name: my-lb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.ScalewayLoadBalancer.my-lb
spec:
  zone: fr-par-1
  type: LB-S
  backends:
    - name: web
      serverIps:
        - "10.0.1.10"
      forwardPort: 80
      forwardProtocol: http
  frontends:
    - name: http
      inboundPort: 80
      backendName: web

Deploy:

openmcf apply -f load-balancer.yaml

This creates a small Load Balancer in fr-par-1 with a single HTTP backend and frontend on port 80. The public IP is available in stack outputs as lb_ip_address.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
zonestringScaleway zone where the Load Balancer is created (e.g., "fr-par-1", "nl-ams-1"). Must be within the same region as any attached Private Network. Cannot be changed after creation.Required
typestringLoad Balancer type that determines bandwidth and pricing tier. Options: "LB-S" (up to 400 Mbps), "LB-GP-M" (up to 4 Gbps), "LB-GP-L" (up to 8 Gbps), "LB-GP-XL" (up to 10 Gbps). Recommended default: "LB-S". Can be changed after creation.Required
backendsBackend[]One or more backend server pools. Each backend defines a named set of servers, a forwarding port and protocol, health check rules, and load-balancing configuration.Required, min 1 item
backends[].namestringUnique name identifying this backend. Frontends reference backends by this name.Required
backends[].serverIpsstring[]IP addresses of backend servers. Use private IPs when the LB is attached to a Private Network; use public IPs otherwise.Required, min 1 item
backends[].forwardPortintPort on backend servers that receives forwarded traffic (e.g., 80, 443, 8080).Required
backends[].forwardProtocolstringProtocol for LB-to-backend communication. Options: "http", "https", "tcp". Recommended default: "http".Required
frontendsFrontend[]One or more frontend listeners. Each frontend listens on a port and routes traffic to a named backend.Required, min 1 item
frontends[].namestringUnique name identifying this frontend.Required
frontends[].inboundPortintTCP port to listen on for incoming connections (e.g., 80, 443). Must be unique across frontends.Required
frontends[].backendNamestringName of the backend to route traffic to. Must match a backend's name in spec.backends.Required

Optional Fields

FieldTypeDefaultDescription
privateNetworkIdStringValueOrRefnonePrivate Network to attach the LB to. When set, the LB receives a private IP and can reach backend servers on private addresses. Accepts a literal UUID or a valueFrom reference to a ScalewayPrivateNetwork's status.outputs.private_network_id.
descriptionstring""Human-readable description displayed in the Scaleway console.
sslCompatibilityLevelstring"ssl_compatibility_level_intermediate"Minimum TLS version for HTTPS frontends. Options: "ssl_compatibility_level_intermediate" (TLS 1.2+), "ssl_compatibility_level_modern" (TLS 1.3 only).
certificatesCertificate[][]TLS certificates for HTTPS frontends. Each certificate is either Let's Encrypt auto-provisioned or a custom PEM chain. Frontends reference certificates by name.
certificates[].namestring—Unique name for the certificate. Frontends reference this in their certificateNames field. Required when a certificate entry is present.
certificates[].letsencrypt.commonNamestring—Primary domain for a Let's Encrypt certificate. Domain must resolve to the LB's public IP. Exactly one of letsencrypt or customCertificate must be set.
certificates[].letsencrypt.subjectAlternativeNamesstring[][]Additional domains covered by the Let's Encrypt certificate. All SANs must resolve to the LB's IP.
certificates[].customCertificate.certificateChainstring—Full PEM certificate chain (server cert + intermediates). Exactly one of letsencrypt or customCertificate must be set.
backends[].forwardPortAlgorithmstring"roundrobin"Load-balancing algorithm. Options: "roundrobin", "leastconn", "first".
backends[].stickySessionsstring"none"Sticky session type. Options: "none", "cookie", "table".
backends[].stickySessionsCookieNamestring""Cookie name for sticky sessions. Required when stickySessions is "cookie".
backends[].healthCheck.typestring"tcp"Health check protocol. Options: "tcp", "http", "https".
backends[].healthCheck.uristring"/"URI path for HTTP/HTTPS health checks. Ignored for TCP checks.
backends[].healthCheck.expectedCodeint200Expected HTTP status code for a healthy response. Ignored for TCP checks.
backends[].healthCheck.checkDelaystring"5s"Interval between health check probes.
backends[].healthCheck.checkTimeoutstring"3s"Maximum time to wait for a health check response. Must be less than checkDelay.
backends[].healthCheck.checkMaxRetriesint3Consecutive failed checks before marking a server as unhealthy.
backends[].healthCheck.portintsame as forwardPortPort to send health check probes to. Set when health checks use a dedicated monitoring port.
backends[].timeoutConnectstringScaleway defaultMaximum time to wait for a connection to a backend server (e.g., "5s").
backends[].timeoutServerstringScaleway defaultMaximum idle time for a backend connection before it is closed (e.g., "30s").
backends[].onMarkedDownActionstring"none"Action when a server is marked down. Options: "none", "shutdown_sessions".
backends[].sslBridgingboolfalseWhen true, the LB re-encrypts traffic to backend servers (TLS between LB and backends).
backends[].proxyProtocolstring"none"PROXY protocol version for passing client metadata to backends. Options: "none", "v1", "v2", "v2_ssl", "v2_ssl_cn".
frontends[].certificateNamesstring[][]Names of TLS certificates to attach. Must match entries in spec.certificates. Required for HTTPS frontends.
frontends[].timeoutClientstringScaleway defaultMaximum idle time for a client connection before it is closed (e.g., "30s").
frontends[].enableHttp3boolfalseWhen true, the frontend accepts HTTP/3 (QUIC) connections in addition to HTTP/1.1 and HTTP/2. Requires a TLS certificate.

Examples

Minimal HTTP Load Balancer

A single-backend, single-frontend Load Balancer for development or internal services:

apiVersion: scaleway.openmcf.org/v1
kind: ScalewayLoadBalancer
metadata:
  name: dev-lb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.ScalewayLoadBalancer.dev-lb
spec:
  zone: fr-par-1
  type: LB-S
  backends:
    - name: web
      serverIps:
        - "10.0.1.10"
      forwardPort: 8080
      forwardProtocol: http
      healthCheck:
        type: http
        uri: /health
        expectedCode: 200
  frontends:
    - name: http
      inboundPort: 80
      backendName: web

HTTPS Load Balancer with Let's Encrypt and Private Network

A production-grade Load Balancer with automatic TLS, HTTP-to-HTTPS frontend pairing, a Private Network attachment, and HTTP health checks:

apiVersion: scaleway.openmcf.org/v1
kind: ScalewayLoadBalancer
metadata:
  name: prod-lb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.ScalewayLoadBalancer.prod-lb
spec:
  zone: fr-par-1
  type: LB-GP-M
  privateNetworkId:
    valueFrom:
      kind: ScalewayPrivateNetwork
      name: app-network
      fieldPath: status.outputs.private_network_id
  description: "Production web load balancer"
  sslCompatibilityLevel: ssl_compatibility_level_intermediate
  certificates:
    - name: app-cert
      letsencrypt:
        commonName: app.example.com
        subjectAlternativeNames:
          - www.example.com
  backends:
    - name: web
      serverIps:
        - "10.0.1.10"
        - "10.0.1.11"
        - "10.0.1.12"
      forwardPort: 8080
      forwardProtocol: http
      forwardPortAlgorithm: leastconn
      stickySessions: cookie
      stickySessionsCookieName: SERVERID
      healthCheck:
        type: http
        uri: /ready
        expectedCode: 200
        checkDelay: "10s"
        checkTimeout: "5s"
        checkMaxRetries: 3
      timeoutConnect: "5s"
      timeoutServer: "60s"
      onMarkedDownAction: shutdown_sessions
  frontends:
    - name: http
      inboundPort: 80
      backendName: web
    - name: https
      inboundPort: 443
      backendName: web
      certificateNames:
        - app-cert
      enableHttp3: true

Multi-Backend TCP Load Balancer with PROXY Protocol

A Load Balancer routing traffic to separate backend pools (API and gRPC), using TCP forwarding and PROXY protocol to preserve client IPs:

apiVersion: scaleway.openmcf.org/v1
kind: ScalewayLoadBalancer
metadata:
  name: gateway-lb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.ScalewayLoadBalancer.gateway-lb
spec:
  zone: nl-ams-1
  type: LB-GP-L
  privateNetworkId:
    valueFrom:
      kind: ScalewayPrivateNetwork
      name: infra-network
      fieldPath: status.outputs.private_network_id
  backends:
    - name: api
      serverIps:
        - "10.0.2.10"
        - "10.0.2.11"
      forwardPort: 3000
      forwardProtocol: tcp
      forwardPortAlgorithm: leastconn
      proxyProtocol: v2
      healthCheck:
        type: tcp
        checkDelay: "5s"
        checkTimeout: "3s"
        checkMaxRetries: 3
      timeoutConnect: "5s"
      timeoutServer: "300s"
    - name: grpc
      serverIps:
        - "10.0.2.20"
        - "10.0.2.21"
      forwardPort: 50051
      forwardProtocol: tcp
      proxyProtocol: v2
      sslBridging: true
      healthCheck:
        type: tcp
        checkDelay: "10s"
        checkTimeout: "5s"
        checkMaxRetries: 5
  frontends:
    - name: api
      inboundPort: 443
      backendName: api
      timeoutClient: "60s"
    - name: grpc
      inboundPort: 50051
      backendName: grpc
      timeoutClient: "300s"

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
lb_idstringZoned ID of the created Load Balancer (e.g., "fr-par-1/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"). Can be used to reference the LB in Scaleway APIs.
lb_ip_addressstringPublic IPv4 address assigned to the Load Balancer's Flexible IP. This is the address clients connect to. Use for DNS A records (via ScalewayDnsRecord), firewall allowlists, and monitoring.
lb_ip_idstringZoned ID of the Flexible IP resource. The IP has independent lifecycle and survives LB replacement.

Related Components

  • ScalewayPrivateNetwork — the Private Network that the Load Balancer attaches to for private backend connectivity
  • ScalewayVpc — the parent VPC containing the Private Network
  • ScalewayInstance — compute instances that serve as backend servers behind the Load Balancer
  • ScalewayDnsRecord — DNS records that can reference status.outputs.lb_ip_address to point a domain to the Load Balancer
  • ScalewayInstanceSecurityGroup — controls network access for backend instances

Next article

Scaleway MongoDB Instance

Scaleway MongoDB Instance Deploys a Scaleway Managed MongoDB instance with an admin user, optional additional users with role-based access control, Private Network attachment, and automated snapshot scheduling. Supports standalone (single-node) and replica set (three-node) topologies with block storage volumes and TLS certificates. What Gets Created When you deploy a ScalewayMongodbInstance resource, OpenMCF provisions: MongoDB Instance — a mongodb.Instance resource providing a fully managed...
Read next article
Presets
2 ready-to-deploy configurationsView presets →