Java agent injector Manual

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.

Install Injector

The java agent injector is a component of the operator, so you need to follow Operator installation instrument to install the operator firstly.

Active the java agent injection

We have two granularities here: namespace and pod.

ResourceLabelEnabled valueDisabled value
Namespaceswck-injectionenableddisabled
Podswck-java-agent-injected“true”“false”

The injector is configured with the following logic:

  1. If either label is disabled, the pod is not injected.
  2. If two labels are enabled, the pod is injected.

Follow the next steps to active java agent injection.

  • Label the namespace with swck-injection=enabled
$ kubectl label namespace default(your namespace) swck-injection=enabled
  • Add label 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 ways to configure the agent

The java agent injector supports a precedence order to configure the agent:

Annotations > SwAgent > Configmap (Deprecated) > Default Configmap (Deprecated)

Annotations

Annotations are described in kubernetes annotations doc.

We support annotations in agent annotations and sidecar annotations.

SwAgent

SwAgent is a Customer Resource defined by SWCK.

We support SwAgent in SwAgent usage guide

Configmap (Deprecated)

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.

Default configmap (Deprecated)

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.

Configure the agent

The injector supports two methods to configure agent:

  • Only use the default configuration.
  • Use annotations to overlay the default configuration.

Use the default agent configuration

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.10.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

Use SwAgent to overlay default agent configuration

The injector will read the SwAgent CR when pods creating.

SwAgent CRD basic structure is like:

apiVersion: operator.skywalking.apache.org/v1alpha1
kind: SwAgent
metadata:
  name: swagent-demo
  namespace: default
spec:
  containerMatcher: ''
  selector:
  javaSidecar:
    name: swagent-demo
    image: apache/skywalking-java-agent:8.10.0-java8
    env:
      - name: "SW_LOGGING_LEVEL"
        value: "DEBUG"
      - name: "SW_AGENT_COLLECTOR_BACKEND_SERVICES"
        value: "skywalking-system-oap:11800"
  sharedVolumeName: "sky-agent-demo"
  optionalPlugins:
    - "webflux"
    - "cloud-gateway-2.1.x"

There are three kind of configs in SwAgent CR.

1. label selector and container matcher

label selector and container matcher decides which pod and container should be injected.

key pathdescriptiondefault value
spec.selectorlabel selector for pods which should be effected during injection. if no label selector was set, SwAgent CR config will affect every pod during injection.no default value
spec.containerMatchercontainer matcher is used to decide which container to be inject during injection. regular expression is supported. default value ‘.*’ would match any container name..*

2. injection configuration

injection configuration will affect on agent injection behaviour

key pathdescriptiondefault value
javaSidecarjavaSidecar is the configs for init container, which holds agent sdk and take agent sdk to the target containers.
javaSidecar.namethe name of the init container.inject-skywalking-agent
javaSidecar.imagethe image of the init container.apache/skywalking-java-agent:8.8.0-java8
SharedVolumeNameSharedVolume is the name of an empty volume which shared by initContainer and target containers.sky-agent
SwConfigMapVolumeSwConfigMapVolume defines the configmap which contains agent.configno default value
OptionalPluginsSelect the optional plugin which needs to be moved to the directory(/plugins). Such as trace,webflux,cloud-gateway-2.1.x.no default value
OptionalReporterPluginsSelect the optional reporter plugin which needs to be moved to the directory(/plugins). such as kafka.no default value

3. skywalking agent configuration

skywalking agent configuration is for agent SDK.

key pathdescriptiondefault value
javaSidecar.envthe env list to be appended to target containers. usually we can use it to setup agent configuration at container level.no default value.

Use annotations to overlay default agent configuration

The injector can recognize five kinds of annotations to configure the agent as below.

1. strategy configuration

The strategy configuration is the annotation as below.

Annotation keyDescriptionAnnotation Default value
strategy.skywalking.apache.org/inject.ContainerSelect the injected container, if not set, inject all containers.not set

2. agent configuration

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.

3. plugins configuration

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.

4. optional plugin configuration

The optional plugin configuration is the annotation as below.

Annotation keyDescriptionAnnotation value
optional.skywalking.apache.orgSelect 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

5. optional reporter plugin configuration

The optional reporter plugin configuration is the annotation as below.

Annotation keyDescriptionAnnotation value
optional-reporter.skywalking.apache.orgSelect 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

Configure sidecar

The injector can recognize the following annotations to configure the sidecar:

Annotation keyDescriptionAnnotation Default value
sidecar.skywalking.apache.org/initcontainer.NameThe name of the injected java agent container.inject-skywalking-agent
sidecar.skywalking.apache.org/initcontainer.ImageThe container image of the injected java agent container.apache/skywalking-java-agent:8.10.0-java8
sidecar.skywalking.apache.org/initcontainer.CommandThe command of the injected java agent container.sh
sidecar.skywalking.apache.org/initcontainer.args.OptionThe args option of the injected java agent container.-c
sidecar.skywalking.apache.org/initcontainer.args.CommandThe args command of the injected java agent container.mkdir -p /sky/agent && cp -r /skywalking/agent/* /sky/agent
sidecar.skywalking.apache.org/initcontainer.resources.limitsThe resources limits of the injected java agent container. You should use json type to define it such as {"memory": "100Mi","cpu": "100m"}nil
sidecar.skywalking.apache.org/initcontainer.resources.requestsThe resources requests of the injected java agent container. You should use json type to define it such as {"memory": "100Mi","cpu": "100m"}nil
sidecar.skywalking.apache.org/sidecarVolume.NameThe name of sidecar Volume.sky-agent
sidecar.skywalking.apache.org/sidecarVolumeMount.MountPathMount path of the agent directory in the injected container./sky/agent
sidecar.skywalking.apache.org/configmapVolume.NameThe name of configmap volume.java-agent-configmap-volume
sidecar.skywalking.apache.org/configmapVolumeMount.MountPathMount path of the configmap in the injected container/sky/agent/config
sidecar.skywalking.apache.org/configmapVolume.ConfigMap.NameThe name pf configmap used in the injected container as agent.config skywalking-swck-java-agent-configmap
sidecar.skywalking.apache.org/env.NameEnvironment Name used by the injected container (application container).JAVA_TOOL_OPTIONS
sidecar.skywalking.apache.org/env.ValueEnvironment variables used by the injected container (application container).-javaagent:/sky/agent/skywalking-agent.jar

The ways to get the final injected agent's configuration

Please see javaagent introduction for details.