Blocks · Web and proxies

web/nginx

nginx web server. nginx serving one virtual host from a directory, as stateless replicas.

Overview

Runs the upstream nginx binary with a generated one-server configuration: it listens on port, answers for serverName and serves files from root. Replicas keep no state, so the block scales out like any active-active block and a VIP spreads requests over them.

This is the type the block model examples use. For automatic HTTPS or a reverse proxy, use web/caddy instead.

Shape
Stateless replicas
Reached at
Node port, or a VIP
Node package
pkgs.nginx

Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.nginx, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.

Example

nginx.yaml
apiVersion: expanse.io/v1
kind: Block
metadata:
  name: web
  namespace: default
spec:
  type: web/nginx
  replicas: 3
  placement:
    antiAffinity: ANTI_AFFINITY_NODE   # one replica per node
  resources:
    requests:
      cpu: 100m
      memory: 64Mi
  config:
    port: 18080
    serverName: web.example.internal
  network:
    ports:
      - name: http
        port: 80
        target_port: 18080
        protocol: tcp
        expose: EXPOSE_VIP
    health_check:
      readiness:
        type: PROBE_HTTP
        path: /
        port: 18080
        period_seconds: 5
$ expanse ctl block apply -f nginx.yaml --dry-run   # validate only
$ expanse ctl block apply -f nginx.yaml

Configuration

Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.

KeyDefaultMeaning
serverNamerequiredThe server_name nginx answers for.
portnone: always set itPort nginx listens on, behind the block's address; clients connect to the address port in network.ports. Unset, the runtime passes port 0.
roota private temporary directoryDocument root. It is created if missing, and an index.html placeholder is written when the directory has none. The unit is sandboxed (ProtectSystem=strict), so the directory must be one it can write.
tlsnoneAccepted by the schema (cert and key paths) but not applied: the runtime always serves plain HTTP. Put web/caddy in front for HTTPS.

Using it

Apply the block, then request any replica through the VIP:

$ expanse ctl block apply -f web.yaml
$ expanse ctl block get web         # shows the VIP
$ curl http://<VIP>/

With no root set, every replica serves the same placeholder page, which is enough to check the load balancer. Rolling updates follow strategy.update (see the fields every block shares).

When a node fails

Replicas hold nothing, so a node failure only removes that node's replica from the VIP's pool. After the unreachable grace (30 s) the controller places a replacement on another node, under the same anti-affinity rules.

Limits

  • No TLS: the tls setting is ignored.
  • One server block. There is no way to pass your own nginx.conf.
  • Content under root is not replicated; each node serves what its own directory holds.

Source

All block types · Fields every block shares