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
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.
| Key | Default | Meaning |
|---|---|---|
serverName | required | The server_name nginx answers for. |
port | none: always set it | Port nginx listens on, behind the block's address; clients connect to the address port in network.ports. Unset, the runtime passes port 0. |
root | a private temporary directory | Document 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. |
tls | none | Accepted 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
tlssetting is ignored. - One server block. There is no way to pass your own
nginx.conf. - Content under
rootis not replicated; each node serves what its own directory holds.
Source
- nix/blocks/web/nginx: the type's identity and JSON Schema.