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:
|
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:
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:
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:
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 |
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:
|
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:
|
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. |
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: |
webhookconfig.namespaces[x].selector.matchExpressions |
List of pod selector requirements. More information regarding selecting the pods can be found in the following article: |
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 |
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 |
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 |
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. |
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 |
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.
Comments
0 comments
Please sign in to leave a comment.