Instana AutoTrace webhook

Configuring in an air-gapped environment

For air-gapped environments, you need to provide the instana-autotrace-webhook Helm chart, the instana-autotrace-webhook container image, and the instrumentation container image in your environment.

To download the latest release of the Helm chart to your current working directory, run the following command:

helm pull instana-autotrace-webhook --repo https://agents.instana.io/helm instana-autotrace-webhook

To change the destination directory of this command, you can use the option -d <DESTINATION_PATH> to specify another destination directory.

To download the latest instana-autotrace-webhook image, run the following command:

docker pull containers.instana.io/instana/release/agent/instana-autotrace-webhook:latest

To download the latest instrumentation image, run the following command:

docker pull icr.io/instana/instrumentation:latest

The two container images need to be available in your container registry. The previously downloaded Helm chart archive must be available on the system that runs the helm install command.

To install the Instana AutoTrace webhook, run the following command:

helm upgrade --install --create-namespace \
  --namespace instana-autotrace-webhook \
  --set webhook.image=<INSTANA_AUTOTRACE_WEBHOOK_IMAGE_PATH> \
  --set autotrace.instrumentation.image=<INSTRUMENTATION_IMAGE_PATH> \
  instana-autotrace-webhook <PATH_TO_HELM_CHART_ARCHIVE>

Role-based access control

To deploy the AutoTrace webhook into a ServiceAccount guarded by a ClusterRole and matching ClusterRoleBinding, set the rbac.enabled=true flag when you are deploying 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.

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

If the flags rbac.enabled=false and webhook.pod.hostNetwork=false are set 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

Container port

To be reachable from Kubernetes' apiserver, the AutoTrace webhook pod must be hosted on the host network, and the deployment must be configured to achieve that transparently. By default, the container is bound to port 42650.

If port 42650 is in use, the AutoTrace webhook crashes because its port is already bound. You can change the port by using the webhook.pod.port property.

Opt-in or opt-out

The AutoTrace webhook instruments all containers in all pods. However, you can have more control over which features are instrumented and which are not. By setting the autotrace.opt_in=true value when you are deploying the Helm chart, the AutoTrace webhook modifies pods, replica sets, stateful sets, daemon sets, and deployments that carry the instana-autotrace: "true" label.

Irrespective of the value of the autotrace.opt_in, the AutoTrace webhook does not touch pods that carry the instana-autotrace: "false" label.

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

Ignoring namespaces

By using the autotrace.exclude.namespaces configuration, you can exclude entire namespaces from being auto-instrumented.

Resources that have the instana-autotrace: "true" label are instrumented regardless of namespace exclusion.

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.

Ignoring resources

Resources that have the instana-autotrace: "false" label are ignored 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.

NGINX and ingress-nginx

To activate the NGINX and ingress-nginx auto-instrumentation, you must opt-in by setting autotrace.ingress_nginx.enabled=true. Make sure to read the troubleshooting section afterward, 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, and it is compatible with Helm chart 2.11.2 or later.

IBM MQ and ACE

To activate the IBM MQ and ACE auto-instrumentation, you must opt-in by setting autotrace.ibmmq.enable=true and autotrace.ace.enable=true. The AutoTrace webhook supports only IBM MQ and ACE running in IBM Cloud Pak for Integration. IBM Cloud Pak for Integration runs on the Red Hat OpenShift cluster, and thus you must also set openshift.enabled=true. 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

Node.js ECMAScript modules

ECMAScript modules are unavailable in Node.js 18.19.0 and later. For more information on the breaking changes in Node.js 18.19.0, see official release notes. The ECMAScript modules are in the experimental phase.

When your Node.js application is using ECMAScript modules (ES modules), set autotrace.nodejs.esm=true. Before the application code is loaded, the AutoTrace webhook loads and initialize the Node.js collector by using the --experimental-loaders argument instead of the --require argument. Follow the updates guide to make sure that you are on the latest version of the AutoTrace webhook.

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.esm=true

Verifying that the Instana AutoTrace webhook is receiving requests

To verify that the Instana AutoTrace webhook is receiving requests, check the logs of the instana-autotrace-webhook pod by running the following command:

kubectl logs -l app.kubernetes.io/name=instana-autotrace-webhook -n instana-autotrace-webhook

In a functioning installation, you can see the following logs:

14:41:37.590 INFO  |- [AdmissionReview 48556a1a-7d55-497b-aa9c-23634b089cd1] Applied transformation DefaultDeploymentTransformation to the Deployment 'test-netcore-glibc/test-apps'
14:41:37.588 INFO  |- [AdmissionReview 1d5877cf-7153-4a95-9bfb-de0af8351195] Applied transformation DefaultDeploymentTransformation to the Deployment 'test-nodejs-12/test-apps'

If you do not see such logs, a problem with Kubernetes setup might exist. Continue troubleshooting by checking the following section.

Checking the kube-apiserver logs

Check the logs of your kube-apiserver. These logs report on whether the Instana AutoTrace webhook is being started and provide information about the outcome of the execution.

Common issues