You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by ha...@apache.org on 2021/10/22 09:20:12 UTC
[skywalking-swck] branch master updated: Polish documents (#39)
This is an automated email from the ASF dual-hosted git repository.
hanahmily pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking-swck.git
The following commit(s) were added to refs/heads/master by this push:
new 2fad259 Polish documents (#39)
2fad259 is described below
commit 2fad2590d6ff3f20b550d5ce9ae806096c9fcc26
Author: Gao Hongtao <ha...@gmail.com>
AuthorDate: Fri Oct 22 17:20:08 2021 +0800
Polish documents (#39)
* Polish documents
* Re-arrage documetns
* Add README.md in the root of docs folder
* Add menu.yml to help generate the menu of website
Signed-off-by: Gao Hongtao <ha...@gmail.com>
* Update menu.yml
Signed-off-by: Gao Hongtao <ha...@gmail.com>
* Update links
Signed-off-by: Gao Hongtao <ha...@gmail.com>
---
CHANGES.md | 3 +-
README.md | 28 +++++++------------
docs/README.md | 13 +++++++++
docs/examples/storage.md | 4 +--
docs/menu.yml | 52 ++++++++++++++++++++++++++++++++++
docs/operator.md | 73 ++++++++++++++++++++++++++++++++----------------
6 files changed, 128 insertions(+), 45 deletions(-)
diff --git a/CHANGES.md b/CHANGES.md
index 4155c61..bad9474 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,7 +8,7 @@ Release Notes.
#### Features
- Add Java agent injector.
-- Add the storage module of the operator.
+- Add JavaAgent and Storage CRDs of the operator.
### Vulnerabilities
@@ -18,6 +18,7 @@ Release Notes.
#### Chores
- Bump up GO to 1.17.
- Bump up k8s api to 0.20.11.
+- Polish documents.
0.3.0
------------------
diff --git a/README.md b/README.md
index fa9fb11..df1f475 100644
--- a/README.md
+++ b/README.md
@@ -11,14 +11,23 @@ SWCK is a platform for the SkyWalking user, provisions, upgrades, maintains SkyW
# Features
+ 1. Java Agent Injector: Inject the java agent into the application pod natively.
1. Operator: Provision and maintain SkyWalking backend components.
1. Custom Metrics Adapter: Provides custom metrics come from SkyWalking OAP cluster for autoscaling by Kubernetes HPA
- 1. Java Agent Injector: Inject the java agent into the application pod natively.
# Quick Start
* Go to the [download page](https://skywalking.apache.org/downloads/#SkyWalkingCloudonKubernetes) to download latest release manifest.
+## Java Agent Injector
+
+* Inject the java agent into the application pod.
+* Use the default agent configuration.
+* Use annotations to overlay sidecar configuration and agent configuration.
+* Get the final injected agent's configuration.
+
+For more details, please read [Java agent injector](docs/java-agent-injector.md)
+
## Operator
* To install the operator in an existing cluster, make sure you have [`cert-manager` installed](https://cert-manager.io/docs/installation/)
@@ -30,14 +39,6 @@ SWCK is a platform for the SkyWalking user, provisions, upgrades, maintains SkyW
For more details, please refer to [deploy operator](docs/operator.md)
-### Examples of the Operator
-
-There are some instant examples to represent the functions or features of the Operator.
-
- - [Deploy OAP server and UI with default settings](./docs/examples/default-backend.md)
- - [Fetch metrics from the Istio control plane(istiod)](./docs/examples/istio-controlplane.md)
- - [Inject the java agent into the application pod](./docs/examples/java-agent-injector-usage.md)
-
## Custom Metrics Adapter
* Deploy OAP server by referring to Operator Quick Start.
@@ -49,15 +50,6 @@ There are some instant examples to represent the functions or features of the Op
For more details, please read [Custom metrics adapter](docs/custom-metrics-adapter.md)
-## Java Agent Injector
-
-* Inject the java agent into the application pod.
-* Use the default agent configuration.
-* Use annotations to overlay sidecar configuration and agent configuration.
-* Get the final injected agent's configuration.
-
-For more details, please read [Java agent injector](docs/java-agent-injector.md)
-
# Contributing
For developers who want to contribute to this project, see [Contribution Guide](CONTRIBUTING.md)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..31de7c1
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,13 @@
+Welcome to Apache SkyWalking Cloud on Kubernetes Document Repository
+============
+
+Here you can lean all you need to know about Apache SkyWalking Cloud on Kubernetes(SWCK). This
+repository provides how to onboard and customize the agent injector, operator and adapter.
+
+ * Design. Some materials regarding the design decision under the hood.
+ * Setup. Several instruments to onboard the agent injector, operator and adapter.
+ * Examples. A number of examples of how to use SWCK.
+
+We're always looking for help to improve our documentation and codes, so please don’t hesitate to file an issue
+if you see any problems. Or better yet, directly contribute by submitting a pull request to help us get better!
+
diff --git a/docs/examples/storage.md b/docs/examples/storage.md
index 4739b1b..3dd0084 100644
--- a/docs/examples/storage.md
+++ b/docs/examples/storage.md
@@ -1,4 +1,4 @@
-# Storage Operator Usage
+# Storage Usage
In this example, you will learn how to use the Storage.
@@ -108,7 +108,7 @@ NAME INSTANCES RUNNING ADDRESS
sample 1 1 sample-oap.default
```
-3. Check whether the pod generated by OAP server is running normally
+3. Check whether the pod generated by OAP server is running correctly.
```shell
$ kubectl get pod -l app=oap
diff --git a/docs/menu.yml b/docs/menu.yml
new file mode 100644
index 0000000..5a84755
--- /dev/null
+++ b/docs/menu.yml
@@ -0,0 +1,52 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+catalog:
+ - name: "Welcome"
+ path: "/readme"
+ - name: "Designs"
+ catalog:
+ - name: "Proposal"
+ path: "/design/proposal"
+ - name: "Setup"
+ catalog:
+ - name: "Java Agent Injector"
+ path: "/java-agent-injector"
+ - name: "Operator"
+ path: "/operator"
+ - name: "Adapter"
+ path: "/custom-metrics-adapter"
+ - name: "Examples"
+ catalog:
+ - name: "Inject Java Agent"
+ path: "/examples/java-agent-injector-usage"
+ - name: "Deploy OAP and UI"
+ path: "/examples/default-backend"
+ - name: "Deploy Storage"
+ path: "/examples/storage"
+ - name: "Fetch metrics"
+ path: "/examples/istio-controlplane"
+ - name: "Contributing Guides"
+ catalog:
+ - name: "Contribute"
+ path: "https://skywalking.apache.org/docs/main/latest/en/guides/readme/"
+ - name: "Become A Committer"
+ path: "https://skywalking.apache.org/docs/main/latest/en/guides/asf/committer/"
+ - name: "Release Guide"
+ path: "/release"
+ - name: "Changelog"
+ path: "https://github.com/apache/skywalking-swck/tree/master/changes"
diff --git a/docs/operator.md b/docs/operator.md
index 55c11eb..e6ca703 100644
--- a/docs/operator.md
+++ b/docs/operator.md
@@ -1,5 +1,6 @@
-# Guides of Operator Deployment
-## Use kustomize to customise your deployment
+# Operator Usage Guide
+## Guides of Operator Deployment
+### Use kustomize to customise your deployment
1. Clone the source code:
@@ -22,7 +23,7 @@ make operator-deploy
make operator-install
```
-## Test your deployment
+### Test your deployment
1. Deploy a sample OAP server, this will create an OAP server in the default namespace:
@@ -42,7 +43,7 @@ kubectl get oapserver
kubectl get ui
```
-## Troubleshooting
+### Troubleshooting
If you encounter any issue, you can check the log of the controller by pulling it from Kubernetes:
@@ -54,29 +55,53 @@ kubectl --namespace skywalking-swck-system get pods
kubectl --namespace skywalking-swck-system logs -f [name_of_the_controller_pod]
```
-## Storage Operator Introduction
-
-The Storage Operator can manage and monitor storage pods(ES, MySQL, and etc.).
-We provide external and internal configuration methods to deploy Storage.
-When you deployment the Storage,you also need to specify the Storage Name in the OAP server configuration。
-
-### Storage Configuration
-
-| Field Name | Description |
-| ------------------ | ------------------------------------------------------------ |
-| type | specify the database type(elasticsearch7,mysql,and etc.).|
-| connectType | specify how to connect to storage(use external or internal).|
-| address | specify connection address of database(when you use an external configuration method,you need to set).|
-| version | specify the version of storage.|
-| image | specify the docker image name of database.|
-| instances | specify the number of storage instance.|
-| security | set oapserver and storage secure connection configuration.|
-| security.user.secretName | enable the user authentication of the storage connection,you need to configure the user name and password in the secret,and specify the secret name here.if you specify the secret name as default,this will use the default username(elastic) and password(changeme).|
-| security.tls | enable the tls authentication of the storage connection,you can set true or false to indicate whether the authentication is open.|
-
## Custom manifests templates
If you want to custom the manifests templates to generate dedicated Kubernetes resources,
please edit YAMLs in `pkg/operator/manifests`.
After saving your changes, issue `make update-templates` to transfer them to binary assets.
The last step is to rebuild `operator` by `make operator-docker-build`.
+
+
+## Custom Resource Define(CRD)
+
+The custom resources that the operator introduced are:
+
+### JavaAgent
+
+The `JavaAgent` custom resource definition (CRD) declaratively defines a view to tracing the injection result.
+The [java-agent-injector](java-agent-injector.md) creat JavaAgents once it injects agents into some workloads.
+Refer to [Java Agent](./javaagent.md) for more details.
+
+### OAP
+
+The `OAP` custom resource definition (CRD) declaratively defines a desired OAP setup to run in a Kubernetes cluster.
+It provides options to configure environment variables and how to connect a `Storage`.
+
+### UI
+
+The `UI` custom resource definition (CRD) declaratively defines a desired UI setup to run in a Kubernetes cluster.
+It provides options for how to connect an `OAP`.
+
+### Storage
+
+The `Storage` custom resource definition (CRD) declaratively defines a desired storage setup to run in a Kubernetes cluster.
+The `Storage` could be managed instances onboarded by the operator or an external service. The `OAP` has options to select
+which `Storage` it would connect.
+
+> Caveat: `Stroage` only supports the `Elasticsearch`.
+
+### Fetcher
+
+The `Fetcher` custom resource definition (CRD) declaratively defines a desired Fetcher setup to run in a Kubernetes cluster.
+It provides options to configure OpenTelemetry collector, which fetches metrics to the deployed `OAP`.
+
+
+## Examples of the Operator
+
+There are some instant examples to represent the functions or features of the Operator.
+
+- [Deploy OAP server and UI with default settings](./examples/default-backend.md)
+- [Fetch metrics from the Istio control plane(istiod)](./examples/istio-controlplane.md)
+- [Inject the java agent to pods](./examples/java-agent-injector-usage.md)
+- [Deploy a storage](./examples/storage.md)
\ No newline at end of file