hanahmily commented on a change in pull request #33: URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718458035
########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. + +The following sections describe how to configure agent, if you want to try it directly, please see [Usage](examples/java-agent-injector-usage) for more details. + +## Install Injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../README.md#operator) to install the operator firstly. + +## Active java agent injectoin + +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: + +1. If either label is disabled, the pod is not injected. +2. If two labels are enabled, the pod is injected. Review comment: IIRC, either label is enabled, the pod CAN be injected. The pod granularity only helps users to enable injection for some specific pods which belong to a namespace without the `sw-injection` label. ########## File path: docs/examples/java-agent-injector-usage.md ########## @@ -0,0 +1,255 @@ +# Java agent injector Usage + +In this example , you will learn how to use the java agent injector in three ways. + +## Install injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../../README.md#operator) to install the operator firstly. + +## Use default configuration + +At first , set the injection label in your namespace as below. + +```shell +kubectl label namespace default(your namespace) swck-injection=enabled +``` + +Then add `swck-java-agent-injected: "true"` in the labels of yaml file as below. Review comment: Why add this label since we actived injector in the namespace ########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. + +The following sections describe how to configure agent, if you want to try it directly, please see [Usage](examples/java-agent-injector-usage) for more details. + +## Install Injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../README.md#operator) to install the operator firstly. + +## Active java agent injectoin + +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: + +1. If either label is disabled, the pod is not injected. +2. If two labels are enabled, the pod is injected. + +Follow next steps to active java agent injection. Review comment: ```suggestion Follow the next steps to active java agent injection. ``` ########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. + +The following sections describe how to configure agent, if you want to try it directly, please see [Usage](examples/java-agent-injector-usage) for more details. + +## Install Injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../README.md#operator) to install the operator firstly. + +## Active java agent injectoin + +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: + +1. If either label is disabled, the pod is not injected. +2. If two labels are enabled, the pod is injected. + +Follow next steps to active java agent injection. + +* Label the namespace with `swck-injection=enabled` + +```shell +$ 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. + +```shell +$ 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 support a precedence order to configure the agent: + +``` Annotations > Configmap > Default configmap``` + +### Annotations + +Annotations are described in [kubernetes annotations doc](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/). + +We support annotations in [agent annotations](#Use-annotations-to-overlay-default-agent-configuration) and [sidecar annotations](#configure-sidecar). + +### Configmap + +Configmap is described in [kubernetes configmap doc](https://kubernetes.io/docs/concepts/configuration/configmap/). + +We need to use configmap to set [agent.config](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configurations/#table-of-agent-configuration-properties), 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](#configure-sidecar); If there is no configmap , the injector will create a default configmap. + +### Default configmap + +when we active the injector, it will create a default configmap to overlay the `agent.config` in agent container. Review comment: ```suggestion The injector will create a default configmap to overlay the `agent.config` in the agent container. ``` ########## File path: docs/examples/java-agent-injector-usage.md ########## @@ -0,0 +1,255 @@ +# Java agent injector Usage + +In this example , you will learn how to use the java agent injector in three ways. + +## Install injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../../README.md#operator) to install the operator firstly. Review comment: ```suggestion The java agent injector is a component of the operator, so you need to follow [Operator installation instrument](../../README.md#operator) to install the operator firstly. ``` ########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. Review comment: ```suggestion When enabled in a pod's namespace or a specific pod, the injector injects the java agent container at pod creation time using a mutating webhook admission controller. By rendering java agent to a shared volume, containers within the pod can use the java agent. ``` ########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. + +The following sections describe how to configure agent, if you want to try it directly, please see [Usage](examples/java-agent-injector-usage) for more details. + +## Install Injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../README.md#operator) to install the operator firstly. + +## Active java agent injectoin + +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: + +1. If either label is disabled, the pod is not injected. +2. If two labels are enabled, the pod is injected. + +Follow next steps to active java agent injection. + +* Label the namespace with `swck-injection=enabled` + +```shell +$ 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. + +```shell +$ 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 support a precedence order to configure the agent: + +``` Annotations > Configmap > Default configmap``` + +### Annotations + +Annotations are described in [kubernetes annotations doc](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/). + +We support annotations in [agent annotations](#Use-annotations-to-overlay-default-agent-configuration) and [sidecar annotations](#configure-sidecar). + +### Configmap + +Configmap is described in [kubernetes configmap doc](https://kubernetes.io/docs/concepts/configuration/configmap/). + +We need to use configmap to set [agent.config](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configurations/#table-of-agent-configuration-properties), 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](#configure-sidecar); If there is no configmap , the injector will create a default configmap. + +### Default configmap + +when we active the injector, it will create a default configmap to overlay the `agent.config` in agent container. + +The default configmap is shown as below , one is `agent.service_name` and the string cann'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. User 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 user update it but validate error , such as using wrong backend_service , the controller will create the default configmap. Review comment: ```suggestion 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. ``` ########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. + +The following sections describe how to configure agent, if you want to try it directly, please see [Usage](examples/java-agent-injector-usage) for more details. + +## Install Injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../README.md#operator) to install the operator firstly. + +## Active java agent injectoin + +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: + +1. If either label is disabled, the pod is not injected. +2. If two labels are enabled, the pod is injected. + +Follow next steps to active java agent injection. + +* Label the namespace with `swck-injection=enabled` + +```shell +$ 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. + +```shell +$ 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 support a precedence order to configure the agent: Review comment: ```suggestion The java agent injector supports a precedence order to configure the agent: ``` ########## File path: docs/java-agent-injector.md ########## @@ -0,0 +1,168 @@ +# Java agent injector Manual + +In order to use java agent more natively , we propose the java agent injector to inject the agent sidecar to 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 java agent to a shared volume , containers within the pod can use the java agent. + +The following sections describe how to configure agent, if you want to try it directly, please see [Usage](examples/java-agent-injector-usage) for more details. + +## Install Injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../README.md#operator) to install the operator firstly. + +## Active java agent injectoin + +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: + +1. If either label is disabled, the pod is not injected. +2. If two labels are enabled, the pod is injected. + +Follow next steps to active java agent injection. + +* Label the namespace with `swck-injection=enabled` + +```shell +$ 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. + +```shell +$ 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 support a precedence order to configure the agent: + +``` Annotations > Configmap > Default configmap``` + +### Annotations + +Annotations are described in [kubernetes annotations doc](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/). + +We support annotations in [agent annotations](#Use-annotations-to-overlay-default-agent-configuration) and [sidecar annotations](#configure-sidecar). + +### Configmap + +Configmap is described in [kubernetes configmap doc](https://kubernetes.io/docs/concepts/configuration/configmap/). + +We need to use configmap to set [agent.config](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configurations/#table-of-agent-configuration-properties), 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](#configure-sidecar); If there is no configmap , the injector will create a default configmap. + +### Default configmap + +when we active the injector, it will create a default configmap to overlay the `agent.config` in agent container. + +The default configmap is shown as below , one is `agent.service_name` and the string cann'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. User can change it as their default configmap. Review comment: ```suggestion 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. ``` ########## File path: docs/examples/java-agent-injector-usage.md ########## @@ -0,0 +1,255 @@ +# Java agent injector Usage + +In this example , you will learn how to use the java agent injector in three ways. + +## Install injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../../README.md#operator) to install the operator firstly. + +## Use default configuration + +At first , set the injection label in your namespace as below. + +```shell +kubectl label namespace default(your namespace) swck-injection=enabled +``` + +Then add `swck-java-agent-injected: "true"` in the labels of yaml file as below. Review comment: if we have multi-language pods in a namespace, the pod granularity is enough. The namespace label is "configuration sugar" instead of a constraint. Thanks for your mentioning, the label name attached to a namespace should be `swck-java-injection`. ########## File path: docs/examples/java-agent-injector-usage.md ########## @@ -0,0 +1,255 @@ +# Java agent injector Usage + +In this example , you will learn how to use the java agent injector in three ways. + +## Install injector + +The java agent injector is builded in the operator , so you need to follow [Operator installation instrument](../../README.md#operator) to install the operator firstly. + +## Use default configuration + +At first , set the injection label in your namespace as below. + +```shell +kubectl label namespace default(your namespace) swck-injection=enabled +``` + +Then add `swck-java-agent-injected: "true"` in the labels of yaml file as below. Review comment: make sense to me. @dashanji please use the same annotation to both namespace and pod. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@skywalking.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org