You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by ke...@apache.org on 2021/11/10 04:24:31 UTC
[skywalking-showcase] 01/01: Add documentation for website
This is an automated email from the ASF dual-hosted git repository.
kezhenxu94 pushed a commit to branch doc
in repository https://gitbox.apache.org/repos/asf/skywalking-showcase.git
commit b1fb5b65559f3db27c8cad8db0b88197534c60e1
Author: kezhenxu94 <ke...@apache.org>
AuthorDate: Wed Nov 10 12:24:16 2021 +0800
Add documentation for website
---
README.md | 4 +-
deploy/platform/kubernetes/features.mk | 2 +-
docs/menu.yml | 20 +++++++
docs/readme.md | 101 +++++++++++++++++++++++++++++++++
4 files changed, 124 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index 9f7f30b..e2d5ba6 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,9 @@
[](https://twitter.com/AsfSkyWalking)
-# Usage
+# Documentations
-Run `make help` to get help.
+Please read the documentation in [our official website](https://skywalking.apache.org/).
# Code of conduct
diff --git a/deploy/platform/kubernetes/features.mk b/deploy/platform/kubernetes/features.mk
index a18ad82..a9f29e8 100644
--- a/deploy/platform/kubernetes/features.mk
+++ b/deploy/platform/kubernetes/features.mk
@@ -28,7 +28,7 @@ endif
.PHONY: istio
istio:
- istioctl install -y --set profile=demo \
+ @istioctl install -y --set profile=demo \
--set meshConfig.enableEnvoyAccessLogService=true `# @feature: als; enable Envoy access log service` \
--set meshConfig.defaultConfig.envoyAccessLogService.address=oap.$(NAMESPACE):11800 `# @feature: als; set ALS address to OAP so Envoy emits logs to OAP`
diff --git a/docs/menu.yml b/docs/menu.yml
new file mode 100644
index 0000000..7874b90
--- /dev/null
+++ b/docs/menu.yml
@@ -0,0 +1,20 @@
+# 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: "SkyWalking showcase"
+ path: "/readme"
diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 0000000..b0d9fcb
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,101 @@
+# SkyWalking showcase
+
+This showcase repository includes an example music application and other manifests to demonstrate the main features of
+SkyWalking. The music application is composed of several microservices that are written in different programming
+languages. Here is the architecture:
+
+```mermaid
+%% please read this doc in our official website, otherwise the graph is not correctly rendered.
+graph LR;
+ loadgen[load generator] --> ui("UI (React)") --> app("app server (NodeJS)") --> gateway("gateway (Spring)");
+ gateway --> songs("songs (Spring)") & rcmd("recommendations (Python)");
+ rcmd --> songs;
+ songs --> db("database (H2)");
+```
+
+## Usage
+
+The showcase uses [GNU Make](https://www.gnu.org/software/make/) and Docker containers to run commands, so please make
+sure you have `make` installed and Docker daemon running.
+
+### Customization
+
+The variables defined in [`Makefile.in`](../Makefile.in) can be overridden to customize the showcase, by specifying an
+environment variable with the same name, e.g.:
+
+```shell
+export ES_VERSION=7.14.0
+make <target>
+```
+
+or directly specifying in the `make` command, e.g.: `make <target> ES_VERSION=7.14.0`.
+
+Run `make help` to get more information.
+
+### Features
+
+The showcase is composed of a set of scenarios with feature flags, you can deploy some of them that interest you by
+overriding the `FEATURE_FLAGS` variable defined in [`Makefile.in`](../Makefile.in), as documented
+in [Customization](#customization), e.g.:
+
+```shell
+make deploy.kubernetes FEATURE_FLAGS=single-node,agent
+```
+
+Feature flags for different platforms ([Kubernetes](#kubernetes) and [Docker Compose](#docker-compose)) are not
+necessarily the same so make sure to specify the right feature flags.
+
+Currently, the features supported are:
+
+| Name | Description | Note |
+| ----------- | ----------- | ----------- |
+| `agent` | Deploy microservices with SkyWalking agent enabled. | The microservices include agents for Java, NodeJS server, browser, Python. |
+| `cluster` | Deploy SkyWalking OAP in cluster mode, with 2 nodes, and SkyWalking RocketBot UI, ElasticSearch as storage. | Only one of `cluster` or `single-node` can be enabled. |
+| `single-node` | Deploy only one single node of SkyWalking OAP, and SkyWalking RocketBot UI, ElasticSearch as storage. | Only one of `cluster` or `single-node` can be enabled. |
+| `so11y` | Enable SkyWalking self observability. | This is enabled by default for platform [Docker Compose](#docker-compose). |
+| `vm` | Start 2 virtual machines and export their metrics to SkyWalking. | The "virtual machines" are mimicked by Docker containers or Pods. |
+| `als` | Start microservices **
+WITHOUT** SkyWalking agent enabled, and configure SkyWalking to analyze the topology and metrics from their access logs. | Command `istioctl` is required to run this feature. The agentless microservices will be running at namespace `${NAMESPACE}-agentless` |
+
+### Kubernetes
+
+To deploy the example application in Kubernetes, please make sure that you have `kubectl` command available, and it can
+connect to the Kubernetes cluster successfully.
+
+If you don't have a running cluster, you can also leverage [KinD (Kubernetes in Docker)](https://kind.sigs.k8s.io)
+or [minikube](https://minikube.sigs.k8s.io) to create a cluster.
+
+Run `kubectl get nodes` to check the connectivity before going to next step. The typical error message that indicates
+your `kubectl` cannot connect to a cluster is:
+
+```text
+The connection to the server localhost:8080 was refused - did you specify the right host or port?
+```
+
+#### Deploy
+
+```shell
+# Set the features that you want to deploy
+export FEATURE_FLAGS=cluster,agent,vm,so11y
+# Deploy
+make deploy.kubernetes
+# Undeploy
+make undeploy.kubernetes
+# Redeploy
+make redeploy.kubernetes # equivalent to make undeploy.kubernetes deploy.kubernetes
+```
+
+### Docker Compose
+
+#### Deploy
+
+```shell
+# Set the features that you want to deploy
+export FEATURE_FLAGS=cluster,agent,vm,so11y
+# Deploy
+make deploy.docker
+# Undeploy
+make undeploy.docker
+# Redeploy
+make redeploy.docker # equivalent to make undeploy.docker deploy.docker
+```