NGINX Ingress Controller using C++ module

Starting with version 1.12.0, the Ingress-NGINX controller removed support for custom Lua plugins, which were previously used for instrumentation. Traceable now supports injecting a C++ module into the Ingress-NGINX controller to continue supporting Ingress traffic monitoring and protection. This approach ensures compatibility with the latest controller versions and offers a reliable alternative to Lua-based instrumentation.

This document guides you through enabling Traceable’s C++ module injection for Ingress-NGINX using namespace labels or custom match selectors.

What Is This About?

This topic explains how to instrument the Ingress-NGINX controller using Traceable’s native C++ module. The module enables API observability and protection by injecting the required C++ module into the Ingress-NGINX controller pods. This solution is designed for environments where Lua-based plugins are no longer supported.

What Problem Does This Solve?

The deprecation of Lua plugin support in recent Ingress-NGINX versions (≥ 1.12.0) breaks compatibility with older Traceable instrumentation methods. This module-based injection approach resolves that by:

• Ensuring instrumentation continues to work with updated NGINX versions.

• Supporting fine-grained resource and behavior control through Helm or Terraform values.

• Providing full observability via the Traceable Platform.

Before You Begin

Ensure the following prerequisites are met before proceeding:

Important: The configuration options listed in this topic are part of the Traceable Platform Agent (TPA) Helm chart and Terraform module.

You must ensure that TPA is installed using one of the following methods:

• Install via Helm

• Install via Terraform

For more information on different Helm and Terraform values, see Helm and Terraform values topic.

• Ingress-NGINX version ≥ 1.12.0.

• You have kubectl access with permissions to:

  • Label namespaces.

  • Patch deployments.

  • Restart deployments.

• Your deployment environment supports init containers and ConfigMap-based configuration.

• You have either:

  • Helm access to modify values.yaml, or

  • Terraform configuration control for deployment.

Configuration Steps

Step 1: Label the Namespace (Optional but Recommended)

Apply a label to the namespace where Ingress-NGINX is deployed. This label signals Traceable’s injection mechanism to automatically inject the C++ module into any matching pods within this namespace.

kubectl label ns ingress-nginx traceableai-inject-nginx-cpp=enabled

What this does:
This command adds a label named traceableai-inject-nginx-cpp=enabled to the ingress-nginx namespace. When this label is present, Traceable’s injection logic knows to target this namespace for instrumentation.

Note

If you prefer to control injection based on pod annotations or labels instead of namespace-wide injection, you can skip this step and configure the matchSelectors parameter (see config table).

Step 2: Patch the Ingress Controller Deployment

Add a pod-level annotation to the Ingress-NGINX controller deployment to explicitly request injection of the Traceable C++ module.

Before proceeding to the next step: Ensure that the Traceable Platform Agent (TPA) has been installed using one of the supported methods:

• Install via Helm

• Install via Terraform

kubectl patch deployment.apps/ingress-nginx-controller \
  -p '{"spec": {"template": {"metadata": {"annotations": {"nginx.cpp.traceable.ai/inject": "true"}}}}}' \
  -n ingress-nginx

What this does:
This command adds an annotation to the pod template within the ingress-nginx-controller deployment. The annotation is:

nginx.cpp.traceable.ai/inject: "true"

This instructs the Traceable agent injector to inject the C++ module into the pod during its next restart.

Why patch instead of editing directly?
Patching is a safer and quicker way to update specific parts of a Kubernetes object, especially in automated environments or CI/CD pipelines.

Step 3: Restart the Ingress Controller

Restart the Ingress-NGINX deployment to apply the annotation changes and trigger injection of the Traceable module.

kubectl rollout restart deployment ingress-nginx -n ingress-nginx

What this does:
This command safely restarts all pods in the ingress-nginx deployment by triggering a rolling restart. Kubernetes will recreate the pods using the updated configuration (which now includes the annotation and injection logic).

Note

A restart is required because changes to pod templates (like annotations) only apply to new pods. Existing pods must be restarted for changes to take effect.

Helm and Terraform Configuration Options

The following table lists configuration parameters for Helm (values.yaml) and Terraform (snake_case) to customize C++ module behavior:

Upgrade

To upgrade the Traceable instrumentation:

Step 1: Upgrade the Traceable Platform Agent (TPA)

Update your TPA installation with the required configuration changes using your preferred method (Helm or Terraform).

Step 2: Clean up Traceable-specific directives

Manually remove the following directives from the Ingress-NGINX ConfigMap:

• traceableai

• opentracing

• opentracing_trace_locations

• opentracing_propagate_context

Step 3: Restart the Ingress-NGINX Deployment

kubectl rollout restart deployment ingress-nginx -n ingress-nginx

This command triggers a rolling restart of all pods in the ingress-nginx deployment. It ensures any changes to the ConfigMap or injected configuration take effect. triggers a rolling restart of all pods in the ingress-nginx deployment. It ensures any changes to the ConfigMap or injected configuration take effect.

Uninstall

To completely remove the Traceable instrumentation from your Ingress-NGINX setup:

Step 1: Remove the namespace label (if configured)

kubectl label ns ingress-nginx traceableai-inject-nginx-cpp-

Step 2: Remove the deployment annotation (if configured)

kubectl patch deployment.apps/ingress-nginx-controller \
  -p '{"spec": {"template": {"metadata": {"annotations": {"nginx.cpp.traceable.ai/inject": null}}}}}' \
  -n ingress-nginx

Step 3: Remove Traceable directives from the Ingress-NGINX ConfigMap

Manually delete the following directives:

• traceableai

• opentracing

• opentracing_trace_locations

• opentracing_propagate_context

Step 4: Uninstall the Traceable Platform Agent (TPA)

Uninstall the TPA from your cluster using the same method you used for installation (Helm or Terraform).