Configure Deepfactor Mutating Webhook

Deepfactor's Mutating Admission Controller is used to instrument Kubernetes workloads to run with Deepfactor. This document describes the config required for mutation of the qualifying workloads.

This webhook-override.yaml (shown below) can be used during webhook install/upgrade using helm charts. Alternately you can also use the annotations described below for the same.

For details on how to install the webhook using helm charts, please refer to Install Deepfactor Mutating Webhook


Configure Webhook with webhook-override.yaml

Create webhook-override.yamlor specify the config via CLI parameters for helm installation. Following is a sample override file for the webhook

webhookconfig:
httpProxy: ""
httpsProxy: ""
dfRunToken: "ey..."
namespaces:
- name: ""
alertPolicy: "Built-in-Policy Max Alert"
envName: "staging"
stackTraces: true
methodTracing: true
selector:
matchLabels:
app: myapp
matchExpressions:
- {key: environment, operator: notin, values: [prod]}
 

The following table describes the additional configurations that can be set in webhook-override.yaml file:

 

Configuration Description
webhookconfig.dfRunToken This must be set to the run token that is required to register an application with the Deepfactor platform. You can find this token by logging into the Deepfactor Portal and navigating to Run with Deepfactor -> Kubernetes screen. This is set at the global webhook config level and can be overridden using df.k8-app.run.token/runtoken annotation in podspec.

webhookconfig.httpProxy &

webhookconfig.httpsProxy

These optional parameters can be used to set the proxy which must be used for registering the application with the Deepfactor platform. This can be overridden by the annotations df.k8-app.http/proxy and df.k8-app.https/proxy.
webhookconfig.selector This optional parameter further helps in providing fine-grain control over pod inclusion criteria for instrumentation. The format is that of standard Kubernetes label selectors - works with pod labels. 
More information regarding Kubernetes label selectors can be found in the following article https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
webhookconfig.appNameSource
(deprecated)

This option has been deprecated. Please use 'appName' option. Read more here

This config determines how the application name is decided by the webhook while registering apps with the Deepfactor platform.

The following are possible values for this config:

  • podspec The pod name will be used as the application name. This is the default value starting with the 2.3.2 release.

  • namespace This config will make the namespace to be used as the application name and all containers within the namespace will become components within the single application. This used to be the default until the 2.3.1 release

webhookconfig.appName

This optional parameter can be used to determine the name of the application for each of the containers instrumented with Deepfactor. This option can take variables as well. By default, it is set to the name of the pod. Read more about the various possible options here.

webhookconfig.componentName

This optional parameter can be used to set the name of the component for every container that gets instrumented by Deepfactor. This option can take variables as well. By default it is set to the name of the container being instrumented. Read more about the various possible options here.

webhookconfig.componentVersion

This optional parameter, when set, will be used to determine the version number of the container being instrumented. By default, it is set to the container image tag. Read more about the various possible options here.

webhookconfig.excludeJobsPods

This optional parameter can be used to enable the instrumentation of Kubernetes jobs and cronjobs. The default for this config parameter is set to true.

webhookconfig.namespaces[x].appName This optional parameter can be used to determine the name of the application for each of the containers instrumented with Deepfactor. This option can take variables as well. By default, it is set to the name of the pod. Read more about the various possible options here.
webhookconfig.namespaces[x].lsa

You generally do not need to specify this option as Deepfactor automatically detects the programming language per process and injects the appropriate language-specific agent (LSA). There may be special cases where you may want to override this behavior. For example, you want to enable stack traces only for java applications. You can read more about Deepfactor LSA in the following document
Language-Specific Agents

webhookconfig.namespaces[x].envName This optional parameter is used to represent the application's execution environment created on the Deepfactor platform. This is an optional parameter and can be overridden using annotation df.k8-app.env/name in the pod spec.
webhookconfig.namespaces[x].stackTraces Deepfactor's language specific agents (LSA) collect language specific stack traces. The agents to collect stack traces are supported for Java and Python applications. For other languages, this option is ignored and will not have any impact on the application. This option is enabled by default and can be disabled by setting this option to false.
You can also disable this capability for a particular pod by setting the following annotation in the podspec:
df.k8-app.stack-traces: false 
Note: Stack traces for C runtime is always enabled and is not dependent on this configuration.
webhookconfig.namespaces[x].methodTracing When set to true, agents to collect usage telemetry (methods, etc) will be injected for each process in the application instances monitored by Deepfactor runtime. The agent to collect method usage information is only supported for Java applications. For other languages, this option is ignored and will not have any impact on the application. This config can be overridden using annotation df.k8-app.method-tracing in the pod spec.
webhookconfig.namespaces[x].componentNameSource
(deprecated)

This option has been deprecated. Please use 'componentName' option. Read more here

This optional parameter determines how the component name is extracted from the image tag. The following are possible values for this config:

  • PodContainer
  • PodRepository
  • Image
  • ImageAndTag
webhookconfig.namespaces[x].componentVersionSource

This option has been deprecated. Please use 'componentVersion' option. Read more here

This optional parameter determines how the component version info is extracted from the image tag. The following are possible values for this config:

  • Tag
  • ImageID
webhookconfig.namespaces[x].excludePodNamePrefixes List of pod name prefixes that will be excluded from mutation by webhook. Pods that match these criteria will be excluded from Deepfactor instrumentation.
webhookconfig.namespaces[x].excludeImageNamePrefixes List of image name prefixes that will be excluded from mutation by webhook. Pods that match these criteria will not be instrumented by Deepfactor.
webhookconfig.namespaces[x].excludePodNameRegularExpressions List of pod name regexes that will be used to determine pod names to be excluded from mutation by webhook. Pods that match these criteria will not be instrumented by Deepfactor.
webhookconfig.namespaces[x].excludeImageNameRegularExpressions List of image name prefixes that will be excluded from mutation by webhook. Pods that match these criteria will not be instrumented by Deepfactor.
webhookconfig.namespaces[x].selector

This optional parameter further helps in providing fine-grain control over pod inclusion criteria for instrumentation. The format is that of standard Kubernetes label selectors - works with pod labels. 
More information regarding Kubernetes label selectors can be found in the following article: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements

webhookconfig.namespaces[x].selector.matchLabels


Map of key value pairs that are matched against pod labels.

More information regarding selecting the pods can be found in the following article:

Selecting the pods you want to run with Deepfactor

webhookconfig.namespaces[x].selector.matchExpressions


List of pod selector requirements.

More information regarding selecting the pods can be found in the following article:

Selecting the pods you want to run with Deepfactor

webhookconfig.namespaces[x].componentName

This optional parameter can be used to set the name of the component for every container that gets instrumented by Deepfactor. This option can take variables as well. By default, it is set to the name of the container being instrumented. Read more about the various possible options here.

webhookconfig.namespaces[x].componentVersion

This optional parameter, when set, will be used to determine the version number of the container being instrumented. By default, it is set to the container image tag. Read more about the various possible options here.

webhookconfig.namespaces[x].packageInfoEvents

This optional parameter, when set to false, will be used to skip reporting OS package information for the container. The default for this config parameter is set to true.

webhookconfig.namespaces[x].dependencyCheckInfoEvents

This optional parameter, when set to false, will be used to skip reporting application dependency information. The default for this config parameter is set to true.

webhookconfig.namespaces[x].packageQueryDelayMS

This optional parameter will be used to configure a throttle time in milliseconds in between queries to get OS package information. The default for this config parameter is 250 milliseconds.

webhookconfig.namespaces[x].excludeJobsPods

This optional parameter can be used to enable the instrumentation of Kubernetes jobs and cronjobs. The default for this config parameter is set to true.

The config setting at the namespace level will supersede the config setting at the global level for this parameter.

 

Deepfactor Pod Annotations

In addition to mutating webhook config, Deepfactor supports the following pod annotations to enable and configure Deepfactor instrumentation of your pods. These annotations can also be used to override any specific configuration defined in the webhook config for the instrumented namespace.

 

Pod Annotation Description
df.k8-app.registration/inject This must be set to "enabled" to enable Deepfactor mutation on pods. This annotation can be also set to "disabled" to disable mutation on a pod deployed in one of the instrumented namespaces.
df-k8-app.name

When set, this will be used as an application name to register the Kubernetes workload with the Deepfactor platform. This can be used to override value computed by the webhook based on config and pod specs.

df.k8-app.run.token/runtoken This option need not be specified at each pod level and can be specified at the global level in the webhook config. However, when specified, it will override the value configured in webhook.dfRunToken.
df.k8-app.tag

Specify comma-separated key-value pairs to tag instances of the current deployment. If this optional parameter is specified, users can filter such using tags.

Example: -t "key1=value1,key2=value2"

df.k8-app.comp/name

When specified, this will be used as a component name to register the Kubernetes workload with the Deepfactor platform. This annotation can be used to override the default value of the container registry and repo info set by the webhook.

df.k8-app.comp/version

When specified, this will be used as the version of the component while registering the Kubernetes workload with the Deepfactor platform. This annotation can be used to override the default value set to the container image tag by the webhook.

df.k8-app.lsa Deepfactor automatically detects the programming language per process and injects the appropriate language specific agent hence this option is not required for most common use cases. However, there may be special cases where you might want to set this option. For example, you only want to enable stack traces only for java applications in your namespace. You can read more about Deepfactor LSA in the following document Language-Specific Agents.
This annotation can be used to override the config in webhookconfig.namespaces[x].lsa.
df.k8-app.env/name

This annotation can be used to set the application's execution environment created on the Deepfactor platform. You can filter insights based on the environment you specify. If specified, this overrides the value specified in webhookconfig.namespaces[x].envName

df.k8-app.alert/policy

This can be used to set the alert policy to be used for the Kubernetes workload being deployed. Without any alert-policy specified, the applications get registered with the default alert policy configured on the Deepfactor platform. If specified, this overrides the value specified in webhookconfig.namespaces[x].alertPolicy.

df.k8-app.http/proxy and df.k8-app.https/proxy

These optional annotations can be used to set the proxy which must be used for registering the application with the Deepfactor platform. If specified, this overrides the value specified in webhookconfig.httpProxy and webhookconfig.httpsProxy.

df.k8-app.multilibc

Deepfactor runtime supports a musl libc (alpine) process starting a glibc process, and vice versa e.g. alpine-musl image with java-glibc. Default is "auto" and you can set it to "false" to disable detection of libc type.
You can read more about this option in the below article
Mixed libc environments

df.k8-app.imageid

This optional annotation can be used set the container image-id instrumented using the webhook.

df.k8-app.namespace

The namespace is determined by the webhook. However, the namespace information can be overridden using this annotation.

df.k8-app.entrypoint.libc

The libc of the entrypoint binary is determined by the runtime checks. The auto-detected libc type cab be overridden using this annotation.

df.k8-app.entrypoint.path

The pod container entrypoint binary is determined by the image analyzer service deployed along with the webhook. The auto-detected entrypoint can be overridden using this annotation.

df.k8-app.stack-traces Deepfactor's language specific agents (LSA) collect language specific stack traces. The agents to collect stack traces are supported for Java and Python applications. For other languages, this option is ignored and will not have any impact on the application. This option is enabled by default and can be disabled by setting this option to disabled. When specified, this will override the value specified in webhookconfig.namespaces[x].stackTraces.
Note: Stack traces for C runtime is always enabled and is not dependent on this configuration.
df.k8-app.method-tracing When set to true, agents to collect usage telemetry (methods, etc) will be injected for each process in the application instances monitored by Deepfactor runtime. The agent to collect method usage information is only supported for Java applications. For other languages, this option is ignored and will not have any impact on the application. If specified, this will override the value specified in webhookconfig.namespaces[x].methodTracing.

 

In addition to pod scope annotations, annotations can be set in the pod spec for a specific container in the pod. Pod container annotations take precedence over pod annotations. Likewise, pod annotations take precedence over webhookconfig namespace defaults.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.