To use the java agent more natively, we propose the java agent injector to inject the agent sidecar into a pod.
When enabled in a pod's namespace, the injector injects the java agent container at pod creation time using a mutating webhook admission controller. By rendering the java agent to a shared volume, containers within the pod can use the java agent.
The following sections describe how to configure the agent, if you want to try it directly, please see Usage for more details.
The java agent injector is a component of the operator, so you need to follow Operator installation instrument to install the operator firstly.
We have two granularities here: namespace and pod.
| Resource | Label | Enabled value | Disabled value |
|---|---|---|---|
| Namespace | swck-injection | enabled | disabled |
| Pod | swck-java-agent-injected | “true” | “false” |
The injector is configured with the following logic:
Follow the next steps to active java agent injection.
swck-injection=enabled$ kubectl label namespace default(your namespace) swck-injection=enabled
swck-java-agent-injected: "true" to the pod, and get the result as below.$ kubectl get pod -l swck-java-agent-injected=true NAME READY STATUS RESTARTS AGE inject-demo 1/1 Running 0 2d2h
The java agent injector supports a precedence order to configure the agent:
Annotations > Configmap > Default configmap
Annotations are described in kubernetes annotations doc.
We support annotations in agent annotations and sidecar annotations.
Configmap is described in kubernetes configmap doc.
We need to use configmap to set agent.config so that we can modify the agent configuration without entering the container.
If there are different configmap in the namepsace, you can choose a configmap by setting sidecar annotations; If there is no configmap, the injector will create a default configmap.
The injector will create the default configmap to overlay the agent.config in the agent container.
The default configmap is shown as below, one is agent.service_name and the string can't be empty; the other is collector.backend_service and it needs to be a legal IP address and port, the other fields need to be guaranteed by users themselves. Users can change it as their default configmap.
data:
agent.config: |
# The service name in UI
agent.service_name=${SW_AGENT_NAME:Your_ApplicationName}
# Backend service addresses.
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800}
# Please refer to https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configurations/#table-of-agent-configuration-properties to get more details.
To avoid the default configmap deleting by mistake, we use a configmap controller to watch the default configmap. In addition, if the user applies an invalid configuration, such as a malformed backend_service, the controller will use the default configmap.
The injector supports two methods to configure agent:
After activating the java agent injection, if not set the annotations, the injector will use the default agent configuration directly as below.
initContainers:
- args:
- -c
- mkdir -p /sky/agent && cp -r /skywalking/agent/* /sky/agent
command:
- sh
image: apache/skywalking-java-agent:8.8.0-java8
name: inject-skywalking-agent
volumeMounts:
- mountPath: /sky/agent
name: sky-agent
volumes:
- emptyDir: {}
name: sky-agent
- configMap:
name: skywalking-swck-java-agent-configmap
name: java-agent-configmap-volume
The injector can recognize five kinds of annotations to configure the agent as below.
The strategy configuration is the annotation as below.
| Annotation key | Description | Annotation Default value |
|---|---|---|
strategy.skywalking.apache.org/inject.Container | Select the injected container, if not set, inject all containers. | not set |
strategy.skywalking.apache.org/agent.Overlay | Whether to overlay the agent configuration. If set true, then you can see the next details to configure the agent. If set false, then you can skip Configure agent. | false |
The agent configuration is the annotation like agent.skywalking.apache.org/{option}: {value}, and the option support agent.xxx 、osinfo.xxx 、collector.xxx 、 logging.xxx 、statuscheck.xxx 、correlation.xxx 、jvm.xxx 、buffer.xxx 、 profile.xxx 、 meter.xxx 、 log.xxx in agent.config, such as agent.skywalking.apache.org/agent.namespace, agent.skywalking.apache.org/meter.max_meter_size, etc.
The plugins configuration is the annotation like plugins.skywalking.apache.org/{option}: {value}, and the option only support plugin.xxx in the agent.config, such as plugins.skywalking.apache.org/plugin.mount, plugins.skywalking.apache.org/plugin.mongodb.trace_param, etc.
The optional plugin configuration is the annotation as below.
| Annotation key | Description | Annotation value |
|---|---|---|
optional.skywalking.apache.org | Select the optional plugin which needs to be moved to the directory(/plugins). Users can select several optional plugins by separating from ｜, such as trace｜webflux｜cloud-gateway-2.1.x. | not set |
The optional reporter plugin configuration is the annotation as below.
| Annotation key | Description | Annotation value |
|---|---|---|
optional-reporter.skywalking.apache.org | Select the optional reporter plugin which needs to be moved to the directory(/plugins). Users can select several optional reporter plugins by separating from ｜, such as kafka. | not set |
The injector can recognize the following annotations to configure the sidecar:
| Annotation key | Description | Annotation Default value |
|---|---|---|
sidecar.skywalking.apache.org/initcontainer.Name | The name of the injected java agent container. | inject-skywalking-agent |
sidecar.skywalking.apache.org/initcontainer.Image | The container image of the injected java agent container. | apache/skywalking-java-agent:8.8.0-java8 |
sidecar.skywalking.apache.org/initcontainer.Command | The command of the injected java agent container. | sh |
sidecar.skywalking.apache.org/initcontainer.args.Option | The args option of the injected java agent container. | -c |
sidecar.skywalking.apache.org/initcontainer.args.Command | The args command of the injected java agent container. | mkdir -p /sky/agent && cp -r /skywalking/agent/* /sky/agent |
sidecar.skywalking.apache.org/sidecarVolume.Name | The name of sidecar Volume. | sky-agent |
sidecar.skywalking.apache.org/sidecarVolumeMount.MountPath | Mount path of the agent directory in the injected container. | /sky/agent |
sidecar.skywalking.apache.org/configmapVolume.Name | The name of configmap volume. | java-agent-configmap-volume |
sidecar.skywalking.apache.org/configmapVolumeMount.MountPath | Mount path of the configmap in the injected container | /sky/agent/config |
sidecar.skywalking.apache.org/configmapVolume.ConfigMap.Name | The name pf configmap used in the injected container as agent.config | skywalking-swck-java-agent-configmap |
sidecar.skywalking.apache.org/env.Name | Environment Name used by the injected container (application container). | JAVA_TOOL_OPTIONS |
sidecar.skywalking.apache.org/env.Value | Environment variables used by the injected container (application container). | -javaagent:/sky/agent/skywalking-agent.jar |
Please see javaagent introduction for details.