Skip to main content

Enable custom Nginx settings on my scope

🎯 Goal: Enable custom Nginx behavior (WebSockets, gRPC, headers) for my Kubernetes scope while preserving nullplatform metrics compatibility.

Introduction​

By default, the Kubernetes scope provided by nullplatform ships with a preconfigured Nginx setup inside the Traffic container. The Traffic container is the Nginx sidecar that handles incoming HTTP traffic, logs requests for platform metrics, and forwards requests to your app. In some advanced scenarios, you may need to override this configuration, for example:

  • Enabling WebSocket support
  • Enabling gRPC
  • Adding custom headers
  • Tuning Nginx behavior for specific workloads (buffers, timeouts, etc.)

This tutorial walks you through providing a ConfigMap with your Nginx configuration and telling the agent to mount it into the Traffic container in a safe, supported way.

Important

Metrics shown in nullplatform are derived from the Traffic container logs. Do not modify the logging block in the Nginx configuration, or metrics may break.

What you’ll set up​

By the end of this guide, you’ll have:

  • A custom Nginx configuration stored in a ConfigMap
  • The Traffic container mounting that configuration
  • An agent-backed scope using your customized Traffic container

Prerequisites​

  • Helm installed
  • A running nullplatform agent
  • Permissions to create a ConfigMap in the target namespace
  • Access to the Kubernetes namespace where your app is deployed

1. Create a ConfigMap with the Nginx configuration​

Create a ConfigMap in the same namespace where your application is deployed. The ConfigMap must contain two keys with these exact names (case-sensitive):

  • nginx.conf
  • default.conf
apiVersion: v1
kind: ConfigMap
metadata:
  name: traffic-container-configuration
data:
  nginx.conf: |
    # Your full nginx.conf
  default.conf: |
    # Your server/default configuration

Apply it to your application namespace:

kubectl apply -f traffic-container-configuration.yaml -n <namespace>

Preserve the logging configuration​

Make sure your nginx.conf keeps the original logging block, as shown below:

log_format  main  '$remote_addr [$time_local] "$request" '
                  '$status $request_time $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for" "$quality"';
map $status $quality {
  ~^[23]   "OK (2XX, 3XX)";
  ~^4      "DENIED (4XXs)";
  default  "ERROR (5XXs)";
}

You can extend the configuration with WebSocket support, gRPC, or custom headers, as long as this block remains unchanged.

2. Tell the agent which ConfigMap to use​

Set the TRAFFIC_MANAGER_CONFIG_MAP environment variable in the agent configuration to the name of the ConfigMap you created:

helm upgrade nullplatform-agent nullplatform/nullplatform-agent \
  --namespace nullplatform-tools \
  --set configuration.values.TRAFFIC_MANAGER_CONFIG_MAP="traffic-container-configuration" \
  --reuse-values
note

The ConfigMap must exist in the application namespace (the namespace where the scope is deployed).

The value must match a ConfigMap that already exists in the application namespace. If the variable is not set, the Traffic container uses the default Nginx configuration.

3. Deploy and verify the change​

Deploy the scope as usual. If the environment variable (TRAFFIC_MANAGER_CONFIG_MAP) is present and the ConfigMap is valid, the Traffic container will mount the files and use them (/nginx.conf and /default.conf).

🔍 Validating ConfigMap 'traffic-container-configuration' in namespace 'nullplatform'
✅ ConfigMap '$TRAFFIC_MANAGER_CONFIG_MAP' exists
✅ Found required key 'nginx.conf' in ConfigMap
✅ Found required key 'default.conf' in ConfigMap
🎉 ConfigMap 'traffic-container-configuration' validation successful
info

This configuration is opt-in: if you do not set TRAFFIC_MANAGER_CONFIG_MAP, the Traffic container keeps using the default Nginx configuration shipped with the scope.

What happens if something is wrong​

If the ConfigMap does not exist, deployment will fail during validation:

Validating ConfigMap 'traffic-container-configuration' in namespace 'nullplatform'
ConfigMap 'traffic-container-configuration' does not exist in namespace 'nullplatform'
error: exit status 1

If the ConfigMap exists but is missing required keys, deployment will also fail:

ConfigMap 'traffic-container-configuration' exists
ConfigMap 'traffic-container-configuration' is missing required key 'nginx.conf'
The ConfigMap must contain data entries for: nginx.conf default.conf
error: exit status 1

Wrap-up 🎉​

You’ve successfully:

  • Overridden the default Nginx configuration for the Traffic container
  • Preserved metric compatibility with nullplatform

This pattern can be reused for other advanced scope customizations while keeping full compatibility with the platform.

Related docs​