// Docker image build system, Dockerfile structure, image variants, build scripts, and Makefile targets for NIC. Use when building container images, modifying the Dockerfile, adding new image variants, debugging image builds, or working with build scripts.
| name | nic-docker-images |
| description | Docker image build system, Dockerfile structure, image variants, build scripts, and Makefile targets for NIC. Use when building container images, modifying the Dockerfile, adding new image variants, debugging image builds, or working with build scripts. |
Single build/Dockerfile (~850 lines), heavily multi-stage. The BUILD_OS arg selects which base image stage is used.
nginx-files (scratch) <- Collects repo files, signing keys, scripts
|
OS-specific base stages <- One per variant (debian, alpine, ubi, *-plus, *-nap)
|
FROM ${BUILD_OS} AS common <- Runs common.sh + patch-os.sh, sets permissions
|
TARGET stages (final image) <- local, container, goreleaser, debug, download, aws, patched
3 OS families x 2 NGINX editions x optional NAP = ~20 variants.
| OS | OSS | Plus | Plus+WAF | Plus+WAFv5 | Plus+DoS | Plus+WAF+DoS | Plus+FIPS | Plus+WAF+FIPS | Plus+WAFv5+FIPS |
|---|---|---|---|---|---|---|---|---|---|
| Debian | yes | yes | yes | yes | yes | yes | - | - | - |
| Alpine | yes | yes | - | - | - | - | yes | yes | yes |
| UBI 10 | yes | yes | yes | yes | yes | yes | - | - | - |
Architecture: amd64 + arm64 for OSS and Plus. NAP variants are amd64 only.
All targets call docker build --platform linux/$(ARCH) --target $(TARGET) -f build/Dockerfile.
| Target | BUILD_OS | NAP_MODULES |
|---|---|---|
debian-image | debian | - |
alpine-image | alpine | - |
ubi-image | ubi | - |
debian-image-plus | debian-plus | - |
alpine-image-plus | alpine-plus | - |
alpine-image-plus-fips | alpine-plus-fips | - |
alpine-image-nap-plus-fips | alpine-plus-nap-fips | waf |
alpine-image-nap-v5-plus-fips | alpine-plus-nap-v5-fips | waf |
ubi-image-plus | ubi-10-plus | - |
debian-image-nap-plus | debian-plus-nap | waf |
debian-image-nap-v5-plus | debian-plus-nap-v5 | waf |
debian-image-dos-plus | debian-plus-nap | dos |
debian-image-nap-dos-plus | debian-plus-nap | waf,dos |
ubi-image-nap-plus | ubi-10-plus-nap | waf |
ubi-image-nap-v5-plus | ubi-10-plus-nap-v5 | waf |
ubi-image-dos-plus | ubi-10-plus-nap | dos |
ubi-image-nap-dos-plus | ubi-10-plus-nap | waf,dos |
all-images | Builds 18 variants | - |
push | docker push to PREFIX:TAG | - |
patch-os | OS patches existing image | - |
Plus images receive $(PLUS_ARGS): --secret id=nginx-repo.crt --secret id=nginx-repo.key.
| Target | Use Case |
|---|---|
local | Default -- binary pre-built on host, copied in |
container | Binary built inside Docker (multi-arch capable) |
goreleaser | Binary from GoReleaser dist/ (CI builds) |
debug | Includes delve debugger |
download | Extracts binary from published Docker Hub image |
aws | AWS marketplace variant |
patched | OS patches an existing image |
| Arg | Purpose | Example |
|---|---|---|
BUILD_OS | Base image stage | debian, alpine-plus, ubi-10-plus-nap |
IC_VERSION | Ingress controller version | 5.5.0 |
NGINX_PLUS_VERSION | NGINX Plus version | R36 |
NAP_MODULES | App Protect modules | waf, dos, waf,dos |
PREBUILT_BASE_IMG | Base for prebuilt targets | GCR image ref |
build/scripts/)| Script | Purpose |
|---|---|
common.sh | Sets up directories, copies NGINX templates (v1/v2), sets file permissions (101:0), runs setcap on nginx binaries |
agent.sh | Configures nginx-agent ownership; creates NMS compiler symlinks for NAP v4 |
nap-waf.sh | Creates WAF directories (/etc/nginx/waf/nac-policies, /opt/app_protect/) |
nap-dos.sh | Creates DoS directories (/root/app_protect_dos, /shared/cores) |
ubi-setup.sh | UBI-specific: installs shadow-utils, creates nginx user/group (101:0) |
ubi-clean.sh | UBI-specific: removes build-time packages, cleans dnf cache |
setcap cap_net_bind_service for ports 80/443--mount=type=bind, --mount=type=secret, --mount=type=cache--secret mounts, never COPY into layers@sha256: digests for reproducibility; some stages intentionally use build-arg/tag-selected bases (for example BUILD_OS or download/prebuilt images)nginx-module-otel (OpenTelemetry) and nginx-agent (usage reporting)njs and fips-check modules# renovate: comments--secret mountsarm64 to NAP image matrices -- NAP is amd64 onlyBUILD_OS to select variants, not separate Dockerfilescommon stage unifies all variants -- changes there affect every imagecommon.sh detects Plus via BUILD_OS containing "plus" and creates OIDC directoriespatch-os.sh handles OS-level security updates at build timeDebugging and troubleshooting patterns for NIC. Use when diagnosing failures, tracing issues, investigating NGINX reload errors, config generation bugs, or controller sync problems.
Task planning and approach strategy for NIC. Use when starting any non-trivial task, reading issues or specs, planning before implementing, or when asked to create a plan for a change.
CI/CD pipeline structure, GitHub Actions workflows, reusable workflow patterns, and matrix builds for NIC. Use when working on CI workflows, debugging build failures, adding new workflow steps, modifying build matrices, or understanding the release pipeline.
NIC architecture, resource processing pipeline, template systems, and key type definitions. Use when exploring the codebase, understanding data flow, debugging config generation, or working on controller logic.
Checklists for adding Ingress annotations, VirtualServer/VSR fields, or Helm chart values to NIC. Use when adding new configuration options, new NGINX directives, new annotations, new CRD fields, or new Helm values.
Step-by-step checklist for adding a new Policy CRD type to NIC. Use when implementing a new policy like AccessControl, RateLimit, JWTAuth, ExternalAuth, BasicAuth, IngressMTLS, EgressMTLS, OIDC, WAF, APIKey, Cache, or CORS, or extending the policy system with a new policy type.