You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@inlong.apache.org by do...@apache.org on 2022/04/13 10:58:45 UTC
[incubator-inlong-website] branch master updated: [INLONG-3489] Add k8s docs to official website (#344)
This is an automated email from the ASF dual-hosted git repository.
dockerzhang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-inlong-website.git
The following commit(s) were added to refs/heads/master by this push:
new 1f847b039 [INLONG-3489] Add k8s docs to official website (#344)
1f847b039 is described below
commit 1f847b039a7d515db49441f3e23cc4a60b4f2bdf
Author: Yuanhao Ji <ji...@apache.org>
AuthorDate: Wed Apr 13 18:58:41 2022 +0800
[INLONG-3489] Add k8s docs to official website (#344)
---
docs/deployment/k8s.md | 130 +++++++++++++++++++--
.../current/deployment/k8s.md | 130 +++++++++++++++++++--
2 files changed, 246 insertions(+), 14 deletions(-)
diff --git a/docs/deployment/k8s.md b/docs/deployment/k8s.md
index 0e0d92d49..e08c06bf7 100644
--- a/docs/deployment/k8s.md
+++ b/docs/deployment/k8s.md
@@ -10,15 +10,62 @@ sidebar_position: 3
- [InLong Helm Chart](https://github.com/apache/incubator-inlong/tree/master/docker/kubernetes)
- A dynamic provisioner for the PersistentVolumes(`production environment`)
-## Install
+## Usage
+
+### Install
+
+If the namespace named `inlong` does not exist, create it first by running:
```shell
kubectl create namespace inlong
+```
+
+To install the chart with a namespace named `inlong`, try:
+
+```shell
helm upgrade inlong --install -n inlong ./
```
-## Configuration
-The configuration file is **values.yaml**, and the following tables lists the configurable parameters of InLong and their default values.
+### Access InLong Dashboard
+
+If `ingress.enabled` in [values.yaml](https://github.com/apache/incubator-inlong/blob/master/docker/kubernetes/values.yaml) is set to `true`, you just access `http://${ingress.host}/dashboard` in browser.
+
+Otherwise, when `dashboard.service.type` is set to `ClusterIP`, you need to execute the port-forward command like:
+
+```shell
+export DASHBOARD_POD_NAME=$(kubectl get pods -l "app.kubernetes.io/name=inlong-dashboard,app.kubernetes.io/instance=inlong" -o jsonpath="{.items[0].metadata.name}" -n inlong)
+export DASHBOARD_CONTAINER_PORT=$(kubectl get pod $DASHBOARD_POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}" -n inlong)
+kubectl port-forward $DASHBOARD_POD_NAME 8181:$DASHBOARD_CONTAINER_PORT -n inlong
+```
+
+And then access [http://127.0.0.1:8181](http://127.0.0.1:8181)
+
+> Tip: If the error of `unable to do port forwarding: socat not found` appears, you need to install `socat` at first.
+
+Or when `dashboard.service.type` is set to `NodePort`, you need to execute the following commands:
+
+```shell
+export DASHBOARD_NODE_IP=$(kubectl get nodes -o jsonpath="{.items[0].status.addresses[0].address}" -n inlong)
+export DASHBOARD_NODE_PORT=$(kubectl get svc inlong-dashboard -o jsonpath="{.spec.ports[0].nodePort}" -n inlong)
+```
+
+And then access `http://$DASHBOARD_NODE_IP:$DASHBOARD_NODE_PORT`
+
+When `dashboard.service.type` is set to `LoadBalancer`, you need to execute the following command:
+
+```shell
+export DASHBOARD_SERVICE_IP=$(kubectl get svc inlong-dashboard --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}" -n inlong)
+```
+
+And then access `http://$DASHBOARD_SERVICE_IP:30080`
+
+> NOTE: It may take a few minutes for the `LoadBalancer` IP to be available. You can check the status by running `kubectl get svc inlong-dashboard -n inlong -w`
+
+The default username is `admin` and the default password is `inlong`. You can access the InLong Dashboard through them.
+
+### Configuration
+
+The configuration file is [values.yaml](https://github.com/apache/incubator-inlong/blob/master/docker/kubernetes/values.yaml), and the following tables lists the configurable parameters of InLong and their default values.
| Parameter | Default | Description |
|:--------------------------------------------------------------------------------:|:----------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------:|
@@ -27,7 +74,7 @@ The configuration file is **values.yaml**, and the following tables lists the co
| `images.<component>.repository` | | Docker image repository for the component |
| `images.<component>.tag` | `latest` | Docker image tag for the component |
| `<component>.component` | | Component name |
-| `<component>.replicaCount` | `1` | Replicas is the desired number of replicas of a given Template |
+| `<component>.replicas` | `1` | Replicas is the desired number of replicas of a given Template |
| `<component>.podManagementPolicy` | `OrderedReady` | PodManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down |
| `<component>.annotations` | `{}` | The `annotations` field can be used to attach arbitrary non-identifying metadata to objects |
| `<component>.tolerations` | `[]` | Tolerations are applied to pods, and allow (but do not require) the pods to schedule onto nodes with matching taints |
@@ -59,17 +106,86 @@ The configuration file is **values.yaml**, and the following tables lists the co
| `external.pulsar.serviceUrl` | `localhost:6650` | External Pulsar service URL |
| `external.pulsar.adminUrl` | `localhost:8080` | External Pulsar admin URL |
-> The components include `agent`, `audit`, `dashboard`, `dataproxy`, `manager`, `tubemq-manager`, `tubemq-master`, `tubemq-broker`, `zookeeper` and `mysql`.
+> The optional components include `agent`, `audit`, `dashboard`, `dataproxy`, `manager`, `tubemq-manager`, `tubemq-master`, `tubemq-broker`, `zookeeper` and `mysql`.
+
+### Uninstall
-## Uninstall
+To uninstall the release, try:
```shell
helm uninstall inlong -n inlong
```
-You can delete all `PVC ` if any persistent volume claims used, it will lose all data.
+The above command removes all the Kubernetes components except the `PVC` associated with the chart, and deletes the release.
+You can delete all `PVC` if any persistent volume claims used, it will lose all data.
```shell
kubectl delete pvc -n inlong --all
```
+> Note: Deleting the PVC also delete all data. Please be cautious before doing it.
+
+## Development
+
+A Kubernetes cluster with [helm](https://helm.sh) is required before development.
+But it doesn't matter if you don't have one, the [kind](https://github.com/kubernetes-sigs/kind) is recommended.
+It runs a local Kubernetes cluster in Docker container. Therefore, it requires very little time to up and stop the Kubernetes node.
+
+### Quick start with kind
+
+You can install kind by following the [Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start) section of their official documentation.
+
+After installing kind, you can create a Kubernetes cluster with the [kind.yml](https://github.com/apache/incubator-inlong/tree/master/.github/kind.yml), try:
+
+```shell
+kind create cluster --config kind.yml
+```
+
+To specify another image use the `--image` flag – `kind create cluster --image=....`.
+Using a different image allows you to change the Kubernetes version of the created cluster.
+To find images suitable for a given release currently you should check the [release notes](https://github.com/kubernetes-sigs/kind/releases) for your given kind version (check with `kind version`) where you'll find a complete listing of images created for a kind release.
+
+After installing kind, you can interact with the created cluster, try:
+
+```shell
+kubectl cluster-info --context kind-inlong-cluster
+```
+
+Now, you have a running Kubernetes cluster for local development.
+
+### Install Helm
+
+Please follow the [installation guide](https://helm.sh/docs/intro/install) in the official documentation to install Helm.
+
+### Install the chart
+
+To create the namespace and Install the chart, try:
+
+```shell
+kubectl create namespace inlong
+helm upgrade inlong --install -n inlong ./
+```
+
+It may take a few minutes. Confirm the pods are up:
+
+```shell
+watch kubectl get pods -n inlong -o wide
+```
+
+### Develop and debug
+
+Follow the [template debugging guide](https://helm.sh/docs/chart_template_guide/debugging) in the official documentation to debug your chart.
+
+Besides, you can save the rendered templates by:
+
+```shell
+helm template ./ --output-dir ./result
+```
+
+Then, you can check the rendered templates in the `result` directory.
+
+## Troubleshooting
+
+We've done our best to make these charts as seamless as possible, but occasionally there are circumstances beyond our control.
+We've collected tips and tricks for troubleshooting common issues.
+Please examine these first before raising an [issue](https://github.com/apache/incubator-inlong/issues/new/choose), and feel free to make a [Pull Request](https://github.com/apache/incubator-inlong/compare)!
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/k8s.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/k8s.md
index fa2df15e2..c899b665f 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/k8s.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/k8s.md
@@ -10,15 +10,63 @@ sidebar_position: 3
- [InLong Helm Chart](https://github.com/apache/incubator-inlong/tree/master/docker/kubernetes)
- A dynamic provisioner for the PersistentVolumes(`production environment`)
-## 安装
+## 使用
+
+### 安装
+
+如果不存在名为 `inlong` 的命名空间，则可通过以下命令创建：
```shell
kubectl create namespace inlong
+```
+
+在 [docker/kubernetes](https://github.com/apache/incubator-inlong/tree/master/docker/kubernetes) 目录下安装 chart：
+
+```shell
helm upgrade inlong --install -n inlong ./
```
-## 配置
-配置内容都在 **values.yaml** 文件中，以下为所有可配置项及其默认值，包括：
+### 进入 InLong Dashboard
+
+如果 [values.yaml](https://github.com/apache/incubator-inlong/blob/master/docker/kubernetes/values.yaml) 中的 `ingress.enabled` 字段值是 `true`，
+则直接在浏览器中访问 `http://${ingress.host}/dashboard` 即可
+
+否则，如果 `dashboard.service.type` 字段值设置为 `ClusterIP`，则需要执行以下命令进行端口转发：
+
+```shell
+export DASHBOARD_POD_NAME=$(kubectl get pods -l "app.kubernetes.io/name=inlong-dashboard,app.kubernetes.io/instance=inlong" -o jsonpath="{.items[0].metadata.name}" -n inlong)
+export DASHBOARD_CONTAINER_PORT=$(kubectl get pod $DASHBOARD_POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}" -n inlong)
+kubectl port-forward $DASHBOARD_POD_NAME 8181:$DASHBOARD_CONTAINER_PORT -n inlong
+```
+
+之后就可以访问 [http://127.0.0.1:8181](http://127.0.0.1:8181) 进入 InLong Dashboard 了。
+
+> 提示：如果出现 `unable to do port forwarding: socat not found` 的错误，则首先需要安装 `socat`
+
+如果 `dashboard.service.type` 字段值设置为 `NodePort`，则需要执行以下命令：
+
+```shell
+export DASHBOARD_NODE_IP=$(kubectl get nodes -o jsonpath="{.items[0].status.addresses[0].address}" -n inlong)
+export DASHBOARD_NODE_PORT=$(kubectl get svc inlong-dashboard -o jsonpath="{.spec.ports[0].nodePort}" -n inlong)
+```
+
+之后就可以访问 `http://$DASHBOARD_NODE_IP:$DASHBOARD_NODE_PORT` 进入 InLong Dashboard 了。
+
+如果 `dashboard.service.type` 字段值设置为 `LoadBalancer`，则需要执行以下命令：
+
+```shell
+export DASHBOARD_SERVICE_IP=$(kubectl get svc inlong-dashboard --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}" -n inlong)
+```
+
+之后就可以访问 `http://$DASHBOARD_SERVICE_IP:30080` 进入 InLong Dashboard 了。
+
+> 注意：这将花费一些时间，可以运行 `kubectl get svc inlong-dashboard -n inlong -w` 命令来查看其状态
+
+默认的用户名是 `admin`，默认密码是 `inlong`，你可以通过它们进入 InLong Dashboard。
+
+### 配置
+
+配置项在 [values.yaml](https://github.com/apache/incubator-inlong/blob/master/docker/kubernetes/values.yaml) 文件中，下表展示了所有可配置项及其默认值：
| Parameter | Default | Description |
|:--------------------------------------------------------------------------------:|:----------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------:|
@@ -27,7 +75,7 @@ helm upgrade inlong --install -n inlong ./
| `images.<component>.repository` | | Docker image repository for the component |
| `images.<component>.tag` | `latest` | Docker image tag for the component |
| `<component>.component` | | Component name |
-| `<component>.replicaCount` | `1` | Replicas is the desired number of replicas of a given Template |
+| `<component>.replicas` | `1` | Replicas is the desired number of replicas of a given Template |
| `<component>.podManagementPolicy` | `OrderedReady` | PodManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down |
| `<component>.annotations` | `{}` | The `annotations` field can be used to attach arbitrary non-identifying metadata to objects |
| `<component>.tolerations` | `[]` | Tolerations are applied to pods, and allow (but do not require) the pods to schedule onto nodes with matching taints |
@@ -59,18 +107,86 @@ helm upgrade inlong --install -n inlong ./
| `external.pulsar.serviceUrl` | `localhost:6650` | External Pulsar service URL |
| `external.pulsar.adminUrl` | `localhost:8080` | External Pulsar admin URL |
-> The components include `agent`, `audit`, `dashboard`, `dataproxy`, `manager`, `tubemq-manager`, `tubemq-master`, `tubemq-broker`, `zookeeper` and `mysql`.
+> 可选的组件有：`agent`、`audit`、`dashboard`、`dataproxy`、`manager`、`tubemq-manager`、`tubemq-master`、`tubemq-broker`、`zookeeper` 和 `mysql`。
+### 卸载
-## 卸载
+通过以下命令卸载 chart：
```shell
helm uninstall inlong -n inlong
```
-You can delete all `PVC ` if any persistent volume claims used, it will lose all data.
+上述命令会删除除与 chart 关联的 `PVC` 之外的所有 Kubernetes 组件。
+
+如果不再使用 `PVC`，可通过下列命令删除，它将会删除所有数据。
```shell
kubectl delete pvc -n inlong --all
```
+> 注意：删除 PVC 也会删除所有数据。在做之前请小心。
+
+## 开发
+
+在开发前需要有一个装有 [helm](https://helm.sh) 的 Kubernetes 集群。
+但是没有也没有关系，推荐使用 [kind](https://github.com/kubernetes-sigs/kind) ，
+它能够在 Docker 容器中运行一个本地的 Kubernetes 集群，因此，只需花费很少的时间即可启动和停止 kubernetes 节点。
+
+### kind 快速开始
+
+你可以按照 [快速开始](https://kind.sigs.k8s.io/docs/user/quick-start) 章节中的指示安装 kind。
+安装好 kind 后，你可以通过 [kind.yml](https://github.com/apache/incubator-inlong/tree/master/.github/kind.yml) 配置文件来创建一个 Kubernetes 集群。
+
+```shell
+kind create cluster --config kind.yml
+```
+
+可以通过 `--image` 指定具体的 Docker 镜像 —— `kind create cluster --image=....`。
+使用不同的镜像可以改变集群的 kubernetes 版本。
+要找到适合当前版本的镜像，你可以查看 [发行说明](https://github.com/kubernetes-sigs/kind/releases) 。
+
+之后，你可以通过以下命令与集群进行交互：
+
+```shell
+kubectl cluster-info --context kind-inlong-cluster
+```
+
+现在，你已经拥有了一个可以进行本地开发的 Kubernetes 集群！
+
+### 安装 Helm
+
+请按照 [安装指引](https://helm.sh/zh/docs/intro/install) 进行安装。
+
+### 安装 chart
+
+通过以下命令创建命名空间并安装 chart：
+
+```shell
+kubectl create namespace inlong
+helm upgrade inlong --install -n inlong ./
+```
+
+这将花费一段时间，通过以下命令查看所有 pod 是否能够正常启动：
+
+```shell
+watch kubectl get pods -n inlong -o wide
+```
+
+### 开发与调试
+
+按照 [模板调试指引](https://helm.sh/zh/docs/chart_template_guide/debugging) 来调试你所开发的 chart。
+
+除此以外，你可以通过以下命令保存渲染的模板：
+
+```shell
+helm template ./ --output-dir ./result
+```
+
+之后，你可以在 `result` 文件夹下检查渲染后的模板。
+
+## 故障排除
+
+我们已尽最大努力使这些 chart 尽可能正确，但偶尔也会出现我们无法控制的情况。
+我们已经收集了用于解决常见问题的提示和技巧。
+请在提出 [issue](https://github.com/apache/incubator-inlong/issues/new/choose) 之前先检查这些内容，并随时欢迎向我们提出 [Pull Request](https://github.com/apache/incubator-inlong/compare) ！