Configuring AutoTrace webhook

You can disable the following tracers:

• .NET Core (netcore)
• Python (python)
• Node.js (nodejs)
• Ruby (ruby)

If .NET Core tracing is enabled, do not disable the other tracers (Python, Node.js, and Ruby). Disabling these tracers might affect the .NET Core tracing functionality.

To disable the tracing of technologies individually, add the line --set autotrace.<technology>.enabled=false to the AutoTrace webhook installation command as shown in the following example. Replace <technology> with the technology for which that you want to disable tracing.

helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
  --repo https://agents.instana.io/helm instana-autotrace-webhook \
  --set webhook.imagePullCredentials.password=<download_key> \
  --set autotrace.ruby.enabled=false \
 

To deploy the AutoTrace webhook into a ServiceAccount that is guarded by a ClusterRole and matching ClusterRoleBinding, set the rbac.enabled=true flag when you deploy the Helm chart.

In addition to the role-based access control, if you use pod security policies, add rbac.psp.enabled=true to the Helm arguments.

You can also enforce Pod Security Standards through the built-in Pod Security Admission controller. For more information about the Pod Security Admission, see Kubernetes documentation.

If you set the flags rbac.enabled=false and webhook.pod.hostNetwork=false in the Helm installation, you can run the AutoTrace webhook with the restrictive Pod Security Standard by running the following command:

kubectl label --overwrite ns instana-autotrace-webhook pod-security.kubernetes.io/enforce=restricted
 

You must host the AutoTrace webhook pod on the host network and configure it properly to make sure that it is reachable from the Kubernetes API server (apiserver).

By default, the container is bound to port 42650.

If port 42650 is already in use, the AutoTrace webhook crashes. To avoid this issue, you can change the port by using the webhook.pod.port property.

The AutoTrace webhook instruments all containers in all pods.

However, you can have more control over which resources are instrumented. To specify that only selected resources are instrumented, first add the autotrace.opt_in=true argument during the Helm deployment.

Then, specify which resources must be instrumented by adding the instana-autotrace: "true" label to the required pods, replica sets, stateful sets, daemon sets, and deployments. AutoTrace webhook uses this label to identify the required resources and mutates them. Additionally, you can set the label on a namespace level, where all resources within that namespace are instrumented.

The instana-autotrace: "false" label is respected in the metadata of DaemonSets, Deployments, DeploymentConfigs, ReplicaSets, StatefulSets, and namespaces, as in nested pod templates and in stand-alone pods.

You can exclude entire namespaces from being auto-instrumented by using the autotrace.exclude.namespaces configuration.

The instana-autotrace label is respected in the metadata of DaemonSets, Deployments, DeploymentConfigs, ReplicaSets, and StatefulSets, as in nested pod templates and in stand-alone pods.

You can exclude individual resources from auto-instrumentation by adding the instana-autotrace: "false" label. AutoTrace webhook ignores the resources with this label regardless of other settings.

The instana-autotrace label is respected in the metadata of DaemonSets, Deployments, DeploymentConfigs, ReplicaSets, and StatefulSets, as in nested pod templates and in stand-alone pods.

Starting with 1.304.6, the Instana AutoTrace webhook only mutates pods and ConfigMaps by default. This makes updates and uninstallation easier. When a new webhook pod runs, higher-level resources can be restarted, which would invoke new pods that would be mutated with the new instrumentation image.

If you need the previous behavior of mutating higher-level resources directly (deployments, daemonsets, replicasets, statefulsets, and deploymentconfigs), you can enable it by using the autotrace.enableHigherLevelResourceMutation=true flag:

helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
  --repo https://agents.instana.io/helm instana-autotrace-webhook \
  --set webhook.imagePullCredentials.password=<download_key> \
  --set autotrace.enableHigherLevelResourceMutation=true
 

To activate the NGINX and ingress-nginx auto-instrumentation, you must opt in by setting the label autotrace.ingress_nginx.enabled=true.

Before your proceed, see Troubleshooting AutoTrace webhook, and make sure that the relevant objects are updated or re-created.

The AutoTrace webhook supports the ingress-nginx Kubernetes ingress controller 0.34.1 or later with a support policy of 45 days, and is compatible with Helm chart 2.11.2 or later.

To set up Instana AutoTrace webhook with the NGINX, run the following command:

helm install --create-namespace --namespace instana-autotrace-webhook \
  --repo https://agents.instana.io/helm instana-autotrace-webhook instana-autotrace-webhook \
  --set webhook.imagePullCredentials.password=<download-key> \
  --set autotrace.ingress_nginx.enabled=true

You need to manually add the nginx_status location for regular or standalone NGINX. However, for ingress-nginx, the nginx_status location is automatically added by the AutoTrace webhook.

Deployment and ConfigMap mutations are required for instrumenting Ingress NGINX. Therefore, install the Instana AutoTrace webhook before installing the Ingress NGINX. If the Ingress NGINX is already installed, then complete the following steps:

1. To delete the existing deployment and create a new one without affecting the service, run the following commands:

   kubectl get deploy ingress-nginx-deployment -o yaml > your_deployment_backup.yaml # Back up your deployment config

   kubectl delete deploy your_deployment_name --cascade=orphan # Delete the existing deployment, cascade option ensures that pods are not deleted.

   kubectl apply -f your_deployment_backup.yaml # Re-apply the deployment config

2. To replace the ConfigMap, run the following command:

   kubectl get cm ingress-nginx-configmap -o yaml > your_configmap_backup.yaml # Back-up your configmap

   kubectl replace --force -f your_configmap_backup.yaml # replace the configmap to trigger mutation webhook API

To activate the IBM MQ and ACE auto-instrumentation, you must opt in by setting the labels autotrace.ibmmq.enable=true and autotrace.ace.enable=true. The AutoTrace webhook supports only IBM MQ and ACE that are running in IBM Cloud Pak for Integration.

Because IBM Cloud Pak for Integration runs on the Red Hat OpenShift cluster, you must also set openshift.enabled=true during the Helm deployment.

To set up Instana AutoTrace webhook with the IBM MQ and ACE auto-instrumentation that are enabled, enter the following command:

helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
  --repo https://agents.instana.io/helm instana-autotrace-webhook \
  --set webhook.imagePullCredentials.password=<download_key> \
  --set openshift.enabled=true \
  --set autotrace.ibmmq.enabled=true \
  --set autotrace.ace.enabled=true
 

If your application is using ECMAScript modules, use the autotrace.nodejs.application_type setting. To make sure that you are using the latest version of the AutoTrace webhook, see Updating AutoTrace webhook .

• Set autotrace.nodejs.application_type to module_v2 (Node.js version 18.19 and later):

    helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
      --repo https://agents.instana.io/helm instana-autotrace-webhook \
      --set webhook.imagePullCredentials.password=<download_key> \
      --set autotrace.nodejs.application_type=module_v2

  Note:

  • The module_v1 option is deprecated.
  • Set autotrace.nodejs.application_type to module_v1 only when the following conditions are met:
    • Your application runs on a Node.js version earlier than 18.19.0.
    • You use AutoTrace webhook or earlier.
  • The module_v1 option is no longer supported in current versions and will be removed during the next upgrade. For more details, refer to the Breaking changes section.

• To revert to the default behavior or remove the configuration option entirely, set autotrace.nodejs.application_type to commonjs:

  helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
    --repo https://agents.instana.io/helm instana-autotrace-webhook \
    --set webhook.imagePullCredentials.password=<download_key> \
     --set autotrace.nodejs.application_type=commonjs

The webhook mutates the deployment and adds the initContainer. The initContainer pulls the image that has instrumentation files for all supported technologies (Node.js, .NET Core, Ruby, Python, and NGINX) and copies the files to the volume. The files are stored in the emptyDir volume instana-instrumentation-volume under volume mount path /opt/instana/instrumentation/. The emptyDir volumes are stored on the local file system of the node and therefore the instrumentation files increase the pod's ephemeral storage usage. The total size of the instrumentation files is around 300 MB. See the following table for the storage requirements of each technology:

In some cases, your cluster might use only certain technologies. To optimize, you can limit the files that are copied during the installation, which reduces the ephemeral storage and improving the initContainer running time. Complete the following steps to limit the files to only the technologies you require:

1. Determine the technologies used in your cluster. In this example, Node.js and .NET Core are selected.

2. Configure the webhook installation by explicitly enabling the required technologies that use Helm chart flags. The syntax is as follows:

   --set autotrace.instrumentation.manual.<technology>=true
    

   Replace <techonology> with one of the following:

   • nodejs
   • netcore
   • python
   • ruby
   • nginx

   For example, to enable both Node.js and .NET Core, use flags:

   --set autotrace.instrumentation.manual.nodejs=true --set autotrace.instrumentation.manual.netcore=true
    

3. After the helm chart installation is successful, make sure to re-create your deployment so the new configuration takes effect on the cluster workloads.

For more information on the environment variables or Helm chart flags, see Helm values.