Chainguard Container for nginx-otel-fips

Minimal Wolfi-based nginx HTTP server with OpenTelemetry observability integration and FIPS 140-2 hardened cryptography

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/nginx-otel-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Chainguard's nginx-otel-fips container image extends the standard nginx functionality with OpenTelemetry instrumentation for distributed tracing and FIPS 140-2 hardened cryptography. It maintains all the compatibility features of the standard nginx Chainguard Container.

FIPS Support

The nginx-otel-fips Chainguard Container ships with a validated redistribution of OpenSSL's FIPS provider module. For more on FIPS support in Chainguard Containers, consult the guide on FIPS-enabled Chainguard Containers on Chainguard Academy.

Users

Like the standard nginx Chainguard Container, this image runs as a non-root nonroot user (UID/GID 65532) and does not require privilege escalation.

Default port

The default port for the nginx-otel-fips Chainguard Container is 8080, rather than 80.

IPv6 Support

By default, the container only listens on IPv4. You can add IPv6 support by mounting a configuration file with IPv6 listeners:

server {
    listen       8080;
    listen  [::]:8080;
    ...
}

OpenTelemetry Integration

This image includes the nginx OpenTelemetry module (ngx_otel_module) which enables distributed tracing with FIPS-compliant cryptographic operations. The module is available as an opt-in configuration and supports:

• OTLP (OpenTelemetry Protocol) trace export with FIPS-compliant TLS
• Configurable service names and endpoints
• Per-location tracing controls
• Integration with observability platforms like Jaeger, Zipkin, and others

Available nginx Modules

This image includes all nginx modules from the upstream nginx:otel image for feature parity:

• Core modules: HTTP
• Additional modules: GeoIP, Image Filter, XSLT Filter, JavaScript (njs)
• OpenTelemetry module: Distributed tracing and observability

Variants

Two variants are available following nginx's release strategy:

• stable: Based on nginx stable releases (even version numbers)
• mainline: Based on nginx mainline releases (odd version numbers) - tagged as latest

User Directive Warning

Starting the container gives the following warning:

 [warn] 1#1: the "user" directive makes sense only if the master process runs with super-user privileges, ignored in /etc/nginx/nginx.conf:2

This warning indicates the container is already running as the nonroot user, so the directive has no effect. The directive is included for compatibility with configurations that may run the container as root.

Entrypoint

The entrypoint for the nginx-otel-fips Chainguard Container is /docker-entrypoint.sh. Commands run as part of docker run will be passed as arguments to nginx.

Getting Started

The nginx-otel-fips Chainguard Container provides nginx with OpenTelemetry capabilities and FIPS-compliant cryptography. To try out the basic image:

docker run -p 8080:8080 cgr.dev/ORGANIZATION/nginx-otel-fips:latest

After starting the container, navigate to localhost:8080 in your web browser to see the default nginx welcome page.

OpenTelemetry Configuration

To enable OpenTelemetry tracing with FIPS-compliant cryptography, you need to include the module and configure the tracing endpoint. Here's a basic example:

# Include the OpenTelemetry module (opt-in)
include /etc/nginx/modules/10_otel.conf;

events {
    worker_connections 1024;
}

http {
    # Configure OpenTelemetry
    otel_exporter { endpoint jaeger:4317; }
    otel_trace on;
    otel_service_name nginx-test;

    server {
        listen 8080;
        location / { return 200 'OpenTelemetry enabled nginx response'; }
        location /health { return 200 'OK'; }
    }
}

Example with Jaeger

Here's a complete example running nginx-otel-fips with Jaeger for trace collection:

First, start Jaeger:

docker run -d --name jaeger \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 16686:16686 \
  cgr.dev/ORGANIZATION/jaeger-all-in-one:latest

Create an nginx configuration file:

mkdir -p nginx-conf
cat > nginx-conf/nginx.conf <<EOF
include /etc/nginx/modules/10_otel.conf;

worker_processes  auto;

error_log  /var/log/nginx/error.log notice;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    otel_exporter { endpoint jaeger:4317; }
    otel_trace on;
    otel_service_name nginx-test;
    server {
        listen 8080;
        location / { return 200 'OpenTelemetry enabled nginx response'; }
        location /health { return 200 'OK'; }
    }
}

EOF

Run nginx-otel-fips with the test configuration:

docker run -p 8080:8080 \
  --link jaeger \
  -v $(pwd)/nginx-conf/nginx.conf:/etc/nginx/nginx.conf \
  cgr.dev/ORGANIZATION/nginx-otel-fips:latest

Generate some traffic:

curl -sf localhost:8080

OpenTelemetry enabled nginx response

Check that your nginx-test service has been registered with Jaeger at http://localhost:16686/api/services

View traces at http://localhost:16686/api/traces/service=nginx-test

Run in a read-only File System

Like the standard nginx container, you can run nginx-otel-fips with a read-only filesystem:

docker run \
 --read-only \
 --tmpfs /var/lib/nginx/tmp/ --tmpfs /var/run/ \
 --cap-drop=ALL \
 -p 8080:8080 \
 cgr.dev/ORGANIZATION/nginx-otel-fips:latest

Documentation and Resources

• Official nginx Documentation
• nginx OpenTelemetry Module
• OpenTelemetry Documentation
• Jaeger Documentation

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.