You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@skywalking.apache.org by wu...@apache.org on 2018/04/02 09:18:21 UTC
[incubator-skywalking] branch master updated: Provide advanced
features document (#1014)
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-skywalking.git
The following commit(s) were added to refs/heads/master by this push:
new 7a733ce Provide advanced features document (#1014)
7a733ce is described below
commit 7a733ce45896f17f34c29fd259fc3ae184d5897f
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Mon Apr 2 17:18:17 2018 +0800
Provide advanced features document (#1014)
* Provide document for TLS
* Provide direct uplink doc.
* Add namespace document.
* Provide token auth doc.
* Provide setting override document.
* Fix two typo.
* Fix more typos.
---
.../src/main/resources/application.yml | 1 +
apm-sniffer/config/agent.config | 3 ++
docs/README.md | 6 +++
docs/en/Deploy-skywalking-agent.md | 3 --
docs/en/Direct-uplink.md | 32 +++++++++++++++
docs/en/Namespace.md | 39 ++++++++++++++++++
docs/en/Setting-override.md | 24 +++++++++++
docs/en/TLS.md | 46 ++++++++++++++++++++++
docs/en/Token-auth.md | 46 ++++++++++++++++++++++
9 files changed, 197 insertions(+), 3 deletions(-)
diff --git a/apm-collector/apm-collector-boot/src/main/resources/application.yml b/apm-collector/apm-collector-boot/src/main/resources/application.yml
index bcaa653..a3a33ea 100644
--- a/apm-collector/apm-collector-boot/src/main/resources/application.yml
+++ b/apm-collector/apm-collector-boot/src/main/resources/application.yml
@@ -70,6 +70,7 @@ storage:
# user_name: sa
configuration:
default:
+ # namespace: xxxxx
application_apdex_threshold: 2000
service_error_rate_threshold: 10.00
service_average_response_time_threshold: 2000
diff --git a/apm-sniffer/config/agent.config b/apm-sniffer/config/agent.config
index 24f1ec9..dcf6afa 100644
--- a/apm-sniffer/config/agent.config
+++ b/apm-sniffer/config/agent.config
@@ -14,6 +14,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+# The agent namespace
+# agent.namespace=default-namespace
+
# The application name in UI
agent.application_code=Your_ApplicationName
diff --git a/docs/README.md b/docs/README.md
index 22e5489..a3bb22f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,6 +5,12 @@
* [Quick start](en/Quick-start.md)
* [Supported middlewares, frameworks and libraries](Supported-list.md)
* [How to disable plugins?](en/How-to-disable-plugin.md)
+ * Advanced Features
+ * [Override settings through System.properties or System.env](en/Setting-override.md)
+ * [Direct uplink and disable naming discovery](en/Direct-uplink.md)
+ * [Open TLS](en/TLS.md)
+ * [Namespace Isolation](en/Namespace.md)
+ * [Token Authentication](en/Token-auth.md)
* Application Toolkit
* [Overview](en/Applicaton-toolkit.md)
* [OpenTracing Tracer](en/Opentracing.md)
diff --git a/docs/en/Deploy-skywalking-agent.md b/docs/en/Deploy-skywalking-agent.md
index 900c39f..ae6eaac 100644
--- a/docs/en/Deploy-skywalking-agent.md
+++ b/docs/en/Deploy-skywalking-agent.md
@@ -27,9 +27,6 @@ New agent package looks like this：
# Advanced features
- All plugins are in `/plugin` folder. The plugin jar is active when it is in there. Remove the plugin jar, it disabled.
-- Besides set config through `/config/agent.config`, you can use System.Env and System.Properties(-D) to set config.
- - Key of env and properties = `skywalking.` + key in `agent.config` file
- - Priority: System.Env > System.Properties(-D) > `/config/agent.config`
- The default logging output folder is `/log`.
# Deploy agent in Tomcat FAQ
diff --git a/docs/en/Direct-uplink.md b/docs/en/Direct-uplink.md
new file mode 100644
index 0000000..11f49bb
--- /dev/null
+++ b/docs/en/Direct-uplink.md
@@ -0,0 +1,32 @@
+# Direct uplink
+## Supported version
+5.0.0-beta +
+
+## What is direct uplink?
+In default, SkyWalking agent uses naming service to find all collector addresses. Then connect to gRPC services.
+
+In **direct updalink**, mean no naming service available or don't work well, set the gRPC addresses in agent directly.
+The agent uses theses addresses to connect gRPC services.
+
+## Why need this?
+Agent uplink data through the following network
+1. VPCs in Cloud
+1. Internet
+1. Different subnet.
+1. IPs and Ports proxy
+
+## Set the agent config
+1. Remove `collector.servers` config item.
+2. You can find the following settings in `agent.config`
+```
+# Collector agent_gRPC/grpc service addresses.
+# Secondary address setting, only effect when "collector.servers" is empty.
+# By using this, no discovery mechanism provided. The agent only uses these addresses to uplink data.
+# Recommend to use this only when collector cluster IPs are unreachable from agent side. Such as:
+# 1. Agent and collector cluster are in different VPC in Cloud.
+# 2. Agent uplinks data to collector cluster through Internet.
+# collector.direct_servers=www.skywalking.service.io
+```
+
+3. Set `collector.direct_servers` to a domain name, IP:PORTs, with split by comma(,).
+
diff --git a/docs/en/Namespace.md b/docs/en/Namespace.md
new file mode 100644
index 0000000..d5e9fa5
--- /dev/null
+++ b/docs/en/Namespace.md
@@ -0,0 +1,39 @@
+# Namespace
+## Supported version
+5.0.0-beta +
+
+## Background
+SkyWalking is a monitoring tool, which collects metrics from a distributed system. In the real world, a very large distributed system
+includes hundreds of application, thousands of application instance. In that case, more likely, more than one group,
+even than one company are maintaining and monitoring the distributed system. Each one of them takes charge of different parts,
+don't or can't share there metrics.
+
+Namespace is proposal from this.It is used for tracing and monitoring isolation.
+
+## Set the namespace
+### Set agent.namespace in agent config
+```properties
+# The agent namespace
+# agent.namespace=default-namespace
+```
+
+The default value of `agent.namespace` is empty.
+
+**Influence**
+The default header key of SkyWalking is `sw3`, more in this [document](Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md).
+After `agent.namespace` set, the key changes to `namespace:sw3`.
+
+The across process propagation chain breaks, when the two sides are using different namespace.
+
+### Set namespace in collector
+```yml
+configuration:
+ default:
+ namespace: xxxxx
+```
+
+**Influences**
+1. If cluster model is active, with zookeeper implementation, The path in zookeeper is changed to include namespace prefix path.
+1. If use Elasticsearch as storage implementation, all type names are changed to include namespace prefix.
+
+
diff --git a/docs/en/Setting-override.md b/docs/en/Setting-override.md
new file mode 100644
index 0000000..41770e0
--- /dev/null
+++ b/docs/en/Setting-override.md
@@ -0,0 +1,24 @@
+# Setting Override
+## Supported version
+5.0.0-beta +
+
+_Agent setting override supported since 3.2.5_
+
+## What is setting override?
+In default, SkyWalking provide `agent.config` for client, and `application.yml` for server settings.
+
+Setting override means end user can override the settings in these config file, by using system properties, or system environment variables.
+
+## Override priority
+System.Env > System.Properties(-D) > Config file
+
+## Override
+### Agent
+Use `skywalking.` + key in config file as system properties and envs key, to override the value.
+
+- Why need this prefix?
+
+ The agent system properites and env share with target application, this prefix can avoid variable conflict.
+
+### Collector
+Use key in config file as system properties and envs key, to override the value.
\ No newline at end of file
diff --git a/docs/en/TLS.md b/docs/en/TLS.md
new file mode 100644
index 0000000..d67654f
--- /dev/null
+++ b/docs/en/TLS.md
@@ -0,0 +1,46 @@
+# Support Transport Layer Security (TLS)
+Transport Layer Security (TLS) is a very common security way when transport data through Internet.
+In some use cases, end users report the background:
+
+> Target(under monitoring) applications are in a region, which also named VPC,
+at the same time, the SkyWalking backend is in another region (VPC).
+>
+> Because of that, security requirement is very obvious.
+
+## Requirement
+Enable **direct uplink**, by following this [document](direct-uplink.md).
+
+Because of uplink through internet, with security concern, the naming mechanism didn't fit.
+So we didn't support TLS in naming service of HTTP service.
+
+## Supported version
+5.0.0-beta +
+
+## Authentication Mode
+Only support **no mutual auth**.
+- Use this [script](../../tools/TLS/tls_key_generate.sh) if you are not familiar with how to generate key files.
+- Find `ca.crt`, and use it at client side
+- Find `server.crt` and `server.pem`. Use them at server side.
+
+## Open and config TLS
+
+### Agent config
+- Place `ca.crt` into `/ca` folder in agent package. Notice, `/ca` is not created in distribution, please create it by yourself.
+
+Agent open TLS automatically after the `/ca/ca.crt` file detected.
+
+### Collector config
+Module `agent_gRPC/gRPC` supports TLS. And only this module for now.
+
+- Uncomment the `ssl_cert_chain_file` and `ssl_private_key_file` settings in `application.yml`
+- `ssl_cert_chain_file` value is the absolute path of `server.crt`
+- `ssl_private_key_file` value is the absolute path of `server.pem`
+
+## Avoid port share
+In most cases, we recommend sharing port for all gRPC services in `agent_gRPC/gRPC` and `remote/gRPC` modules.
+But don't do this when you open TLS in `agent_gRPC/gRPC`, the obvious reason is you can't listen a port with and without TLS.
+
+The solution is, change the `remote/gRPC/port`.
+
+## How about other listening ports
+Please use other security ways to make sure can't access other ports out of region (VPC), such as firewall, proxy.
\ No newline at end of file
diff --git a/docs/en/Token-auth.md b/docs/en/Token-auth.md
new file mode 100644
index 0000000..27c7543
--- /dev/null
+++ b/docs/en/Token-auth.md
@@ -0,0 +1,46 @@
+# Token Authentication
+## Supported version
+5.0.0-beta +
+
+## How need token authentication after we have TLS?
+TLS is about transport security, which makes sure the network can be trusted.
+The token authentication is about monitoring application data **can be trusted**.
+
+## Token
+In current version, Token is considered as a simple string.
+
+### Set Token
+1. Set token in agent.config file
+```properties
+# Authentication active is based on backend setting, see application.yml for more details.
+agent.authentication = xxxx
+```
+
+2. Set token in application.yml file
+```yaml
+agent_gRPC:
+ gRPC:
+ host: localhost
+ port: 11800
+
+ #Set your own token to active auth
+ authentication: xxxxxx
+```
+
+## Authentication fails
+The Collector verifies every request from agent, allowed only the token match.
+
+If the token is not right, you will see the following log in agent
+```
+org.apache.skywalking.apm.dependencies.io.grpc.StatusRuntimeException: PERMISSION_DENIED
+```
+
+## FAQ
+### Can I use token authentication instead of TLS?
+No, you shouldn't. In tech way, you can of course, but token and TLS are used for untrusted network env. In that circumstance,
+TLS has higher priority than this. Token can be trusted only under TLS protection.Token can be stolen easily if you
+send it through a non-TLS network.
+
+### Do you support other authentication mechanisms? Such as ak/sk?
+For now, no. But we appreciate someone contributes this feature.
+
--
To stop receiving notification emails like this one, please contact
wusheng@apache.org.