From 8eac7fd275329910b1059732a4f5e23f4bbb42e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=81=90=E5=AE=87?= Date: Tue, 9 Apr 2024 16:40:52 +0800 Subject: [PATCH] add installation guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 遐宇 --- docs/getting-started/installation.md | 119 ++++++++++++++- .../current/getting-started/installation.md | 111 ++++++++++++++ .../guide/exporter/exporter_installation.md | 136 ------------------ 3 files changed, 228 insertions(+), 138 deletions(-) delete mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/guide/exporter/exporter_installation.md diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 842278e..36f748e 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -4,6 +4,121 @@ sidebar_position: 3 # Installation -## Install via `skoopbundle.yml` - ## Install via Helm + +You can install production-ready KubeSkoop instance by Helm. + +Execute the following command to add the KubeSkoop repository to Helm and install KubeSkoop: + +```shell +# Add kubeskoop repo +helm repo add kubeskoop https://kubeskoop.io/kubeskoop/ +# Upgrade helm repo +helm repo update +# Install kubeskoop +helm install -n kubeskoop kubeskoop kubeskoop/kubeskoop +``` + +The command will install `KubeSkoop` into the `kubeskoop` namespace and turn on the agent, controller and webconsole components of `KubeSkoop` by default. + +## Customize Configuration + +You can view the values that can be configured by executing the following command. + +```shell +helm show values kubeskoop/kubeskoop +``` + +You can save the values to the `values.yaml` file, make changes to the parameters you need, and then install KubeSkoop with theses values. + +```shell +# If you have already installed KubeSkoop, you can upgrade it with `helm upgrade`. +helm install -f values.yaml -n kubeskoop kubeskoop kubeskoop/kubeskoop +``` + +You can also use the `--set` parameter to customize the configuration. + +```shell +helm install --set controller.config.prometheusEndpoint=http://prometheus -n kubeskoop kubeskoop kubeskoop/kubeskoop +``` + +## Configure Probes + +In the `config` section of the values, you can configure the metrics/event probes that need to be turned on. + +The default configuration is as follows: + +```yaml +config: + metricProbes: + - name: conntrack + - name: qdisc + - name: netdev + - name: io + - name: sock + - name: tcpsummary + - name: tcp + - name: tcpext + - name: udp + - name: kernellatency + - name: packetloss + - name: flow + args: + enablePortInLabel: false + - name: tcpretrans + eventProbes: + - name: biolatency + - name: kernellatency + - name: packetloss + args: + enableStack: false + - name: tcpreset + - name: tcpretrans + eventSinks: + - name: stderr +``` + +For more information about the probes, please see [the documentation](../reference/monitoring/probes-metrics-events.md). + +## Configure Prometheus and Loki Endpoint + +Some features (e.g., network graph, anomaly events) of [Web Console](.../guide/web-console.md) relies on Prometheus and Loki. +You need to provide the endpoint for the Prometheus and Loki services during installation. + +:::tip +If there is no ready-to-use Prometheus or Loki instances, you can refer to theses documentations: + +- Refer to **[Prometheus Installation](https://prometheus.io/docs/prometheus/latest/installation/)** to complete the deployment and installation of Prometheus. +- Refer to **[Install Grafana Loki with Helm](https://grafana.com/docs/loki/latest/setup/install/helm/)** to complete the deployment and installation of Loki. + +::: + +Configure `prometheusEndpoint` and `lokiEndpoint` in the `controller.config` section. + +Assuming that prometheus and loki are installed in the `monitoring` namespace, + and the service names are `prometheus` and `loki`, a sample configuration is as follows: + + ```yaml + controller: + enabled: true + config: + # configure endpoint address for prometheus. + prometheusEndpoint: 'http://prometheus.monitoring:9090' + # configure endpoint address for loki. + lokiEndpoint: 'http://loki.monitoring:3100' +``` + +At the same time, the event sinks needs to be configured in `config.eventSink` so that events can be collected via Loki. + +```yaml +config: + # ...some probe configurations + eventSinks: + - name: stderr + # configure loki event sink and specify the address as the service address of loki. + - name: loki + args: + addr: 'http://loki.monitoring:3100' +``` + +Finally, install/update KubeSkoop via `helm install` or `helm upgrade`. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation.md b/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation.md index 55f1ef1..e27f77a 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/installation.md @@ -7,3 +7,114 @@ sidebar_position: 2 ## 通过Helm安装 你可以通过Helm来安装生产可用的KubeSkoop实例。 + +执行以下命令，将KubeSkoop仓库添加到Helm中并安装KubeSkoop： + +```shell +# 添加kubeskoop repo +helm repo add kubeskoop https://kubeskoop.io/kubeskoop/ +# 更新helm repo +helm repo update +# 安装kubeskoop +helm install -n kubeskoop kubeskoop kubeskoop/kubeskoop +``` + +该命令将会将`KubeSkoop`安装至`kubeskoop`命名空间，并默认开启`KubeSkoop`的agent、controller和webconsole组件。 + +## 自定义配置 + +你可以执行以下命令查看helm chart中可以配置的值。 + +```shell +helm show values kubeskoop/kubeskoop +``` + +你可以将值保存至`values.yaml`文件中，对你需要的参数进行修改，然后进行KubeSkoop的安装。 + +```shell +# 若你已经安装了KubeSkoop，你可以通过`helm upgrade`命令对其进行更新。 +helm install -f values.yaml -n kubeskoop kubeskoop kubeskoop/kubeskoop +``` + +你也可以使用`--set`来进行简单的配置。 + +```shell +helm install --set controller.config.prometheusEndpoint=http://prometheus -n kubeskoop kubeskoop kubeskoop/kubeskoop +``` + +## 配置探针 + +在配置中的`config`一节，可以对所需开启的指标/事件探针进行配置。默认配置如下： + +```yaml +config: + metricProbes: + - name: conntrack + - name: qdisc + - name: netdev + - name: io + - name: sock + - name: tcpsummary + - name: tcp + - name: tcpext + - name: udp + - name: kernellatency + - name: packetloss + - name: flow + args: + enablePortInLabel: false + - name: tcpretrans + eventProbes: + - name: biolatency + - name: kernellatency + - name: packetloss + args: + enableStack: false + - name: tcpreset + - name: tcpretrans + eventSinks: + - name: stderr +``` + +关于探针的更多信息，请见[文档](../reference/monitoring/probes-metrics-events.md)。 + +## 配置Prometheus和Loki端点地址 + +[Web控制台](../guide/web-console.md)的部分功能（如网络链路图、异常事件）依赖Prometheus和Loki。你需要在Helm安装时提供Prometheus和Loki服务的端点地址。 + +:::tip +若没有已经就绪的Prometheus或Loki实例，可以参考以下文档： + +- 参考 **[Prometheus的安装](https://prometheus.io/docs/prometheus/latest/installation/)** 完成Prometheus的部署安装。 +- 参考 **[使用Helm安装Loki](https://grafana.com/docs/loki/latest/setup/install/helm/)** 完成Loki的部署安装。 + +::: + +在`controller.config`一节中配置`prometheusEndpoint`和`lokiEndpoint`。 + +假设Prometheus和Loki安装在`monitoring`命名空间，并且service名称分别为`prometheus`和`loki`，示例配置如下： + +```yaml +controller: + enabled: true + config: + # 配置prometheus的端点地址。 + prometheusEndpoint: 'http://prometheus.monitoring:9090' + # 配置loki的端点地址。 + lokiEndpoint: 'http://loki.monitoring:3100' +``` + +同时，需要在`config.eventSink`中配置事件收集器，使事件能够通过Loki收集。 + +```yaml +config: + # ...其它探针配置 + eventSinks: + - name: stderr + # 配置loki事件收集器，并指定地址为loki的service地址。 + - name: loki + args: + addr: 'http://loki.monitoring:3100' +``` + +最后，通过`helm install`或者`helm upgrade`对KubeSkoop进行安装/更新。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/guide/exporter/exporter_installation.md b/i18n/zh/docusaurus-plugin-content-docs/current/guide/exporter/exporter_installation.md deleted file mode 100644 index c78cb5d..0000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/guide/exporter/exporter_installation.md +++ /dev/null @@ -1,136 +0,0 @@ -# 安装 KubeSkoop exporter - -## 安装依赖 - -* Linux kernel >= 4.9.17 （在低版本内核上可以支持部分功能） -* 基于Docker/Containerd/Pouch的容器运行时 - -## 快速安装 - -### 快速体验KubeSkoop exporter功能 - -KubeSkoop exporter提供了一个可以快速部署的配置，包含以下组件： - -* KubeSkoop exporter组件。 -* 单副本的Prometheus组件与Grafana组件，Grafana Loki组件。 -* Prometheus和Grafana的NodePort服务。 - -通过以下步骤，可以在Kubernetes集群中快速部署KubeSkoop exporter及其与Prometheus，Grafana和Loki构成的可观测性组合： - -```shell -kubectl apply -f https://raw.githubusercontent.com/alibaba/kubeskoop/main/deploy/skoopbundle.yaml -``` - -通过以下步骤，确认安装完成以及获取访问入口： - -```shell -# 查看Skoop exporter的运行状态 -kubectl get pod -n kubeskoop -l app=kubeskoop-exporter -o wide - -# 查看Probe采集探针的运行状态 -kubectl get --raw /api/v1/namespaces/{{skoop-exporter的pod namespace}}/pods/{{skoop-exporter的pod name}}:9102/proxy/status |jq . - -# 获取Prometheus服务的入口 -kubectl get service -n kubeskoop prometheus-service -o wide - -# 获取Grafana控制台的访问入口 -kubectl get service -n kubeskoop grafana -o wide -``` - -### 仅安装KubeSkoop exporter - -通过以下步骤，可以在Kubernetes集群中快速部署KubeSkoop exporter： - -```shell -kubectl apply -f https://github.com/alibaba/kubeskoop/deploy/kubeskoopexporter.yaml -``` - -## 使用Helm安装 - -```shell -# 添加skoop charts repo -helm repo add kubeskoop https://github.com/alibaba/kubeskoop/charts - -# 首次执行时，需要更新helm repo缓存 -helm repo update - -# 安装skoop exporter -helm install skoop-exporter kubeskoop/skoop-exporter -``` - -如果需要调试Helm Charts信息，可以通过本地安装： - -```shell -# 获取skoop exporter代码仓库 -git clone https://github.com/alibaba/kubeskoop.git - -# 进行本地安装 -helm install --set namespace=kube-system skoop-exporter ./kubeskoop/deploy/skoop-exporter-0.1.0.tgz --debug -``` - -Skoop-exporter以DaemonSet方式部署在集群中，可以通过以下方式验证是否正常工作： - -```shell -# 查看Skoop exporter的运行状态 -kubectl get pod -n kubeskoop -l app=kubeskoop-exporter -o wide - -# 获取到pod的信息后，可以通过apiserver查看Probe采集探针的运行状态 -kubectl get --raw /api/v1/namespaces/{{skoop-exporter的pod namespace}}/pods/{{skoop-exporter的pod name}}:9102/proxy/status |jq . - -# 如果可以直接访问skoop-exporter实例，也可以直接查看Probe的运行状态 -curl {{skoop-exporter的pod ip}}:9102/status |jq . -``` - -### Helm配置 - -通过helm安装KubeSkoop exporter时，可以配置的参数如下： - -| 配置项 | 配置说明 | 默认配置 | -|------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------| -| name | KubeSkoop exporter的组件名称 | `skoop-exporter` | -| namespace | KubeSkoop exporter的命名空间 | `kubeskoop` | -| debugmode | 调试模式的开关，打开调试模式后，可以获得更详细的日志以及开启pprof和gops接口 | `false` | -| config.enableEventServer | 事件采集服务的开关 | `false` | -| config.enableMetricServer | 监控指标服务的开关 | `true` | -| config.remoteLokiAddress | 开启事件采集服务后，通过这个选项配置需要推送事件的Grafana Loki服务地址 | `` | -| config.metricLabelVerbose | 获取更加详细的监控指标标签，包括Pod的app标签，ip地址等 | `false` | -| config.metricServerPort | 监控指标服务的端口，提供http服务 | 9102 | -| config.eventServerPort | KubeSkoop exporter的GRPC服务端口，提供事件流服务| 19102 | -| config.metricProbes | 配置开启的监控指标探针| | -| config.eventProbes | 配置开启的事件采集探针 | | -| config.metricCacheInterval | 监控指标的采集缓存周期，单位为秒 | 15 | - -### 安装完成校验 - -通过helm方式完成KubeSkoop exporter的安装后，可以通过以下方式验证是否正常运行: - -```shell -# 查看Probe采集探针的运行状态 -kubectl get --raw /api/v1/namespaces/{{KubeSkoop exporter的pod namespace}}/pods/{{KubeSkoop exporter的pod name}}:9102/proxy/status |jq . -``` - -## 配置 - -KubeSkoop exporter的配置是默认由与workload相同命名空间下的ConfigMap对象inspector-config进行管理，通过以下方式可以进行修改： - -```shell -# 修改命名空间为实际生效的命名空间 -kubectl edit cm -n kubeskoop inspector-config -``` - -KubeSkoop exporter支持的配置项如下: - -| 配置项 | 配置功能 | 默认值 | -|------------------------------------|-----------------|------------------------------------| -| debugmode | 调试模式的开关，打开调试模式后，可以获得更详细的日志以及开启pprof和gops接口 | `false` | -| event_config.loki_enable | 事件采集服务推向给Grafana Loki的开关 | `false` | -| event_config.loki_address | 开启事件采集服务后，通过这个选项配置需要推送事件的Grafana Loki服务地址 | `` | -| event_config.probes | 配置开启的事件采集探针 | | -| event_config.port | KubeSkoop exporter的GRPC服务端口，提供事件流服务| 19102 | -| metric_config.verbose | 获取更加详细的监控指标标签，包括Pod的app标签，ip地址等 | `false` | -| metric_config.port |监控指标服务的端口，提供http服务 | 9102 | -| metric_config.probes | 配置开启的监控指标探针 | | -| metric_config.interval | 监控指标的采集缓存周期，单位为秒 | 15 | - -可以选择配置的探针信息可以参考**[KubeSkoop exporter 功能简介 -](exporter-description.md)**