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"
Following are additional configurations that can be set in webhook-override.yaml
file.
-
webhookconfig.dfRunToken
This must be set to the run token that is required to register an application with the Deepfactor platform. This is set at the global webhook config level and can be overridden usingdf.k8-app.run.token/runtoken
annotation in pod yaml. -
webhookconfig.httpProxy
andwebhookconfig.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 annotationsdf.k8-app.http/proxy
anddf.k8-app.https/proxy
. -
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 container 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. This used to be the default until the 2.3.1 release
-
-
webhookconfig.namespaces.name
Name of the Kubernetes namespace to be instrumented. All workloads deployed in this namespace will run with Deepfactor instrumentation.
Note: You can exclude a workload from being instrumented in this namespace by adding an annotationdf.k8-app.registration/inject
and setting the value to "disabled
" -
webhookconfig.namespaces.alertPolicy
Set this to the name of the alert policy to be used for all workloads in this namespace. This is an optional parameter and can be overridden using annotationdf.k8-app.alert/policy
in the pod spec. Without any alert-policy specified, the applications get registered with the default alert policy configured on the Deepfactor platform. -
webhookconfig.namespaces.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 inwebhookconfig.appNameSource
-
webhookconfig.namespaces.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. In such a case, you can specify webhookconfig.namespaces.lsa="java-nativeagent".The possible values for the above option are
java-nativeagent
: Enables stack traces for java applications-
java-agent
: Enables method tracing for Java applications -
java
: Enables both stack traces and method tracing for Java applications -
python
: Enables stack traces for python applications.
Read more about it here: Language-Specific Agents
-
webhookconfig.namespaces.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 annotationdf.k8-app.env/name
in the pod spec. More information about the environments can be found at Creating Multiple Environments -
webhookconfig.namespaces.stackTraces
When set to true, agents to collect stack traces will be injected for each process in the application instances monitored by Deepfactor runtime. 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 config can be overridden using annotationdf.k8-app.stack-traces
in the pod spec.
Note: Stack traces for C runtime is always enabled and is not dependent on this configuration -
webhookconfig.namespaces.methondTracing
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 annotationdf.k8-app.method-tracing
in the pod spec. -
webhookconfig.namespaces.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.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.excludePodNamePrefixes
List of pod name prefixes that will be excluded from mutation by webhook.webhookconfig.namespaces.excludeImageNamePrefixes
List of image name prefixes that will be excluded from mutation by webhook.webhookconfig.namespaces.excludePodNameRegularExpressions
List of pod name regex that will be used to determine pod names to be excluded from mutation by webhook.webhookconfig.namespaces.excludeImageNameRegularExpressions
List of imagename regex that will be used to determine images to be excluded from mutation by webhook.
Instrument Kubernetes Workloads Using Pod Annotations
Deepfactor supports the following annotation to trigger pod mutation on workloads deployed in the namespaces that are not configured in webhook config. These annotations can also be used to override any specific configuration defined in the webhook config for the instrumented namespace.
-
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 must be specified to the run token required to register an application with the Deepfactor platform. If specified, it will be used to override the value configured in the 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
This must be set to the enable agents that can be used to collect stack traces and method tracing data for applications running with Deepfactor runtime. The value can be set to one of the following two options-
java-agent
: Can be used to enable method tracking. -
java-nativeagent
: Can be used to enable stack tracing. -
java
: Can be used to enablejava-agent
as well asjava-nativeagent
to collect method tracking as well as stack tracing. -
python
: Can be used to enable Python agents to collect stack tracing.
This annotation can be used to override the config in
webhookconfig.namespaces.lsa
. Read more about it here: Language-Specific Agents. -
-
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 inwebhookconfig.namespaces.envName
. More information about the environments can be found at Creating Multiple Environments -
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 inwebhookconfig.namespaces.alertPolicy
. -
df.k8-app.http/proxy
anddf.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 inwebhookconfig.httpProxy
andwebhookconfig.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
Thelibc
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
When set to true, agents to collect stack traces will be injected for each process in the application instances monitored by Deepfactor runtime. 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. When specified, this will override the value specified inwebhookconfig.namespaces.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 instance monitored by Deepfactor runtime. Currently, Deepfactor only supportsjava
agents to collect method usage information 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 inwebhookconfig.namespaces.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.
Comments
0 comments
Please sign in to leave a comment.