---
title: Enable custom Nginx settings on my scope
sidebar_label: Enable custom Nginx settings
toc_max_heading_level: 2
doc_id: 7f3c1d9a-5e6b-4b2a-9f2e-8b6c4a1d0e93
description: "🎯 Enable custom Nginx behavior in a Kubernetes scope for WebSockets, gRPC, or headers."
tutorial_type: tutorial
tutorial_category: deploy-scopes
tutorial_time: 15 min
tutorial_featured: false
tutorial_cover: /img/tutorials/covers/custom-nginx-traffic-config.svg
keywords:
  - scopes
  - overrides
  - nginx
  - websocket
  - grpc
  - configmap
  - kubernetes
  - traffic
tags:
  - scope
  - kubernetes
  - networking
---

# 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.

:::warning 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](https://helm.sh/docs/intro/install/) installed
- A running [nullplatform agent](/docs/agent/overview)
- 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`

```yaml
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:

```bash
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:

```nginx
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:

```bash
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:

```text
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:

```text
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.

## What's next

- [Populate form fields with live infrastructure data](/docs/tutorials/external-context-dynamic-values): another advanced agent pattern, pulling real-time values into specifications
- [Notify when a deployment fully shifts traffic](/docs/tutorials/notify-on-deployment-traffic-shift): react to deployments the moment they reach 100% traffic

---

## Related docs

- [Agent-backed scopes](/docs/agent-backed-scopes/)
- [Kubernetes scope setup](/docs/tutorials/kubernetes-prod-ready)