Skip to content

Commit 87eefb4

Browse files
soyeric128soyeric128
authored
docs: benddeploy overview & install guide & getting started (#1937)
* updates * Update index.md * Update 01-installing-benddeploy.md * Update 01-installing-benddeploy.md * Update 01-installing-benddeploy.md * Update 01-installing-benddeploy.md * Update 01-installing-benddeploy.md * Create 02-getting-started.md * Update 01-installing-benddeploy.md
1 parent ce0a9e4 commit 87eefb4

File tree

5 files changed

+332
-0
lines changed

5 files changed

+332
-0
lines changed

‎docs/en/guides/10-deploy/01-deploy/03-benddeploy/01-installing-benddeploy.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
---
2+
title: Installing BendDeploy
3+
---
4+
5+
This guide walks you through deploying BendDeploy and its optional Logging component using [k3d](https://k3d.io/), [Helm](https://helm.sh/), and [kubectl](https://kubernetes.io/docs/tasks/tools/) in a Kubernetes environment.
6+
7+
## Prerequisites
8+
9+
Before you begin, make sure the following tools are installed:
10+
11+
- **S3 Bucket**: Used to store logs collected from BendDeploy. This guide uses an Amazon S3 bucket named `databend-doc` in the `us-east-2` region as an example, but you can use any S3-compatible storage. Make sure you have the appropriate Access Key ID and Secret Access Key.
12+
- **k3d**: This guide uses k3d to create a local Kubernetes cluster for testing and development. k3d runs lightweight K3s clusters inside Docker containers, making it easy to get started quickly. However, you can use any Kubernetes environment that fits your needs. Install it from [k3d.io](https://k3d.io/stable/).
13+
- **kubectl**: Needed to manage and interact with the Kubernetes cluster. Installation instructions are available in the [official Kubernetes docs](https://kubernetes.io/docs/tasks/tools/).
14+
- **Helm**: Required for installing BendDeploy and the optional logging component as Helm charts. It simplifies the deployment process and handles configuration for you. Install Helm from [helm.sh](https://helm.sh/docs/intro/install/).
15+
16+
## Step 1: Create the Kubernetes Cluster
17+
18+
To begin, you’ll need a Kubernetes environment to run BendDeploy and its logging components.
19+
20+
1. Create a local cluster named `benddeploy-tutorial`:
21+
22+
```bash
23+
k3d cluster create benddeploy-tutorial
24+
```
25+
26+
You’ll see output showing the steps as the cluster is being set up. Once it completes, your cluster is ready:
27+
28+
```bash
29+
INFO[0000] Prep: Network
30+
INFO[0000] Created network 'k3d-benddeploy-tutorial'
31+
INFO[0000] Created image volume k3d-benddeploy-tutorial-images
32+
INFO[0000] Starting new tools node...
33+
INFO[0000] Starting node 'k3d-benddeploy-tutorial-tools'
34+
INFO[0001] Creating node 'k3d-benddeploy-tutorial-server-0'
35+
INFO[0001] Creating LoadBalancer 'k3d-benddeploy-tutorial-serverlb'
36+
INFO[0001] Using the k3d-tools node to gather environment information
37+
INFO[0001] Starting new tools node...
38+
INFO[0001] Starting node 'k3d-benddeploy-tutorial-tools'
39+
INFO[0002] Starting cluster 'benddeploy-tutorial'
40+
INFO[0002] Starting servers...
41+
INFO[0002] Starting node 'k3d-benddeploy-tutorial-server-0'
42+
INFO[0005] All agents already running.
43+
INFO[0005] Starting helpers...
44+
INFO[0005] Starting node 'k3d-benddeploy-tutorial-serverlb'
45+
INFO[0011] Injecting records for hostAliases (incl. host.k3d.internal) and for 3 network members into CoreDNS configmap...
46+
INFO[0013] Cluster 'benddeploy-tutorial' created successfully!
47+
INFO[0013] You can now use it like this:
48+
kubectl cluster-info
49+
➜ ~ k3d cluster list
50+
51+
NAME SERVERS AGENTS LOADBALANCER
52+
benddeploy-tutorial 1/1 0/0 true
53+
```
54+
55+
2. Verify the Kubernetes node is up and running:
56+
57+
```bash
58+
kubectl get nodes
59+
```
60+
61+
You should see the control plane node in the `Ready` state:
62+
63+
```bash
64+
NAME STATUS ROLES AGE VERSION
65+
k3d-benddeploy-tutorial-server-0 Ready control-plane,master 7m35s v1.31.5+k3s1
66+
```
67+
68+
3. Install Prometheus CRDs. Before continuing, make sure your cluster has the required Prometheus Operator CRDs, especially ServiceMonitor.
69+
70+
```bash
71+
kubectl apply -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/main/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml
72+
```
73+
74+
4. Clone the BendDeploy Helm charts repository:
75+
76+
```bash
77+
git clone https://github.com/databendcloud/benddeploy-charts.git
78+
cd benddeploy-charts/charts/logging
79+
```
80+
81+
## Step 2: Deploy the Logging Components (Optional)
82+
83+
This step is optional but recommended if you want to collect system logs from BendDeploy and store them in S3 for further analysis.
84+
85+
1. Update the **values.yaml** file in the `charts/logging` directory to enable the `warehouseLogCollector` and configure it to use your S3-compatible storage:
86+
87+
```yaml
88+
...
89+
90+
warehouseLogCollector:
91+
enabled: true
92+
replicas: 1
93+
nameOverride: warehouse-log-collector
94+
fullnameOverride: warehouse-log-collector
95+
s3:
96+
endpoint: "https://s3.us-east-2.amazonaws.com"
97+
bucket: "databend-doc"
98+
region: "us-east-2"
99+
auth:
100+
accessKeyId: "<your-access-key-id>"
101+
secretAccessKey: "<your-secret-access-key>"
102+
103+
...
104+
```
105+
106+
2. Edit the **agent.yaml** file located in `configs/vector/` to configure the S3 sink for log storage:
107+
108+
```yaml
109+
...
110+
111+
# S3 sink
112+
s3_logs:
113+
type: aws_s3
114+
inputs:
115+
# - filter_kubernetes_logs
116+
- filter_warehouse_system_logs
117+
endpoint: "https://s3.us-east-2.amazonaws.com"
118+
bucket: "databend-doc"
119+
key_prefix: "logs/{{ tenant }}/system/"
120+
compression: gzip
121+
encoding:
122+
codec: native_json
123+
124+
auth:
125+
access_key_id: "<your-access-key-id>"
126+
secret_access_key: "<your-secret-access-key>"
127+
128+
region: "us-east-2"
129+
130+
...
131+
```
132+
133+
3. Deploy the logging components using Helm:
134+
135+
```bash
136+
helm upgrade --install logging . --namespace=logging --create-namespace
137+
```
138+
139+
On success, Helm will show a message confirming the deployment:
140+
141+
```bash
142+
Release "logging" does not exist. Installing it now.
143+
NAME: logging
144+
LAST DEPLOYED: Sun Apr 20 11:36:46 2025
145+
NAMESPACE: logging
146+
STATUS: deployed
147+
REVISION: 1
148+
TEST SUITE: None
149+
```
150+
151+
4. Verify the logging components are running:
152+
153+
```bash
154+
kubectl get pod -n logging
155+
```
156+
157+
You should see output like:
158+
159+
```bash
160+
NAME READY STATUS RESTARTS AGE
161+
vector-xpshl 1/1 Running 0 6s
162+
warehouse-log-aggregator-0 1/1 Running 0 70m
163+
warehouse-log-collector-0 1/1 Running 0 3s
164+
```
165+
166+
## Step 3: Deploy BendDeploy
167+
168+
Now that your cluster is ready, you can install BendDeploy into the Kubernetes environment.
169+
170+
1. For production deployments, customize the **configmap-benddeploy.yaml** file in the `charts/benddeploy/templates` directory to ensure BendDeploy can properly pull images, store logs, connect to metrics and databases, and authenticate users. If left unchanged, the default settings will be used, which are suitable for testing but not recommended for production use.
171+
172+
| Field | Description |
173+
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
174+
| `imageRegistry` | The image registry for pulling Databend Docker images. If your cluster has no internet access, push the images to your own registry (e.g., `registry.databend.local`). Leave empty to use Docker Hub. |
175+
| `registryUsername` | Username for accessing your image registry, if required. |
176+
| `registryPassword` | Password for accessing your image registry, if required. |
177+
| `repoNamespace` | The namespace under which Databend images are stored. For example, if the image is `registry.databend.local/datafuselabs/databend-query:tag`, the `repoNamespace` is `datafuselabs`. |
178+
| `promEndpoint` | Endpoint of your Prometheus server, e.g., `prometheus-k8s.monitoring.svc.cluster.local:9090`. |
179+
| `logCollectorEndpoint` | Endpoint for your log collector (e.g., Vector or OpenTelemetry), e.g., `http://warehouse-log-collector.logging.svc.cluster.local:4318`. |
180+
| `grafanaEndpoint` | Address of your Grafana dashboard, e.g., `http://grafana.monitoring.svc.cluster.local:80`. |
181+
| `db.postgresDSN` | DSN for an external PostgreSQL database. |
182+
| `oidcProvider` | OIDC provider URL for authentication. Must be accessible from within the cluster or exposed via Ingress. |
183+
184+
2. Install BendDeploy using Helm from the root of the cloned repository. Visit the [BendDeploy image repository on Amazon ECR Public Gallery](https://gallery.ecr.aws/databendlabs/benddeploy) and check the **Image tags** section to find the latest version, such as `v1.0.2`.
185+
186+
```bash
187+
# Replace <version> with the latest release version:
188+
helm install benddeploy -n benddeploy --create-namespace ./charts/benddeploy --set image=public.ecr.aws/databendlabs/benddeploy:<version>
189+
```
190+
191+
Helm will confirm the deployment:
192+
193+
```bash
194+
NAME: benddeploy
195+
LAST DEPLOYED: Sun Apr 20 12:44:44 2025
196+
NAMESPACE: benddeploy
197+
STATUS: deployed
198+
REVISION: 1
199+
TEST SUITE: None
200+
➜ benddeploy-charts git:(main) ✗
201+
```
202+
203+
3. Verify BendDeploy pods are running:
204+
205+
```bash
206+
kubectl get pod -n benddeploy
207+
```
208+
209+
Expected output:
210+
211+
```bash
212+
NAME READY STATUS RESTARTS AGE
213+
benddeploy-cfdd898d5-pkfwd 1/1 Running 0 69s
214+
benddeploy-frontend-6988fdc5b9-blt2n 1/1 Running 0 69s
215+
pg-benddeploy-64c64b95c-wd55m 1/1 Running 0 69s
216+
```
217+
218+
## Step 4: Access the Web Interface
219+
220+
With the deployment complete, you can now access the BendDeploy web UI in your browser.
221+
222+
1. Expose the frontend via port forwarding.
223+
224+
:::tip
225+
While port forwarding is great for quick local access, for production or shared environments, consider configuring an Ingress controller (like NGINX Ingress) or exposing the service via a LoadBalancer to make BendDeploy accessible from outside the cluster. This allows you to access the web UI through a real domain or IP address.
226+
:::
227+
228+
First, check the service:
229+
230+
```bash
231+
kubectl get svc -n benddeploy
232+
```
233+
234+
```bash
235+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
236+
benddeploy-service ClusterIP 10.43.74.161 <none> 8080/TCP 9m23s
237+
frontend-service ClusterIP 10.43.70.22 <none> 8080/TCP 9m23s
238+
pg-benddeploy ClusterIP 10.43.38.197 <none> 5432/TCP 9m23s
239+
```
240+
241+
Then forward the frontend service to your local machine:
242+
243+
```bash
244+
kubectl port-forward -n benddeploy svc/frontend-service 8080:8080
245+
```
246+
247+
You’ll see:
248+
249+
```bash
250+
Forwarding from 127.0.0.1:8080 -> 8080
251+
Forwarding from [::1]:8080 -> 8080
252+
```
253+
254+
2. Navigate to [http://localhost:8080](http://localhost:8080) to access BendDeploy using the default credentials (Username: `databend`, Password: `Databend@1*`).
255+
256+
![alt text](@site/static/img/documents/benddeploy/login.png)

‎docs/en/guides/10-deploy/01-deploy/03-benddeploy/02-getting-started.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Getting Started with BendDeploy
3+
---
4+
5+
This guide walks you through setting up a Databend deployment with BendDeploy — from configuring the system meta to creating tenants and warehouses.
6+
7+
## Before You Start
8+
9+
Before proceeding, ensure that BendDeploy is properly installed and that you're logged in to your environment. For setup instructions, refer to [Installing BendDeploy](01-installing-benddeploy.md).
10+
11+
## Step 1: Create a System Meta
12+
13+
1. In the left navigation pane, click **System Meta**, then click **Create Meta** on the right.
14+
2. Choose the desired `databend-meta` image version, set the replica count, and configure the CPU limit.
15+
3. (Optional) If you have persistent storage available, toggle the **Enabled** switch and specify the size, storage class, and mount path.
16+
4. Click **Create** to deploy the System Meta service.
17+
18+
## Step 2: Create a Tenant
19+
20+
1. In the left navigation pane, click **Tenant**, then click **Create Tenant** on the right.
21+
2. Enter a name for the tenant, then click **Next**.
22+
3. Select **I have a system meta**, confirm that the previously created meta instance is listed below, then click **Next** to proceed.
23+
4. Specify the object storage configuration for your tenant, then click **Next** to proceed.
24+
5. Create a SQL user by specifying a username and password, then click **Next** to proceed.
25+
6. Specify the ingress domain, such as `*.example.domain`, to define the domain through which your tenant will be accessible externally, then click **Next** to proceed.
26+
7. (Optional) If you have a license for Databend Enterprise, enter your license, then click **Create**.
27+
28+
## Step 3: Create a Warehouse
29+
30+
1. In the left navigation pane, click **Tenant**, then click on the tenant you have created.
31+
2. click **Create Warehouse**.
32+
3. On the page that opens, specify the warehouse name, `databend-query` image version, and configure the CPU limit.
33+
4. Click **Confirm** to start creating the warehouse.
34+
35+
## Step 4: (Optional) Enable Logging
36+
37+
If you have installed the logging components, you can enable the logging feature for your tenant. Please note that, once logging is enabled for a tenant, a warehouse is automatically created for log collection.
38+
39+
1. In the left navigation pane, click **Logs**, then click **Enable Logs** on the right.
40+
2. Specify the tenant you want to enable logging for, user credentials, and the log storage bucket.
41+
3. Click **OK**.

‎docs/en/guides/10-deploy/01-deploy/03-benddeploy/_category_.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"label": "BendDeploy"
3+
}

‎docs/en/guides/10-deploy/01-deploy/03-benddeploy/index.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: BendDeploy
3+
---
4+
5+
import IndexOverviewList from '@site/src/components/IndexOverviewList';
6+
7+
BendDeploy is a Kubernetes-based platform developed by Databend to simplify and standardize the deployment and management of Databend clusters. It provides a visual, user-friendly interface for multi-cluster, multi-tenant operations, significantly improving operational efficiency, reliability, and control.
8+
9+
- Multi-Tenant Management: Isolated tenant environments with role-based user access controls.
10+
- One-Click Cluster Deployment: Easily launch and manage Databend clusters with a few clicks.
11+
- Lifecycle Operations: Supports rolling upgrades, version rollbacks, horizontal scaling, and cluster restarts.
12+
- Visual Monitoring & Logs: Integrated views for node status, logs (e.g., query/profile logs), and external Prometheus metrics.
13+
- Web-Based SQL Worksheet: Execute SQL queries directly from the UI, targeting specific tenant clusters.
14+
15+
## Downloading BendDeploy
16+
17+
BendDeploy is distributed as a set of Helm charts, making it easy to deploy on any Kubernetes environment. You can find the official charts repository on GitHub: [https://github.com/databendcloud/benddeploy-charts](https://github.com/databendcloud/benddeploy-charts).
18+
19+
The charts are organized into two main components:
20+
21+
- **BendDeploy Helm Chart**: The core chart that installs the BendDeploy control panel, backend services, and related components required to manage Databend clusters and tenants. This chart is required.
22+
- **BendDeploy Logging Helm Chart**: An optional chart that enables centralized log collection from Databend query nodes using tools like Vector. It provides a convenient way to view logs such as query logs and profile logs directly in the BendDeploy interface.
23+
24+
## Licensing BendDeploy
25+
26+
BendDeploy is free to use for a 6-month trial period after installation. Once the trial expires, you can contact the Databend team to purchase a permanent license and continue using the platform without interruption.
27+
28+
For license inquiries or support, please reach out to: [[email protected]](mailto:[email protected])
29+
30+
## Getting Started with BendDeploy
31+
32+
<IndexOverviewList />

‎static/img/documents/benddeploy/login.png‎

280 KB
Loading

0 commit comments

Comments
 (0)