Chainguard Container for nginx-prometheus-exporter

The nginx-prometheus-exporter image is designed to scrape metrics from an NGINX instance and expose them to Prometheus in a secure and minimal environment. Below are detailed instructions for using the image in both Docker and Kubernetes environments.

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-prometheus-exporter:latest

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

Usage of the nginx-prometheus-exporter Image

The nginx-prometheus-exporter image is designed to scrape metrics from an NGINX instance and expose them to Prometheus in a secure and minimal environment. Below are detailed instructions for using the image in both Docker and Kubernetes environments.

Running with Docker:

To run nginx-prometheus-exporter with a local NGINX instance, use the following commands:

Run NGINX: Start an NGINX instance that has the required /status page enabled.

docker run -d --name nginx -p 8080:80 nginx:stable-alpine

You will need to ensure the /status page is enabled in your NGINX configuration. A simple nginx.conf could look like this:

server {
    listen 80;
    location /status {
        stub_status on;
        allow all;
    }
}

Run the Prometheus Exporter: Start the nginx-prometheus-exporter to scrape metrics from the NGINX instance.

docker run -d --name nginx-prometheus-exporter -p 9113:9113 --link nginx \
  cgr.dev/chainguard/nginx-prometheus-exporter:latest \
  -nginx.scrape-uri="http://nginx/status"

Verify Metrics: You can check if the exporter is running and exposing metrics by visiting the following URL:

http://localhost:9113/metrics

You should see metrics related to your NGINX instance, such as:

nginx_connections_active 1
nginx_connections_reading 0
nginx_connections_writing 1
nginx_connections_waiting 0

Using in Kubernetes

If you're running NGINX in a Kubernetes environment, you can use the following Kubernetes manifest to deploy NGINX and the Prometheus exporter.

Deploy NGINX and Exporter

apiVersion: v1
kind: Namespace
metadata:
  name: nginx-exporter-test
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: nginx-exporter-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:stable-alpine
        ports:
        - containerPort: 80
        volumeMounts:
        - name: nginx-config
          mountPath: /etc/nginx/conf.d
      volumes:
      - name: nginx-config
        configMap:
          name: nginx-config
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
  namespace: nginx-exporter-test
data:
  default.conf: |
    server {
        listen 80;
        location /status {
            stub_status on;
            allow all;
        }
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-prometheus-exporter
  namespace: nginx-exporter-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-prometheus-exporter
  template:
    metadata:
      labels:
        app: nginx-prometheus-exporter
    spec:
      containers:
      - name: nginx-prometheus-exporter
        image: cgr.dev/chainguard/nginx-prometheus-exporter:latest
        args:
        - '-nginx.scrape-uri=http://nginx/status'
        ports:
        - containerPort: 9113
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-prometheus-exporter
  namespace: nginx-exporter-test
spec:
  ports:
  - port: 9113
    targetPort: 9113
  selector:
    app: nginx-prometheus-exporter

Access Metrics in Kubernetes:

You can use kubectl port-forward to forward the exporter service to your local machine for verification:

kubectl port-forward svc/nginx-prometheus-exporter 9113:9113 -n nginx-exporter-test

Access the metrics at:

http://localhost:9113/metrics

Prometheus Configuration: If you’re using Prometheus to scrape the metrics, add the following configuration to your Prometheus configuration file:

scrape_configs:
  - job_name: 'nginx-prometheus-exporter'
    static_configs:
      - targets: ['nginx-prometheus-exporter.nginx-exporter-test.svc.cluster.local:9113']

Environment Variables and Customization

The nginx-prometheus-exporter allows some additional customization through the following options:

-nginx.scrape-uri: Set the URI where the exporter should scrape NGINX metrics. Defaults to http://localhost/status. -telemetry.address: Set the address where the Prometheus exporter exposes metrics. Defaults to :9113.

You can pass these as arguments in the Docker run command or in your Kubernetes manifest.

What are Chainguard Containers?

Chainguard Containers are minimal container images that are secure by default.

In many cases, the Chainguard Containers tagged as :latest contain only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager. Chainguard Containers are built with Wolfi, our Linux undistro 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 -dev variant.

Although the -dev container image variants have similar security features as their more minimal versions, they feature additional software that is typically not necessary in production environments. We recommend using multi-stage builds to leverage the -dev variants, copying application artifacts into a final minimal container that offers a reduced attack surface that won’t allow package installations or logins.

Learn More

To better understand how to work with Chainguard Containers, please visit Chainguard Academy and Chainguard Courses.

In addition to Containers, Chainguard offers VMs and Libraries. Contact Chainguard to access additional products.

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.