From 5a9905d8f625ad1e82f63cf893f0a695f1080318 Mon Sep 17 00:00:00 2001 From: wankai123 Date: Tue, 23 Jul 2024 10:02:01 +0800 Subject: [PATCH 1/3] Introduce new doc menu structure. --- docs/guides/quick-start/docker-compose.yaml | 154 ++++++++++++++++++++ docs/guides/quick-start/quick-start.md | 9 ++ docs/installation/docker.md | 24 +++ docs/installation/kubernetes.md | 70 +++++++++ docs/menu.yml | 120 ++++++++++----- 5 files changed, 343 insertions(+), 34 deletions(-) create mode 100644 docs/guides/quick-start/docker-compose.yaml create mode 100644 docs/guides/quick-start/quick-start.md create mode 100644 docs/installation/docker.md create mode 100644 docs/installation/kubernetes.md diff --git a/docs/guides/quick-start/docker-compose.yaml b/docs/guides/quick-start/docker-compose.yaml new file mode 100644 index 000000000..d765c9f1e --- /dev/null +++ b/docs/guides/quick-start/docker-compose.yaml @@ -0,0 +1,154 @@ +# 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. + +services: + banyandb: + image: ${BANYANDB_IMAGE:-apache/skywalking-banyandb:latest} + container_name: banyandb + command: standalone + expose: + - 17912 + ports: + - 17913:17913 + networks: + - demo + healthcheck: + test: [ "CMD", "./bydbctl", "health", "--config=-", "--addr=http://banyandb:17913" ] + interval: 30s + timeout: 30s + retries: 120 + + oap: + image: ${OAP_IMAGE:-apache/skywalking-oap-server:latest} + environment: + SW_STORAGE: banyandb + SW_STORAGE_BANYANDB_TARGETS: banyandb:17912 + expose: + - 11800 + ports: + - 12800:12800 + networks: + - demo + depends_on: + banyandb: + condition: service_healthy + healthcheck: + test: ["CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/11800"] + interval: 5s + timeout: 60s + retries: 120 + + oap-ui: + image: ${OAP_UI_IMAGE:-apache/skywalking-ui:latest} + ports: + - 8080:8080 + environment: + - SW_OAP_ADDRESS=http://oap:12800 + networks: + - demo + depends_on: + oap: + condition: service_healthy + + agent: + image: ${AGENT_IMAGE:-apache/skywalking-java-agent:9.2.0-java11} + command: cp -r /skywalking/agent/ /skywalking-java-agent/ + volumes: + - sw_agent:/skywalking-java-agent + networks: + - demo + + provider: + image: "ghcr.io/apache/skywalking/e2e-service-provider:cc7a2c9e97fd2c421adbe3e9c471688459a446d9" + volumes: + - sw_agent:/sw-java-agent + environment: + JAVA_TOOL_OPTIONS: -javaagent:/sw-java-agent/agent/skywalking-agent.jar + SW_AGENT_COLLECTOR_BACKEND_SERVICES: oap:11800 + SW_LOGGING_OUTPUT: CONSOLE + SW_AGENT_NAME: e2e-service-provider + SW_AGENT_INSTANCE_NAME: provider1 + SW_AGENT_COLLECTOR_GET_PROFILE_TASK_INTERVAL: 1 + SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL: 1 + ports: + - 9090 + networks: + - demo + depends_on: + oap: + condition: service_healthy + agent: + condition: service_completed_successfully + healthcheck: + test: [ "CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/9090" ] + interval: 5s + timeout: 60s + retries: 120 + + consumer: + image: "ghcr.io/apache/skywalking/e2e-service-consumer:cc7a2c9e97fd2c421adbe3e9c471688459a446d9" + volumes: + - sw_agent:/sw-java-agent + environment: + JAVA_TOOL_OPTIONS: -javaagent:/sw-java-agent/agent/skywalking-agent.jar + SW_AGENT_COLLECTOR_BACKEND_SERVICES: oap:11800 + SW_LOGGING_OUTPUT: CONSOLE + PROVIDER_URL: http://provider:9090 + SW_AGENT_NAME: e2e-service-consumer + SW_AGENT_INSTANCE_NAME: consumer1 + SW_AGENT_COLLECTOR_GET_PROFILE_TASK_INTERVAL: 1 + SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL: 1 + ports: + - 9092 + networks: + - demo + depends_on: + oap: + condition: service_healthy + provider: + condition: service_healthy + agent: + condition: service_completed_successfully + healthcheck: + test: [ "CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/9092" ] + interval: 5s + timeout: 60s + retries: 120 + + traffic_loader: + image: curlimages/curl + networks: + - demo + depends_on: + oap: + condition: service_healthy + provider: + condition: service_healthy + consumer: + condition: service_healthy + entrypoint: > + sh -c " + echo 'Starting traffic generation...'; + while true; do + curl -X POST http://consumer:9092/info; + sleep 1; + done + " + +networks: + demo: + +volumes: + sw_agent: {} diff --git a/docs/guides/quick-start/quick-start.md b/docs/guides/quick-start/quick-start.md new file mode 100644 index 000000000..36029796c --- /dev/null +++ b/docs/guides/quick-start/quick-start.md @@ -0,0 +1,9 @@ +# Quick Start Tutorial + +## Set up a cluster with OAP and BanyanDB with docker-compose + +```shell +docker compose -f ./docker-compose.yaml --project-name=banyandb-quickstart up -d +``` + +## todo... diff --git a/docs/installation/docker.md b/docs/installation/docker.md new file mode 100644 index 000000000..6e5a4bb4d --- /dev/null +++ b/docs/installation/docker.md @@ -0,0 +1,24 @@ +# Installation On Docker + +## Start a container in `standalone mode` +The following commands pull the docker image and run the BanyanDB on Docker. Replace `latest` with the version of the BanyanDB you want to run. +- pull the image +```shell +docker pull apache/skywalking-banyandb:latest +``` +- run the container +```shell +docker run -d \ + -p 17912:17912 \ + -p 17913:17913 \ + --name banyandb \ + apache/skywalking-banyandb:latest \ + standalone +``` + +The BanyanDB server would be listening on the `0.0.0.0:17912` to access gRPC requests. if no errors occurred. + +At the same time, the BanyanDB server would be listening on the `0.0.0.0:17913` to access HTTP requests. if no errors occurred. The HTTP server is used for CLI and Web UI. + +The Web UI is hosted at `http://localhost:17913/`. + diff --git a/docs/installation/kubernetes.md b/docs/installation/kubernetes.md new file mode 100644 index 000000000..9817118f4 --- /dev/null +++ b/docs/installation/kubernetes.md @@ -0,0 +1,70 @@ +# Installation On Kubernetes + +To install BanyanDB on Kubernetes, you can use our Helm chart, which simplifies the deployment process. You can find detailed installation instructions in [our official documentation](https://github.com/apache/skywalking-helm/tree/master). + +This step-by-step guide assumes you have a basic understanding of Kubernetes and Helm, the package manager for Kubernetes. If you're new to Helm, you might want to familiarize yourself with Helm basics before proceeding. + +## Prerequisites + +Before we begin, ensure you have the following: + +1. **A Kubernetes Cluster**: You can use Minikube for a local setup, or any cloud provider like AWS, GCP, or Azure that supports Kubernetes. +2. **Helm 3**: Ensure Helm 3 is installed and configured on your machine. You can download it from [Helm's official website](https://helm.sh/). + +## Step 1: Configure Helm to Use OCI + +Since the BanyanDB Helm chart is hosted as an OCI chart in Docker Hub, you need to ensure your Helm is configured to handle OCI artifacts. + +```shell +helm registry login registry-1.docker.io +``` + +You will be prompted to enter your Docker Hub username and password. This step is necessary to pull Helm charts from Docker Hub. + +## Step 2: Install BanyanDB Using Helm + +- Create a namespace for BanyanDB: +```shell +kubectl create ns sw +``` + +- Install BanyanDB using the following Helm command: +```shell +helm install banyandb \ + oci://registry-1.docker.io/apache/skywalking-banyandb-helm \ + --version 0.2.0 \ + --set image.tag=0.6.1 \ + -n sw +``` +This command installs the BanyanDB Helm chart with the specified version and image tag in the `sw` namespace in `cluster mode`. +You can customize the installation by setting additional values in the `--set` flag. + +- Wait for the installation to complete. You can check the status of the pods using the following command: +```shell +kubectl get pod -n sw -w +``` +```shell +NAME READY STATUS RESTARTS AGE +banyandb-0 1/1 Running 3 (6m38s ago) 7m7s +banyandb-1 1/1 Running 0 5m6s +banyandb-2 1/1 Running 0 4m6s +banyandb-885bc59d4-669lh 1/1 Running 3 (6m35s ago) 7m7s +banyandb-885bc59d4-dd4j7 1/1 Running 3 (6m36s ago) 7m7s +banyandb-etcd-0 1/1 Running 0 7m7s +``` + +- You can check the services using the following command: +```shell +kubectl get svc -n sw +``` +```shell +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +banyandb-etcd ClusterIP 10.96.33.132 2379/TCP,2380/TCP 5m +banyandb-etcd-headless ClusterIP None 2379/TCP,2380/TCP 5m +banyandb-grpc ClusterIP 10.96.152.152 17912/TCP 5m +banyandb-http LoadBalancer 10.96.137.29 17913:30899/TCP 5m +``` +The BanyanDB server would be listening on the `0.0.0.0:17912` to access gRPC requests. if no errors occurred. + +At the same time, the BanyanDB server would be listening on the `0.0.0.0:17913` to access HTTP requests. if no errors occurred. The HTTP server is used for CLI and Web UI. + diff --git a/docs/menu.yml b/docs/menu.yml index 8e081587c..ff72c0db7 100644 --- a/docs/menu.yml +++ b/docs/menu.yml @@ -18,14 +18,92 @@ catalog: - name: "Welcome" path: "/readme" - - name: "Installation" + - name: "User Guide" catalog: - - name: "Get Binaries" - path: "/installation/binaries" - - name: "Standalone Mode" - path: "/installation/standalone" - - name: "Cluster Mode" - path: "/installation/cluster" + - name: "Installation" + catalog: + - name: "Get Binaries" + path: "/installation/binaries" + - name: "Standalone Mode" + path: "/installation/standalone" + - name: "Cluster Mode" + path: "/installation/cluster" + - name: "Installation On Docker" + path: "/installation/docker" + - name: "Installation On Kubernetes" + path: "/installation/kubernetes" + - name: "Basic Concepts and Terminology" + catalog: + - name: "Data Model" + path: "/concept/data-model" + - name: "Clustering" + path: "/concept/clustering" + - name: "TSDB" + path: "/concept/tsdb" + - name: "Quick Start Tutorial" + path: "/guides/quick-start" + - name: "Interacting" + catalog: + - name: "Clients" + path: "/clients" + - name: "Insert and Update Data" + path: "" + - name: "Querying Data" + path: "" + - name: "Deleting Data" + path: "" + - name: "Operation and Maintenance" + catalog: + - name: "Configure BanyanDB" + path: "" + - name: "System Configuration" + path: "" + - name: "Upgrade" + catalog: + - name: "Server and File Versioning" + path: "" + - name: "Upgrade" + path: "" + - name: "Rollback" + path: "" + - name: "Observability" + path: "/observability" + - name: "Cluster Management" + path: "" + - name: "Security" + catalog: + - name: "TLS Configuration" + path: "" + - name: "Troubleshooting" + path: "" + - name: "Security" + path: "" + - name: "File Format" + catalog: + - name: "v1.1.0" + path: "" +# - name: "CRUD Operations" +# catalog: +# - name: "Group" +# path: "/crud/group" +# - name: "Measure" +# catalog: +# - name: "Schema" +# path: "/crud/measure/schema" +# - name: "Query" +# path: "/crud/measure/query" +# - name: "Stream" +# catalog: +# - name: "Schema" +# path: "/crud/stream/schema" +# - name: "Query" +# path: "/crud/stream/query" +# - name: "IndexRule" +# path: "/crud/index_rule" +# - name: "IndexRuleBinding" +# path: "/crud/index_rule_binding" +# - name: "Property" +# path: "/crud/property" - name: "Concepts" catalog: - name: "Data Model" @@ -33,30 +111,4 @@ catalog: - name: "Clustering" path: "/concept/clustering" - name: "TSDB" - path: "/concept/tsdb" - - name: "CRUD Operations" - catalog: - - name: "Group" - path: "/crud/group" - - name: "Measure" - catalog: - - name: "Schema" - path: "/crud/measure/schema" - - name: "Query" - path: "/crud/measure/query" - - name: "Stream" - catalog: - - name: "Schema" - path: "/crud/stream/schema" - - name: "Query" - path: "/crud/stream/query" - - name: "IndexRule" - path: "/crud/index_rule" - - name: "IndexRuleBinding" - path: "/crud/index_rule_binding" - - name: "Property" - path: "/crud/property" - - name: "Clients" - path: "/clients" - - name: "Observability" - path: "/observability" \ No newline at end of file + path: "/concept/tsdb" \ No newline at end of file From cbefa8d2f1026e574b48cf921d610a5563e1c171 Mon Sep 17 00:00:00 2001 From: wankai123 Date: Tue, 23 Jul 2024 10:07:28 +0800 Subject: [PATCH 2/3] changes --- CHANGES.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index 58b59f87c..cae863698 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -32,6 +32,9 @@ Release Notes. - Fix a bug that the Stream module didn't support duplicated in index-based filtering and sorting - Fix the bug that segment's reference count is increased twice when the controller try to create an existing segment. +### Documentation +- Introduce new doc menu structure. + ## 0.6.1 ### Features From 124ad467a920e5868f1724c15581daeade58daa6 Mon Sep 17 00:00:00 2001 From: wankai123 Date: Tue, 23 Jul 2024 10:09:09 +0800 Subject: [PATCH 3/3] changes --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index cae863698..baf4a0d70 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -34,6 +34,7 @@ Release Notes. ### Documentation - Introduce new doc menu structure. +- Add installation on Docker and Kubernetes. ## 0.6.1