You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by GitBox <gi...@apache.org> on 2021/09/23 16:17:02 UTC
[GitHub] [skywalking-swck] dashanji opened a new pull request #33: Add java agent injector manual.
dashanji opened a new pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33
This is a manual about how to use the java agent injector.(docs/examples/java-agent-injector.md)
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] kezhenxu94 commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
kezhenxu94 commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718492928
##########
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
I think this is needed because only via namespace annotation you don't know which language agent should be injected, you definitely don't want to inject a Java agent to a Python application 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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] dashanji commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
dashanji commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718619552
##########
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:
OK , I hava a small question there, the webhook only support namespaceSelector or objectSelector . If either namespace or pod label can active the injector, we need to get every pod's label or the namespace's label in the webhook, the load of the webhook may increase a lot.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718989198
##########
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:
After doing some investigation, the injected pods belong to an intersection of these selectors, I thought it's an union:
https://github.com/kubernetes/apiserver/blob/92392ef22153d75b3645b0ae339f89c12767fb52/pkg/admission/plugin/webhook/generic/webhook.go#L143
All right, let's keep it as is.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily commented on pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#issuecomment-927003014
Noted with thanks, I am gonna add one
On Sat, Sep 25, 2021 at 10:45 AM 吴晟 Wu Sheng ***@***.***>
wrote:
> @hanahmily <https://github.com/hanahmily> Is it better to add menu filr
> and reorganize this repo docs folder, in order to host docs on the website?
> More and more repositories have been using this mode.
>
> —
> You are receiving this because you were mentioned.
>
>
> Reply to this email directly, view it on GitHub
> <https://github.com/apache/skywalking-swck/pull/33#issuecomment-926998898>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAO6UWLCZRNHJ6FNWJT44D3UDUZVTANCNFSM5EUB2HNQ>
> .
>
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718515253
##########
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] wu-sheng commented on pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
wu-sheng commented on pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#issuecomment-926998898
@hanahmily Is it better to add menu filr and reorganize this repo docs folder, in order to host docs on the website? More and more repositories have been using this mode.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] kezhenxu94 commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
kezhenxu94 commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718492928
##########
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
I think this is needed because only via namespace annotation you don't know which language agent should be injected, you definitely don't want to inject a Java agent to a Python application Pod
##########
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:
Yes if that's the case we might want to keep only one annotation name, which can be applied in namespace level or Pod level, instead of 2 different annotation name
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] dashanji commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
dashanji commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r715978633
##########
File path: config/operator/configmap/configmap.yaml
##########
@@ -45,17 +45,16 @@ data:
# The service name in UI
Review comment:
> The configmap and annotation template should shrink to a smaller size.
>
> Would you please split the document into two separate files: one, from 1 to 3, goes to `docs/`. another, section 4, keeps in `docs/example`
>
> The first document should contain the following steps:
>
> 1. how to install an agent injector
> 2. how to active agent injection. We have two granularities here: namespace and pod
> 3. how to config the agent. injector supports a precedence order: annotation, confgmap and default configmap.
> 4. how to config agent.
> 5. how to config sidecar.
ok , I will clean the code and update doc.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily merged pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily merged pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] dashanji commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
dashanji commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718619552
##########
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:
OK , I hava a small question there, the webhook only support namespaceSelector or objectSelector . If either namespace or pod label can active the injector, we need to get every pod's label or the namespace's label in the webhook, the load of the webhook may increase a lot.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718989344
##########
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:
Let's keep it as is.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] dashanji commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
dashanji commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r715978633
##########
File path: config/operator/configmap/configmap.yaml
##########
@@ -45,17 +45,16 @@ data:
# The service name in UI
Review comment:
ok ,
> The configmap and annotation template should shrink to a smaller size.
>
> Would you please split the document into two separate files: one, from 1 to 3, goes to `docs/`. another, section 4, keeps in `docs/example`
>
> The first document should contain the following steps:
>
> 1. how to install an agent injector
> 2. how to active agent injection. We have two granularities here: namespace and pod
> 3. how to config the agent. injector supports a precedence order: annotation, confgmap and default configmap.
> 4. how to config agent.
> 5. how to config sidecar.
> The configmap and annotation template should shrink to a smaller size.
>
> Would you please split the document into two separate files: one, from 1 to 3, goes to `docs/`. another, section 4, keeps in `docs/example`
>
> The first document should contain the following steps:
>
> 1. how to install an agent injector
> 2. how to active agent injection. We have two granularities here: namespace and pod
> 3. how to config the agent. injector supports a precedence order: annotation, confgmap and default configmap.
> 4. how to config agent.
> 5. how to config sidecar.
ok , I will clean the code and update doc.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718511514
##########
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`.
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] kezhenxu94 commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
kezhenxu94 commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r718513471
##########
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:
Yes if that's the case we might want to keep only one annotation name, which can be applied in namespace level or Pod level, instead of 2 different annotation name
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
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.
```
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [skywalking-swck] hanahmily commented on a change in pull request #33: Add java agent injector manual.
Posted by GitBox <gi...@apache.org>.
hanahmily commented on a change in pull request #33:
URL: https://github.com/apache/skywalking-swck/pull/33#discussion_r715624082
##########
File path: config/operator/configmap/configmap.yaml
##########
@@ -45,17 +45,16 @@ data:
# The service name in UI
Review comment:
As we disscussed, `agent.config` should be like:
```yaml
# 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.
```
##########
File path: pkg/operator/manifests/injector/templates/annotations.yaml
##########
@@ -113,12 +113,6 @@ annotations:
useQuotes: nil
Review comment:
Like the configmap, we should verify the service name and collector address at most.
##########
File path: docs/examples/java-agent-injector.md
##########
@@ -0,0 +1,333 @@
+## Java agent injector manual
+
+The java agent injector consists of three parts:
Review comment:
should be "support two methods to configure the agent"
--
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-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org