NGINX Ingress Controller

NGINX Ingress Controller is a specialized load balancer for Kubernetes environments. An Ingress Controller is a daemon that runs alongside the NGINX community or plus version. The daemon monitors the NGINX Ingress resources for load-balancing requests across services. The document explains how to configure a Traceable agent for the NGINX Ingress Controller. The following diagram shows a high-level deployment of the Traceable agent for the NGINX Ingress Controller:

Before you begin

Before you begin installing and configuring the Traceable agent, make sure:

• NGINX Ingress Controller is installed. For example, you can install the latest version of NGINX Ingress Controller by entering the following command:

  ActionScript

  kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.1/deploy/static/provider/cloud/deploy.yaml

  For more information on installing the NGINX Ingress Controller, see NGINX Ingress Controller Installation Guide.

• Ensure you have installed Traceable platform agent 1.15.0 or later in the Kubernetes environment. For more information, see Helm installation.

• You should have a basic understanding of and knowledge of the NGINX Ingress Controller.

Traceable Module Extension (tme)

The deployment uses a Traceable Module extension. Traceable module extension (TME) is a type of sidecar container that a Traceable Platform agent can inject into the application pod. It can be considered a miniature Traceable Platform agent. 

TME has ext_cap as a component. This synchronously receives requests from applications, such as a gateway. The traceable module extension also houses libtraceable, which has the request-blocking logic. TME is used when native instrumentation or a native plugin is unavailable. In such cases, TME captures data inline and sends it to the Traceable Platform agent asynchronously. TME also blocks the requests inline.

Traceable configuration

Add the traceableai-inject-tme label to the namespace to configure Traceable for the NGINX Ingress Controller. The deployment diagram above shows that the injected Traceable module extension (TME) creates SPANS and sends it to the Traceable Platform agent.

Add label

To add the namespace label for Traceable Module Extension (TME) injection, enter the following command:

kubectl label namespace ingress-nginx traceableai-inject-tme=enabled

TME automatically sets up the NGINX Ingress Lua plugin in the Ingress controller container. TME checks the pod labels to identify the NGINX Ingress Controller. In particular, the labels are:

app.kubernetes.io/component=controller
app.kubernetes.io/instance=ingress-nginx
app.kubernetes.io/name=ingress-nginx

You can additionally force the TME to set up the NGINX Ingress Controller Lua plugin using a pod annotation. This should be set on the controller pod.

nginx.traceable.ai/inject: true 

(Optional) ConfigMap name customization

The default ConfigMap name for the Nginx Ingress Controller is ingress-nginx-controller. If the namespace is different from ingress-nginx, the default ConfigMap name is <namespace>-ingress-nginx-controller. You can customize this ConfigMap name and must inform the Traceable Helm values configuration of the new name.

Find the ConfigMap

Enter the following commands to find and inspect the ConfigMap:

1. Enter the following command to list ConfigMaps in the namespace:

   kubectl get cm -n <namespace>

2. Enter the following command to inspect a ConfigMap:

   kubectl describe cm ingress-nginx-controller -n ingress-nginx

Example Helm Values Configuration

If you have a customized ConfigMap name and container name, your Helm values configuration will look like this:

injector: 
  nginx:
    configMapName: "custom-nginx-controller"  # Replace with your custom ConfigMap name
    containerName: "custom-controller"        # Replace with your custom container name, if different

Default ConfigMap Structure

Here's an example of how the default ingress-nginx-controller ConfigMap looks:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
  labels:
    app.kubernetes.io/component: controller
    app.kubernetes.io/instance: ingress-nginx
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: ingress-nginx
    app.kubernetes.io/part-of: ingress-nginx
    app.kubernetes.io/version: 1.11.0
    helm.sh/chart: ingress-nginx-4.11.0
  annotations:
    meta.helm.sh/release-name: ingress-nginx
    meta.helm.sh/release-namespace: ingress-nginx
data:
  allow-snippet-annotations: "false"

Restart the deployment

Enter the following command to restart the deployment:

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

Verification

Enter the following command and verify that the ingress controller has two containers:

❯ kubectl get pod -n ingress-nginx

NAME                                       READY   STATUS      RESTARTS   AGE
ingress-nginx-admission-create-n88nn       0/1     Completed   0          26h
ingress-nginx-admission-patch-jrznd        0/1     Completed   0          26h
ingress-nginx-controller-5fb9c6b96-bs2v6   2/2     Running     0          25h

Upgrade

To upgrade the Traceable agent, make a note of the points mentioned in the Traceable agent installation, that is:

• NGINX Lua plugin is set up as part of the setup of the Traceable agent.

• Make sure that the Traceable agent version is 1.15.0 or later.

Enter the following command to upgrade the Traceable agent using the Helm chart:

cd ./deployments/traceable-agent/helm
helm upgrade traceable-agent ./ -n traceableai --values ./values.yaml

Restart the deployment

Enter the following command to restart the deployment:

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

To verify a successful upgrade, repeat the steps mentioned in the Verification section. 

Uninstall

Uninstalling the Traceable agent involves removing the namespace label for TME and restarting the deployment. Complete the following steps:

1. Remove the namespace label for Traceable Module Extension (TME) injection. Enter the following command:

   ActionScript

   kubectl label namespace ingress-nginx traceableai-inject-tme-

2. Restart the deployment:

   ActionScript

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

3. Verify that ingress-controller has one container:

   ActionScript

   ❯ kubectl get pod -n ingress-nginx
   NAME                                       READY   STATUS      RESTARTS   AGE
   ingress-nginx-admission-create-n88nn       0/1     Completed   0          26h
   ingress-nginx-admission-patch-jrznd        0/1     Completed   0          26h
   ingress-nginx-controller-5fb9c6b96-bs2v6   1/1     Running     0          25h