Articles in this section

Configure Deepfactor Mutating Webhook Follow

Avatar
DeepFactor Support
  • Updated
 
 

Introduction

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.yaml or specify the config via CLI parameters for helm installation. Following is a sample override file for the webhook

webhookconfig:
  appNameSource: "podspec"
  httpProxy: ""
  httpsProxy: ""
  dfRunToken: "ey..."
  namespaces:
  - name: ""
    appName: "demo-app"
    alertPolicy: "Built-in-Policy Max Alert"
    envName: "staging"
    stackTraces: true
    methodTracing: true
    componentNameSource: "ImageAndTag"
    componentVersionSource: "ImageID"
    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

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 configuration 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:

  • namespace
  • podName
  • labels.x

The default value is - podName

webhookconfig.componentName

This optional parameter determines how the component name is decided by webhook while registering the apps with the Deepfactor platform.

The following are possible values for this config:

  • namespace
  • podName
  • containerName
  • containerImagePath
  • containerImageTag
  • labels.x

The default value is - containerName

webhookconfig.componentVersion

This optional parameter determines how the component name is decided by webhook while registering the apps with the Deepfactor platform.

The following are possible values for this config:

  • ImageID
  • ImageTag

The default value is - ImageTag
webhookconfig.namespaces[x].appName This optional parameter when set will be used as an application name for all the pods deployed in the namespace. Otherwise, the value will be chosen based on the configuration set in webhookconfig.appNameSource
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: disable 
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 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 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 this 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 this 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 this 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 this 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].appName

This optional parameter, when set, will be used as an application name for all the pods deployed in the namespace. Otherwise, the value will be chosen based on the configuration set in webhookconfig.appName

webhookconfig.namespaces[x].componentName

This optional parameter, when set, will be used as a component name for all the pods deployed in the namespace. Otherwise, the value will be chosen based on the configuration set in webhookconfig.componentName

webhookconfig.namespaces[x].componentVersion

This optional parameter, when set, will be used as a component name for all the pods deployed in the namespace. Otherwise, the value will be chosen based on the configuration set in webhookconfig.componentVersion

 

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.

Related articles

Comments

0 comments

Please sign in to leave a comment.