| # SkyWalking 9.x showcase |
| |
| **This showcase would follow the latest changes of SkyWalking 9.x, even before the official release.** |
| |
| 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)") --> Traffic1("HTTP Request for backend serv") --> apisix("APISIX as UI container") |
| --> app("app server (NodeJS)") --> gateway("gateway (Spring)"); |
| ui("UI (React)") --> Traffic2("HTTP Request for UI codes") --> apisix("APISIX with UI container") |
| gateway --> songs("songs (Spring)") & rcmd("recommendations (Python)"); |
| songs --> activeMQ |
| activeMQ --> songs |
| rcmd --> songs; |
| songs --> db("database (H2)"); |
| ``` |
| |
| ## Usage |
| |
| **Please run the showcase in a brand new test cluster, otherwise the undeploy process may delete |
| some resources that you have installed before running this showcase (for example cert-manager). |
| If you don't do this in a new test cluster, it's all on your own risks!** |
| |
| 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. |
| |
| ### Prerequisites |
| |
| To deploy the full features of this showcase application, you may need up to 4 CPU cores and 4 GB memory, please |
| increase the Docker daemon resources or Kubernetes cluster resources if you find containers / Pods failed to start up. |
| Alternatively, you can also only deploy part of the features that interest you if you don't want to increase the |
| resources, via the guide in [Customization](#customization). |
| |
| ### Quick Start |
| |
| Make sure you have a running Kubernetes cluster and `kubectl` can access to that cluster. |
| |
| ```shell |
| git clone https://github.com/apache/skywalking-showcase.git |
| cd skywalking-showcase |
| make deploy.kubernetes |
| ``` |
| |
| This will install SkyWalking components, including OAP in cluster mode with 2 nodes, SkyWalking UI, |
| microservices with SkyWalking agent, microservices without SkyWalking agent but managed by Istio, |
| 2 Pods to mimic virtual machines and export metrics to SkyWalking, and enable kubernetes cluster monitoring as well as |
| SkyWalking self observability. |
| |
| For more advanced deployments, check [Customization](#customization) documentation below. |
| |
| Notice, when run this showcase locally such as KinD, the images are downloaded inside the KinD, which could take over 10 mins(depend on local network). |
| Rerun `make deploy.kubernetes` if some timeout errors break the process. |
| |
| ### 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 | |
| |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| |
| | `java-agent-injector` | Use the java agent injector to inject the Skywalking Java agent and deploy microservices with other SkyWalking agent enabled. | The microservices include agents for Java, NodeJS server, browser, Python. | |
| | `agent` | Deploy microservices with SkyWalking agent pre-installed. | In Kubernetes sceanarios, please use `java-agent-injector` instead of this, if possible. | |
| | `cluster` | Deploy SkyWalking OAP in cluster mode, with 2 nodes, and SkyWalking UI. | Only one of `cluster` or `single-node` can be enabled. | |
| | `single-node` | Deploy only one single node of SkyWalking OAP, and SkyWalking UI, ElasticSearch as storage. | Only one of `cluster` or `single-node` can be enabled. | |
| | `elasticsearch` | Deploy a single-node ElasticSearch as storage, you may want to disable this if you want to use your own ElasticSearch deployments. | | |
| | `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-monitor` | Deploy OpenTelemetry and export Kubernetes monitoring metrics to SkyWalking for analysis and display on UI. | | |
| | `istiod-monitor` | Deploy OpenTelemetry and export Istio control plane metrics to SkyWalking for analysis and display on UI. | | |
| | `event` | Deploy tools to trigger events, and SkyWalking Kubernetes event exporter to export events into SkyWalking. | | |
| | `satellite` | Deploy SkyWalking Satellite to load balance the monitoring data. | | |
| | `function` | Deploy [OpenFunction](https://openfunction.dev/) and export trace to SkyWalking. | Command [ofn](https://github.com/OpenFunction/cli) is required to run this feature. | |
| | `trace-profiling` | Deploy tools to submit trace profiling tasks. | Only support deployment with SkyWalking agents installed, currently Java agent and Python agent support trace profiling. | |
| | `rover` | Deploy SkyWalking Rover and detect the processes in the Kubernetes environment. | Only support deployment in the Kubernetes environment, docker is not supported. | |
| | `mysql` | Start a MySQL server and load generator to execute the sample SQLs periodically, set up fluent bit to fetch slow logs and export to OAP, and export their metrics to SkyWalking. | | |
| | `postgresql` | Start a PostgreSQL server, and load generator to execute the sample SQLs periodically, set up fluent bit to fetch slow logs and export to OAP, and export their metrics to SkyWalking. | | |
| | `apisix-monitor` | Deploy OpenTelemetry and export APISIX metrics to SkyWalking for analysis and display on UI | | |
| |
| ### 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 |
| # Deploy |
| make deploy.kubernetes |
| # Undeploy |
| make undeploy.kubernetes |
| # Redeploy |
| make redeploy.kubernetes # equivalent to make undeploy.kubernetes deploy.kubernetes |
| ``` |
| |
| ### Docker Compose |
| |
| #### Deploy |
| |
| ```shell |
| # Deploy |
| make deploy.docker |
| # Undeploy |
| make undeploy.docker |
| # Redeploy |
| make redeploy.docker # equivalent to make undeploy.docker deploy.docker |
| ``` |
| |
| ## Traffic Flow |
| |
| After deploy the showcase, the business system would send monitoring traffic to the OAP node, and one agent/sidecar connect to one OAP node directly. |
| |
| ### Satellite |
| If the business traffic is unbalanced, it would cause the OAP node receive unbalanced monitoring data. So, you could add the Satellite component. |
| After deploy the showcase with the satellite component, the monitoring traffic would send to the Satellite service, and satellite |
| load balances the traffic to the OAP nodes. |
| |
| ```mermaid |
| %% please read this doc in our official website, otherwise the graph is not correctly rendered. |
| graph LR; |
| agent["business app(agent)"] --> satellite("satellite") --> oap("oap"); |
| envoy["sidecar(envoy)"] --> satellite; |
| ``` |
