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
