Building¶
wxingress has three parts:
| Part | Language | Built with |
|---|---|---|
The controller (cmd/nginx-ingress, internal/, pkg/) |
Go | go build, make |
The data plane module (dataplane/) |
metalang | the metalang compiler, in the image docker.io/wxone/meta |
| The image | Dockerfile | build/Dockerfile.wxingress, from the two above and NGINX packages from nginx.org, on the hardened Debian 13 runtime seed of container.gov.de |
The controller¶
Requirements: Go (the version in go.mod), make, and Helm for the chart tests.
make secrets # test certificates and keys the tests read (generated, not committed)
make test # go test -tags=aws,helmunit -shuffle=on ./...
make build # the nginx-ingress binary
After a change to pkg/apis/configuration/v1/types.go, regenerate the code and the CRDs and commit
the result:
After a change to a template (internal/configs/version*/*.tmpl) or to what feeds it, update the
snapshots, and check that a fixture actually renders the new directive:
The data plane module¶
The module ngx_http_wxingress_module.so provides the dynamic upstreams, the balancers, the
ingress-nginx metrics and what NGINX Ingress Controller does in njs. It is written in metalang and compiled
to C by the metalang compiler, then built as a dynamic NGINX module against the exact NGINX version of the
image (NGINX_VERSION in dataplane/build.sh).
About metalang
metalang is the programming language WizardTales writes all of its software in. It is not open source
yet: it is still developed rapidly, and we keep the freedom to change it until others depend on it. It
is planned to be open-sourced in Q2-Q3 2027. Until then the compiler and its runtime are published as
the container image docker.io/wxone/meta, which is all you need to build the module.
docker run --rm -v "$PWD:/src" -w /src -e META=/opt/meta/meta \
docker.io/wxone/meta:44cb41f0 ./dataplane/build.sh
# the module: dataplane/build/ngx_http_wxingress_module.so
# a test nginx: dataplane/build/nginx/sbin/nginx
./dataplane/build.sh test # the data plane tests against that nginx
NGINX version
NGINX loads a dynamic module only if it was built against exactly the same version. When you raise
the NGINX version, change it in dataplane/build.sh, build/Dockerfile,
build/Dockerfile.wxingress, the Makefile and .github/workflows/ci.yml together.
The image¶
CGO_ENABLED=0 go build -trimpath -o nginx-ingress ./cmd/nginx-ingress
docker build -f build/Dockerfile.wxingress -t wxingress:dev \
--build-arg IC_VERSION=dev .
build/Dockerfile.wxingress expects the controller binary nginx-ingress and
dataplane/build/ngx_http_wxingress_module.so in the build context. It has two stages:
- assemble, on the Debian snapshot the seed's own builder uses (by digest): installs NGINX, njs and
the OpenTelemetry module from nginx.org - the signing key checked by its SHA-256 (
ADD --checksum) and against nginx.org's published fingerprints - loads all three modules withnginx -t, and puts into/rootfswhat the image carries: NGINX andnginx-debug, the modules,/etc/nginx, the templates, the njs scripts, the controller, the licences, every shared librarylddproves for NGINX and the modules (andlibgcc_s), and/usr/share/doc/wxingress/PACKAGES, the Debian and nginx.org packages those files come from, for the SBOM. Binaries, templates and libraries are root's and read-only; what the controller and NGINX write belongs to 101:0. NGINX,nginx-debugand/nginx-ingressget the file capabilitycap_net_bind_service(it survivesCOPY --from). - the final stage: the runtime seed
(
registry.opencode.de/oci-community/images/auswaertiges-amt/debian:13.7, by digest) with/rootfson top,USER 101.
There is no shell in the image. The chart runs the two things it needs besides the controller as
subcommands of the controller binary: /nginx-ingress sleep <seconds> (the preStop hook before
Kubernetes 1.30) and /nginx-ingress copy <source> <dest> (the init container with a read-only root
file system). To look inside, use docker cp or run nginx as entrypoint:
The SBOMs of a build:
ci/sbom.sh release dev nginx-ingress dataplane/build/ngx_http_wxingress_module.so > release.cdx.json
ci/sbom.sh image release.cdx.json wxingress:dev wxingress:dev > image.cdx.json
When container.gov.de publishes a new seed, update SEED and the assemble stage's snapshot together.
End-to-end tests¶
The scripts in dataplane/e2e/ run against a kind cluster and need Docker, kind, kubectl and Helm:
| Script | What it tests |
|---|---|
ingress-nginx-parity.sh |
the same answers as ingress-nginx and rke2-ingress-nginx for the 97-Ingress corpus, and a switch under load |
ingress-nginx-bench.sh |
throughput, latency, CPU and memory against ingress-nginx |
ingress-nginx-annotations.sh |
each supported ingress-nginx annotation |
admission-webhook.sh |
what the admission webhook admits and refuses |
gateway.sh, gateway-namespaces.sh |
the Gateway API |
gateway-conformance/run.sh |
the Gateway API conformance suite |
transportserver.sh, certificates.sh |
TransportServers and certificate handling |
CI¶
.github/workflows/ci.yml runs the Go tests, builds the controller, builds and tests the data plane
module with the metalang compiler, and lints the chart, on every push and pull request.
.github/workflows/release.yml runs on tags v<major>.<minor>.<patch>[-wx<n>] whose commit is on
main. In the GitHub Environment release (its protection rules gate every push) it builds the image,
pushes it to ghcr.io/wx-one/wxingress (:latest only for the highest version), signs it with cosign
(keyless), attaches build provenance and SBOM attestations, pushes the chart with the image's digest to
oci://ghcr.io/wx-one/charts, and creates a GitHub release. Releases always build the data plane with
the metalang compiler of ci/meta-image; the META_IMAGE override (by digest) applies to runs of
ci.yml alone. All actions are pinned by commit.