diff --git a/docs/README-zh_CN.md b/docs/README-zh_CN.md new file mode 100644 index 00000000..fcc3ca9c --- /dev/null +++ b/docs/README-zh_CN.md @@ -0,0 +1,41 @@ +# kdoctor +[![Auto Release Version](https://github.com/kdoctor-io/kdoctor/actions/workflows/auto-release.yaml/badge.svg)](https://github.com/kdoctor-io/kdoctor/actions/workflows/auto-release.yaml) +[![Auto Nightly CI](https://github.com/kdoctor-io/kdoctor/actions/workflows/auto-nightly-ci.yaml/badge.svg)](https://github.com/kdoctor-io/kdoctor/actions/workflows/auto-nightly-ci.yaml) +[![codecov](https://codecov.io/gh/kdoctor-io/kdoctor/branch/main/graph/badge.svg?token=rLmsuiBLM2)](https://codecov.io/gh/kdoctor-io/kdoctor) +[![Go Report Card](https://goreportcard.com/badge/github.com/kdoctor-io/kdoctor)](https://goreportcard.com/report/github.com/kdoctor-io/kdoctor) +[![CodeFactor](https://www.codefactor.io/repository/github/kdoctor-io/kdoctor/badge)](https://www.codefactor.io/repository/github/kdoctor-io/kdoctor) +![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ii2day/0300d0a99d701fec02909d843792e67d/raw/e2ereport.json) + +*** + +**简体中文** | [**English**](./README.md) + +## Introduction + +kdoctor 是一个 kubernetes 数据面测试项目，通过压力注入的方式，实现对集群进行功能、性能的主动式巡检。 + +传统的集群巡检，通过采集指标、日志、应用状态等信息来确认集群和应用的状态，实现被动式巡检。但是在一些特殊场景下，这种方式可能不能实现预期的巡检目的、时效性、集群范围，运维人员就需要采用手动方式给集群注入一些压力，进行主动式巡检，当集群规模很大、巡检频率高或巡检流程复杂时，手工方式难以持久实施。这些场景包括： + +* 部署大规模集群后，希望确认所有节点间 POD 的网络连通性，避免某个节点存在网络故障，发现网络中是否存在偶发丢包问题，而通信渠道非常多，包括 pod IP、clusterIP、nodePort、loadbalancer ip、ingress ip, 甚至是 POD 多网卡、双栈IP + +* 希望主动检测所有节点间上的 POD 能够正常访问 coredns 服务，希望确认 coredns 服务的资源配置和副本数量正确，其服务性能能欧支持预期的最大访问量 + +* 磁盘是易耗品，例如 etcd 等应用对磁盘性能是比较敏感的，在日常运维工作中，管理员希望周期地确认所有节点的本地磁盘是正常的，文件读写的吞吐量和延时是符合预期的 + +* 给某个服务主动注入压力，它可能是镜像仓库、mysql 或者 api-server，以配合 BUG 复现，或确认服务性能 + +kdoctor 是一个 kubernetes 数据面测试项目，来源于生产运维过程中的实践场景，通过压力注入的方式，实现对集群进行功能、性能的主动式巡检。 kdoctor 可以应用于: + +* 生产环境的部署检查、日常运维等场景，能避免了人工巡检的工作负担。 + +* 能应用 E2E 测试、bug 复现、混沌测试等，减少编程工作。 + +## 架构 + +## 快速开始 + +## 核心功能 + +## License + +kdoctor is licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for the full license text. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c3852496..e3285a47 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -39,7 +39,7 @@ markdown_extensions: nav: - README.md - Installation: - - Installation: usage/install-zh_CN.md + - Installation: usage/install.md - Usage: - AppHttpHealthy: usage/apphttphealthy.md - NetReach: usage/netreach.md @@ -47,9 +47,9 @@ nav: - Concepts: - Architecture: reference/arch.md - Reference: - - AppHttpHealthy: reference/apphttphealthy-zh_CN.md - - NetReach: reference/netreach-zh_CN.md - - NetDns: reference/netdns-zh_CN.md + - AppHttpHealthy: reference/apphttphealthy.md + - NetReach: reference/netreach.md + - NetDns: reference/netdns.md - Report: reference/report.md - Performance: usage/performance.md - Development: diff --git a/docs/reference/apphttphealthy-zh_CN.md b/docs/reference/apphttphealthy-zh_CN.md index 6159955f..178681f3 100644 --- a/docs/reference/apphttphealthy-zh_CN.md +++ b/docs/reference/apphttphealthy-zh_CN.md @@ -1,5 +1,7 @@ # AppHttpHealthy +[**English**](./apphttphealthy.md) | **简体中文** + ## 基本描述 对于这种任务，每个 kdoctor agent都会向指定的目标发送http请求，并获得成功率和平均延迟。它可以指定成功条件来判断结果是否成功。并且，可以通过聚合API获取详细的报告。 @@ -22,7 +24,7 @@ spec: schedule: roundNumber: 1 roundTimeoutMinute: 1 - schedule: 0 0 + schedule: 0 1 target: enableLatencyMetric: false host: http://www.baidu.com diff --git a/docs/reference/apphttphealthy.md b/docs/reference/apphttphealthy.md new file mode 100644 index 00000000..6cab46ee --- /dev/null +++ b/docs/reference/apphttphealthy.md @@ -0,0 +1,3 @@ +# AppHttpHealthy + +[**简体中文**](./apphttphealthy-zh_CN.md) | **English** diff --git a/docs/reference/netdns-zh_CN.md b/docs/reference/netdns-zh_CN.md index 9e299696..b12fc5ff 100644 --- a/docs/reference/netdns-zh_CN.md +++ b/docs/reference/netdns-zh_CN.md @@ -1,5 +1,7 @@ # netdns +[**English**](./netdns.md) | **简体中文** + ## 基本描述 对于这种任务，每个 kdoctor 代理都会向指定的目标发送 Dns 请求，并获得成功率和平均延迟。 它可以指定成功条件来告知结果成功或失败。 diff --git a/docs/reference/netdns.md b/docs/reference/netdns.md new file mode 100644 index 00000000..32cbdaab --- /dev/null +++ b/docs/reference/netdns.md @@ -0,0 +1,3 @@ +# netdns + +[**简体中文**](./netdns-zh_CN.md) | **English** diff --git a/docs/reference/netreach-zh_CN.md b/docs/reference/netreach-zh_CN.md index 201ecbed..c5c6160b 100644 --- a/docs/reference/netreach-zh_CN.md +++ b/docs/reference/netreach-zh_CN.md @@ -1,5 +1,7 @@ # NetReach +[**English**](./netreach.md) | **简体中文** + ## 基本描述 对于这种任务，每个kdoctor agent都会相互发送http请求，请求地址为每一个 agent 的 pod ip 、service ip、ingress ip 等等，并获得成功率和平均延迟。它可以指定成功条件来判断结果是否成功。并且，可以通过聚合API获取详细的报告。 @@ -22,7 +24,7 @@ spec: schedule: roundNumber: 1 roundTimeoutMinute: 1 - schedule: 0 0 + schedule: 0 1 target: clusterIP: true enableLatencyMetric: false diff --git a/docs/reference/netreach.md b/docs/reference/netreach.md new file mode 100644 index 00000000..23276677 --- /dev/null +++ b/docs/reference/netreach.md @@ -0,0 +1,3 @@ +# NetReach + +[**简体中文**](./netreach-zh_CN.md) | **English** diff --git a/docs/usage/apphttphealthy-zh_CN.md b/docs/usage/apphttphealthy-zh_CN.md new file mode 100644 index 00000000..79ec93ed --- /dev/null +++ b/docs/usage/apphttphealthy-zh_CN.md @@ -0,0 +1,296 @@ +# AppHttpHealthy + +[**English**](./apphttphealthy.md) | **简体中文** + +## 介绍 + +对于这种任务，每个 kdoctor agent 都会向指定的目标发送 http 请求，默认并发量为 50 可覆盖多副本情况，并发量可在 kodcotr 的 configmap 中设置，并获得成功率和平均延迟。根据成功条件来判断结果是否成功。并且，可以通过聚合API获取详细的报告。 + +1.应用场景： + +* 模拟生产需求，确认指定应用能够被集群的每一个角落访问到 +* 在应用部署阶段，用以配合调整应用的资源和副本数配置，以确认能够支撑期望的访问压力 +* 给指定应用注入压力，配合灰度发布、混沌测试、bug 复现等目的 +* 测试集群外部服务，确认集群 egress 工作正常 + + +2.关于 AppHttpHealthy CRD 的更多描述，可参考[AppHttpHealthy](../reference/apphttphealthy-zh_CN.md) + +3.功能列表: + +* 支持 HTTP、HTTPS、HTTP 2，能够定义 header、body + +## 开始 + +接下来将展示 `AppHttpHealthy` 的使用示例 + +### 安装 kdoctor + +参照[安装教程](./install-zh_CN.md)安装 kdoctor + +### 安装测试 server (选做) + +kdoctor 官方仓库中包含了一个名为 http-server-test 的应用，内包含 http server，https server, dns server 可用来测试 kdoctor 功能，若存在其他测试的 server 可跳过安装。 + +```shell +helm repo add kdoctor https://kdoctor-io.github.io/kdoctor +helm repo update kdoctor +helm install server-test kdoctor/http-server-test -n kdoctor --wait --debug --create-namespace +``` + +查看测试 server 状态 +```shell +kubectl get pod -n kdoctor -owide +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +http-server-test-7649566ff9-dv4jc 1/1 Running 0 76s 172.40.1.45 kdoctor-worker +http-server-test-7649566ff9-qc5dh 1/1 Running 0 76s 172.40.0.35 kdoctor-control-plane +``` + +获取测试 server 的 service 地址 +```shell +kubectl get service -n kdoctor +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +http-server-test ClusterIP 172.41.71.0 80/TCP,443/TCP,53/UDP,53/TCP,853/TCP 2m31s +``` + +### 创建 AppHttpHealthy + +创建 http `AppHttpHealthy` ，该任务将执行一轮持续 10s 的任务，任务会向指定的 server 以 qps 为 10 的速度发送 Get 请求，并且立即执行。 + +这里使用 http-server-test 的 service 地址，若有其他 server 地址 可使用其他 server 地址。 + +```shell +SERVER="172.41.71.0" +cat < 6m42s v1.27.1 + + ~# kubectll get po -n kdoctor + NAME READY STATUS RESTARTS AGE + kdoctor-agent-8mcs7 1/1 Running 0 2m33s + kdoctor-agent-lrwgt 1/1 Running 0 2m33s + kdoctor-controller-686b75d6d7-ktctx 1/1 Running 0 2m33s + ``` + +接下来您可以根据您的需要进行任务的布置 [AppHttpHealthy](./apphttphealthy-zh_CN.md)、[NetReach](./netreach-zh_CN.md)、[NetDns](./netdns-zh_CN.md) + +## 卸载 + +* 卸载 Kind 集群 + + 执行 `make e2e_clean` 卸载 Kind 集群。 + diff --git a/docs/usage/get-started-kind.md b/docs/usage/get-started-kind.md new file mode 100644 index 00000000..cfde64f1 --- /dev/null +++ b/docs/usage/get-started-kind.md @@ -0,0 +1,3 @@ +# Kind Quick Start + +[**简体中文**](./get-started-kind-zh_CN.md) | **English** diff --git a/docs/usage/install-zh_CN.md b/docs/usage/install-zh_CN.md index 63453c9c..0f3af27a 100644 --- a/docs/usage/install-zh_CN.md +++ b/docs/usage/install-zh_CN.md @@ -1,5 +1,7 @@ # 安装文档 +[**English**](./install.md) | **简体中文** + ## 介绍 安装 kdoctor 对集群内外的网络及性能进行检查 @@ -29,7 +31,7 @@ kdoctor 可以根据不同的需求进行安装，以下为几个场景的推荐 以下方法 kdoctor agent 只将报告打印到标准输出 ```shell helm install kdoctor kdoctor/kdoctor \ - -n kdoctor --wait --debug --create-namespace + -n kdoctor --debug --create-namespace ``` #### 2.高可用安装 @@ -38,7 +40,7 @@ helm install kdoctor kdoctor/kdoctor \ ```shell helm install kdoctor kdoctor/kdoctor \ - -n kdoctor --wait --debug --create-namespace \ + -n kdoctor --debug --create-namespace \ --set kdoctorController.replicas=2 \ --set feature.aggregateReport.controller.pvc.enabled=true \ --set feature.aggregateReport.controller.pvc.storageClass=local-path \ diff --git a/docs/usage/install.md b/docs/usage/install.md index cfc8f6f7..15726bd1 100644 --- a/docs/usage/install.md +++ b/docs/usage/install.md @@ -1,5 +1,7 @@ # install +[**简体中文**](./install-zh_CN.md) | **English** + ## production env diff --git a/docs/usage/netdns-zh_CN.md b/docs/usage/netdns-zh_CN.md new file mode 100644 index 00000000..0ad91440 --- /dev/null +++ b/docs/usage/netdns-zh_CN.md @@ -0,0 +1,250 @@ +# NetDns + +[**English**](./netdns.md) | **简体中文** + +## 介绍 + +对于这种任务，每个 kdoctor agent都会向指定的 dns server 发送 dns 请求，默认并发量为 50 可覆盖多副本情况，并发量可在 kodcotr 的 configmap 中设置，并获得成功率和平均延迟。根据成功条件来判断结果是否成功。并且，可以通过聚合API获取详细的报告。 + +1.应用场景： +* 生产或 E2E 环境下，检测集群每个角落可访问 coreDNS 服务 +* 在应用部署阶段，用以配合调整 coredns 的资源和副本数量，以确认能够支撑期望的访问压力 +* 给 coredns 注入压力，配合 coredns 升级测试、混沌测试、bug 复现等目的 +* 测试集群外部的 dns 服务 + +2.关于 NetDns CRD 的更多描述，可参考[NetDns](../reference/netdns-zh_CN.md) + +3.功能列表: + +* 支持集群内外 dns server 测试 +* 支持 typeA 、typeAAAA 记录 +* 支持 udp、tcp、tcp-tls 协议 + +## 开始 + +接下来将展示 `NetDns` 的使用示例 + +### 安装 kdoctor + +参照[安装教程](./install-zh_CN.md)安装 kdoctor + +### 安装测试 server (选做) + +kdoctor 官方仓库中包含了一个名为 http-server-test 的应用，内包含 http server，https server, dns server 可用来测试 kdoctor 功能，若存在其他测试的 server 可跳过安装。 + +```shell +helm repo add kdoctor https://kdoctor-io.github.io/kdoctor +helm repo update kdoctor +helm install server-test kdoctor/http-server-test -n kdoctor-test-server --wait --debug --create-namespace +``` + +查看测试 server 状态 +```shell +kubectl get pod -n kdoctor -owide +NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +http-server-test-7649566ff9-dv4jc 1/1 Running 0 76s 172.40.1.45 kdoctor-worker +http-server-test-7649566ff9-qc5dh 1/1 Running 0 76s 172.40.0.35 kdoctor-control-plane +``` + +获取测试 server 的 service 地址 +```shell +kubectl get service -n kdoctor +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +http-server-test ClusterIP 172.41.71.0 80/TCP,443/TCP,53/UDP,53/TCP,853/TCP 2m31s +``` + +### 创建 NetDns + +创建 `NetDns` ，该任务将执行一轮持续 10s 的任务，任务会向集群内 dns server 以 qps 为 10 的速度使用 udp 协议，请求解析 `kubernetes.default.svc.cluster.local` 域名的 typeA 记录，并且立即执行。 + +```shell +cat <