|
| 1 | +```md |
| 2 | +--- |
| 3 | +title: 安装 BendDeploy |
| 4 | +--- |
| 5 | + |
| 6 | +本指南将引导你使用 [k3d](https://k3d.io/)、[Helm](https://helm.sh/) 和 [kubectl](https://kubernetes.io/docs/tasks/tools/) 在 Kubernetes 环境中部署 BendDeploy 及其可选的 Logging 组件。 |
| 7 | + |
| 8 | +## 前提条件 |
| 9 | + |
| 10 | +在开始之前,请确保已安装以下工具: |
| 11 | + |
| 12 | +- **S3 Bucket**: 用于存储从 BendDeploy 收集的日志。本指南使用位于 `us-east-2` 区域中名为 `databend-doc` 的 Amazon S3 bucket 作为示例,但你可以使用任何与 S3 兼容的存储。确保你拥有相应的 Access Key ID 和 Secret Access Key。 |
| 13 | +- **k3d**: 本指南使用 k3d 创建一个本地 Kubernetes 集群,用于测试和开发。k3d 在 Docker 容器内运行轻量级的 K3s 集群,从而可以轻松快速地开始使用。但是,你可以使用任何适合你需求的 Kubernetes 环境。从 [k3d.io](https://k3d.io/stable/) 安装。 |
| 14 | +- **kubectl**: 需要管理 Kubernetes 集群并与之交互。安装说明可在 [官方 Kubernetes 文档](https://kubernetes.io/docs/tasks/tools/) 中找到。 |
| 15 | +- **Helm**: 需要安装 BendDeploy 和可选的 logging 组件作为 Helm charts。它简化了部署过程并为你处理配置。从 [helm.sh](https://helm.sh/docs/intro/install/) 安装 Helm。 |
| 16 | + |
| 17 | +## 步骤 1:创建 Kubernetes 集群 |
| 18 | + |
| 19 | +首先,你需要一个 Kubernetes 环境来运行 BendDeploy 及其 logging 组件。 |
| 20 | + |
| 21 | +1. 创建一个名为 `benddeploy-tutorial` 的本地集群: |
| 22 | + |
| 23 | +```bash |
| 24 | +k3d cluster create benddeploy-tutorial |
| 25 | +``` |
| 26 | + |
| 27 | +你将看到输出显示集群正在设置的步骤。完成后,你的集群已准备就绪: |
| 28 | + |
| 29 | +```bash |
| 30 | +INFO[0000] Prep: Network |
| 31 | +INFO[0000] Created network 'k3d-benddeploy-tutorial' |
| 32 | +INFO[0000] Created image volume k3d-benddeploy-tutorial-images |
| 33 | +INFO[0000] Starting new tools node... |
| 34 | +INFO[0000] Starting node 'k3d-benddeploy-tutorial-tools' |
| 35 | +INFO[0001] Creating node 'k3d-benddeploy-tutorial-server-0' |
| 36 | +INFO[0001] Creating LoadBalancer 'k3d-benddeploy-tutorial-serverlb' |
| 37 | +INFO[0001] Using the k3d-tools node to gather environment information |
| 38 | +INFO[0001] Starting new tools node... |
| 39 | +INFO[0001] Starting node 'k3d-benddeploy-tutorial-tools' |
| 40 | +INFO[0002] Starting cluster 'benddeploy-tutorial' |
| 41 | +INFO[0002] Starting servers... |
| 42 | +INFO[0002] Starting node 'k3d-benddeploy-tutorial-server-0' |
| 43 | +INFO[0005] All agents already running. |
| 44 | +INFO[0005] Starting helpers... |
| 45 | +INFO[0005] Starting node 'k3d-benddeploy-tutorial-serverlb' |
| 46 | +INFO[0011] Injecting records for hostAliases (incl. host.k3d.internal) and for 3 network members into CoreDNS configmap... |
| 47 | +INFO[0013] Cluster 'benddeploy-tutorial' created successfully! |
| 48 | +INFO[0013] You can now use it like this: |
| 49 | +kubectl cluster-info |
| 50 | +➜ ~ k3d cluster list |
| 51 | + |
| 52 | +NAME SERVERS AGENTS LOADBALANCER |
| 53 | +benddeploy-tutorial 1/1 0/0 true |
| 54 | +``` |
| 55 | + |
| 56 | +2. 验证 Kubernetes 节点是否已启动并正在运行: |
| 57 | + |
| 58 | +```bash |
| 59 | +kubectl get nodes |
| 60 | +``` |
| 61 | + |
| 62 | +你应该在 `Ready` 状态下看到控制平面节点: |
| 63 | + |
| 64 | +```bash |
| 65 | +NAME STATUS ROLES AGE VERSION |
| 66 | +k3d-benddeploy-tutorial-server-0 Ready control-plane,master 7m35s v1.31.5+k3s1 |
| 67 | +``` |
| 68 | + |
| 69 | +3. 安装 Prometheus CRDs。在继续之前,请确保你的集群具有所需的 Prometheus Operator CRDs,尤其是 ServiceMonitor。 |
| 70 | + |
| 71 | +```bash |
| 72 | +kubectl apply -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/main/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml |
| 73 | +``` |
| 74 | + |
| 75 | +4. 克隆 BendDeploy Helm charts 存储库: |
| 76 | + |
| 77 | +```bash |
| 78 | +git clone https://github.com/databendcloud/benddeploy-charts.git |
| 79 | +cd benddeploy-charts/charts/logging |
| 80 | +``` |
| 81 | + |
| 82 | +## 步骤 2:部署 Logging 组件(可选) |
| 83 | + |
| 84 | +如果你想从 BendDeploy 收集系统日志并将其存储在 S3 中以进行进一步分析,则此步骤是可选的,但建议执行。 |
| 85 | + |
| 86 | +1. 更新 `charts/logging` 目录中的 **values.yaml** 文件,以启用 `warehouseLogCollector` 并将其配置为使用与 S3 兼容的存储: |
| 87 | + |
| 88 | +```yaml |
| 89 | +... |
| 90 | + |
| 91 | +warehouseLogCollector: |
| 92 | + enabled: true |
| 93 | + replicas: 1 |
| 94 | + nameOverride: warehouse-log-collector |
| 95 | + fullnameOverride: warehouse-log-collector |
| 96 | + s3: |
| 97 | + endpoint: "https://s3.us-east-2.amazonaws.com" |
| 98 | + bucket: "databend-doc" |
| 99 | + region: "us-east-2" |
| 100 | + auth: |
| 101 | + accessKeyId: "<your-access-key-id>" |
| 102 | + secretAccessKey: "<your-secret-access-key>" |
| 103 | + |
| 104 | +... |
| 105 | +``` |
| 106 | + |
| 107 | +2. 编辑位于 `configs/vector/` 中的 **agent.yaml** 文件,以配置 S3 sink 用于日志存储: |
| 108 | + |
| 109 | +```yaml |
| 110 | +... |
| 111 | + |
| 112 | + # S3 sink |
| 113 | + s3_logs: |
| 114 | + type: aws_s3 |
| 115 | + inputs: |
| 116 | +# - filter_kubernetes_logs |
| 117 | + - filter_warehouse_system_logs |
| 118 | + endpoint: "https://s3.us-east-2.amazonaws.com" |
| 119 | + bucket: "databend-doc" |
| 120 | + key_prefix: "logs/{{ tenant }}/system/" |
| 121 | + compression: gzip |
| 122 | + encoding: |
| 123 | + codec: native_json |
| 124 | + |
| 125 | + auth: |
| 126 | + access_key_id: "<your-access-key-id>" |
| 127 | + secret_access_key: "<your-secret-access-key>" |
| 128 | + |
| 129 | + region: "us-east-2" |
| 130 | + |
| 131 | +... |
| 132 | +``` |
| 133 | + |
| 134 | +3. 使用 Helm 部署 logging 组件: |
| 135 | + |
| 136 | +```bash |
| 137 | +helm upgrade --install logging . --namespace=logging --create-namespace |
| 138 | +``` |
| 139 | + |
| 140 | +成功后,Helm 将显示一条消息,确认部署: |
| 141 | + |
| 142 | +```bash |
| 143 | +Release "logging" does not exist. Installing it now. |
| 144 | +NAME: logging |
| 145 | +LAST DEPLOYED: Sun Apr 20 11:36:46 2025 |
| 146 | +NAMESPACE: logging |
| 147 | +STATUS: deployed |
| 148 | +REVISION: 1 |
| 149 | +TEST SUITE: None |
| 150 | +``` |
| 151 | + |
| 152 | +4. 验证 logging 组件是否正在运行: |
| 153 | + |
| 154 | +```bash |
| 155 | +kubectl get pod -n logging |
| 156 | +``` |
| 157 | + |
| 158 | +你应该看到如下输出: |
| 159 | + |
| 160 | +```bash |
| 161 | +NAME READY STATUS RESTARTS AGE |
| 162 | +vector-xpshl 1/1 Running 0 6s |
| 163 | +warehouse-log-aggregator-0 1/1 Running 0 70m |
| 164 | +warehouse-log-collector-0 1/1 Running 0 3s |
| 165 | +``` |
| 166 | + |
| 167 | +## 步骤 3:部署 BendDeploy |
| 168 | + |
| 169 | +现在你的集群已准备就绪,你可以将 BendDeploy 安装到 Kubernetes 环境中。 |
| 170 | + |
| 171 | +1. 对于生产部署,自定义 `charts/benddeploy/templates` 目录中的 **configmap-benddeploy.yaml** 文件,以确保 BendDeploy 可以正确拉取镜像、存储日志、连接到指标和数据库以及验证用户身份。如果保持不变,将使用默认设置,这些设置适用于测试,但不建议用于生产环境。 |
| 172 | + |
| 173 | +| 字段 | 描述 | |
| 174 | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 175 | +| `imageRegistry` | 用于拉取 Databend Docker 镜像的镜像仓库。如果你的集群无法访问互联网,请将镜像推送到你自己的仓库(例如,`registry.databend.local`)。留空以使用 Docker Hub。 | |
| 176 | +| `registryUsername` | 用于访问你的镜像仓库的用户名(如果需要)。 | |
| 177 | +| `registryPassword` | 用于访问你的镜像仓库的密码(如果需要)。 | |
| 178 | +| `repoNamespace` | 存储 Databend 镜像的命名空间。例如,如果镜像为 `registry.databend.local/datafuselabs/databend-query:tag`,则 `repoNamespace` 为 `datafuselabs`。 | |
| 179 | +| `promEndpoint` | 你的 Prometheus 服务器的端点,例如 `prometheus-k8s.monitoring.svc.cluster.local:9090`。 | |
| 180 | +| `logCollectorEndpoint` | 你的日志收集器(例如,Vector 或 OpenTelemetry)的端点,例如 `http://warehouse-log-collector.logging.svc.cluster.local:4318`。 | |
| 181 | +| `grafanaEndpoint` | 你的 Grafana 仪表板的地址,例如 `http://grafana.monitoring.svc.cluster.local:80`。 | |
| 182 | +| `db.postgresDSN` | 外部 PostgreSQL 数据库的 DSN。 | |
| 183 | +| `oidcProvider` | 用于身份验证的 OIDC 提供程序 URL。必须可以从集群内部访问或通过 Ingress 公开。 | |
| 184 | + |
| 185 | +2. 使用 Helm 从克隆的存储库的根目录安装 BendDeploy。访问 [Amazon ECR Public Gallery 上的 BendDeploy 镜像存储库](https://gallery.ecr.aws/databendlabs/benddeploy) 并检查 **Image tags** 部分以查找最新版本,例如 `v1.0.2`。 |
| 186 | + |
| 187 | +```bash |
| 188 | +# 将 <version> 替换为最新版本: |
| 189 | +helm install benddeploy -n benddeploy --create-namespace ./charts/benddeploy --set image=public.ecr.aws/databendlabs/benddeploy:<version> |
| 190 | +``` |
| 191 | + |
| 192 | +Helm 将确认部署: |
| 193 | + |
| 194 | +```bash |
| 195 | +NAME: benddeploy |
| 196 | +LAST DEPLOYED: Sun Apr 20 12:44:44 2025 |
| 197 | +NAMESPACE: benddeploy |
| 198 | +STATUS: deployed |
| 199 | +REVISION: 1 |
| 200 | +TEST SUITE: None |
| 201 | +➜ benddeploy-charts git:(main) ✗ |
| 202 | +``` |
| 203 | + |
| 204 | +3. 验证 BendDeploy pods 是否正在运行: |
| 205 | + |
| 206 | +```bash |
| 207 | +kubectl get pod -n benddeploy |
| 208 | +``` |
| 209 | + |
| 210 | +预期输出: |
| 211 | + |
| 212 | +```bash |
| 213 | +NAME READY STATUS RESTARTS AGE |
| 214 | +benddeploy-cfdd898d5-pkfwd 1/1 Running 0 69s |
| 215 | +benddeploy-frontend-6988fdc5b9-blt2n 1/1 Running 0 69s |
| 216 | +pg-benddeploy-64c64b95c-wd55m 1/1 Running 0 69s |
| 217 | +``` |
| 218 | + |
| 219 | +## 步骤 4:访问 Web 界面 |
| 220 | + |
| 221 | +部署完成后,你现在可以在浏览器中访问 BendDeploy Web UI。 |
| 222 | + |
| 223 | +1. 通过端口转发公开前端。 |
| 224 | + |
| 225 | + |
| 226 | +:::tip |
| 227 | +虽然端口转发非常适合快速本地访问,但对于生产或共享环境,请考虑配置 Ingress 控制器(如 NGINX Ingress)或通过 LoadBalancer 公开服务,以便从集群外部访问 BendDeploy。这允许您通过真实的域名或 IP 地址访问 Web UI。 |
| 228 | +::: |
| 229 | + |
| 230 | +首先,检查服务: |
| 231 | + |
| 232 | +```bash |
| 233 | +kubectl get svc -n benddeploy |
| 234 | +``` |
| 235 | + |
| 236 | +```bash |
| 237 | +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE |
| 238 | +benddeploy-service ClusterIP 10.43.74.161 <none> 8080/TCP 9m23s |
| 239 | +frontend-service ClusterIP 10.43.70.22 <none> 8080/TCP 9m23s |
| 240 | +pg-benddeploy ClusterIP 10.43.38.197 <none> 5432/TCP 9m23s |
| 241 | +``` |
| 242 | + |
| 243 | +然后将前端服务转发到您的本地计算机: |
| 244 | + |
| 245 | +```bash |
| 246 | +kubectl port-forward -n benddeploy svc/frontend-service 8080:8080 |
| 247 | +``` |
| 248 | + |
| 249 | +您将看到: |
| 250 | + |
| 251 | +```bash |
| 252 | +Forwarding from 127.0.0.1:8080 -> 8080 |
| 253 | +Forwarding from [::1]:8080 -> 8080 |
| 254 | +``` |
| 255 | + |
| 256 | +2. 导航到 [http://localhost:8080](http://localhost:8080) 以使用默认凭据(用户名:`databend`,密码:`Databend@1*`)访问 BendDeploy。 |
| 257 | + |
| 258 | + |
0 commit comments