diff --git a/content/en/docs/architecture/architecture.md b/content/en/docs/architecture/architecture.md index 967ecbe..93c8689 100644 --- a/content/en/docs/architecture/architecture.md +++ b/content/en/docs/architecture/architecture.md @@ -14,6 +14,6 @@ type: docs ![image](/docs/architecture/kmesh-arch.svg) The software architecture of Kmesh consists of the following components: -- Kmesh-daemon: The management program responsible for Kmesh lifecycle management, XDS protocol integration, observability, and other functions. -- Ebpf orchestiation: The traffic orchestration implemented based on eBPF, including routing, canary deployments, load balancing, and more. -- waypoint: Modify istio's waypoint to adapt to Kmesh protocols, responsible for L7 traffic governance. +- Kmesh-daemon: The daemon responsible for eBPF Orchestration lifecycle management, xDS protocol integration, observability, and other functions. +- eBPF Orchestration: The traffic orchestration implemented with eBPF, including dynamic routing, canary deployments, load balancing, etc. +- Waypoint: Based on istio's waypoint to adapt to Kmesh protocols, responsible for L7 traffic management. diff --git a/content/en/docs/userguide/install_waypoint.md b/content/en/docs/userguide/install_waypoint.md index da0dc7a..beed3a3 100644 --- a/content/en/docs/userguide/install_waypoint.md +++ b/content/en/docs/userguide/install_waypoint.md @@ -11,7 +11,7 @@ type: docs --- -To try capabilities of Kmesh L7, this is the basic doc to install waypoint. +If you want to make use of Kmesh L7 features, this is the prerequisites to install waypoint. ### Preparation @@ -57,7 +57,7 @@ reviews-v3-5c5cc7b6d-q4r5h 1/1 Running 0 72s sleep-9454cc476-86vgb 1/1 Running 0 62s ``` -5. Test boofinfo works as expected: +5. Test bookinfo works as expected: ```bash [root@ ~]# kubectl exec deploy/sleep -- curl -s http://productpage:9080/ | grep -o ".*" @@ -66,39 +66,31 @@ sleep-9454cc476-86vgb 1/1 Running 0 62s ### Install waypoint -Waypoints can be used at three granularities: namespace, service and pod. Also you could install multiple waypoints with different granularities under the same namespace. +Waypoints can be used at three granularity: namespace, service and pod. And you could also install multiple waypoints at different granularity within a namespace. +Below we will learn how to deploy different waypoints for different granularity. We can use `kmeshctl waypoint` subcommands to generate or apply waypoint. -#### Install waypoint in service granularity: +To enable a namespace, service or pod to use a waypoint, add the `istio.io/use-waypoint` label with a value of the waypoint name. +We can also specify a customized waypoint image with `--image`, by default this default to `ghcr.io/kmesh-net/waypoint:{VERSION}` -Deploy a waypoint for service `reviews`, so any traffic to that service will be mediated by that waypoint proxy +#### Configure a waypoint for a specific service: -***NOTE: There are breaking changes in waypoint capture mode between istio 1.22 and istio 1.21, so the following commands need to be run on at least istio 1.22.*** +Deploy a waypoint `reviews-svc-waypoint` for service `reviews`, so any traffic to `reviews` from a client managed by Kmesh will be mediated by the waypoint proxy ```bash -[root@ ~]# istioctl x waypoint apply -n default --name reviews-svc-waypoint -``` - -Label the `reviews` service to use the `reviews-svc-waypoint` waypoint: +[root@ ~]# kmeshctl waypoint apply --for service -n default --name=reviews-svc-waypoint -```bash -[root@ ~]# kubectl label service reviews istio.io/use-waypoint=reviews-svc-waypoint +waypoint default/reviews-svc-waypoint applied ``` -You can use `kubectl get pods` to see all the pods except waypoint are ready. **Then replace the waypoint image with the Kmesh customized image.** Based on istio-proxy, Kmesh adds an customized listener filter called [Kmesh_tlv](https://github.com/kmesh-net/waypoint/tree/master/source/extensions/filters/listener/kmesh_tlv), which will parse the custom TLV protocol encoded by Kmesh and obtain the target address and metadata to connect L4 and L7. +Label the `reviews` service to use `reviews-svc-waypoint` waypoint: ```bash -[root@ ~]# kubectl get gateways.gateway.networking.k8s.io -NAME CLASS ADDRESS PROGRAMMED AGE -reviews-svc-waypoint istio-waypoint 10.96.198.98 True 30m -``` +[root@ ~]# $ kubectl label service reviews istio.io/use-waypoint=reviews-svc-waypoint -**image replacement**: Add annotation "sidecar.istio.io/proxyImage: ghcr.io/kmesh-net/waypoint:latest" to the `reviews-svc-waypoint` gateway. - -```bash -[root@ ~]# kubectl annotate gateway reviews-svc-waypoint sidecar.istio.io/proxyImage=ghcr.io/kmesh-net/waypoint:latest +service/reviews labeled ``` -Then gateway pod will restart. Now Kmesh is L7 enabled! +After the waypoint is up and running, Kmesh L7 is enabled! ```bash [root@ ~]# kubectl get pods @@ -114,40 +106,29 @@ sleep-5577c64d7c-n7rxp 1/1 Running 0 30m ``` -#### Install waypoint in namespace granularity: +#### Configure waypoint for a specific namespace: -```bash -[root@ ~]# istioctl x waypoint apply -n default --name default-ns-waypoint -waypoint default/default-ns-waypoint applied - -[root@ ~]# kubectl label namespace default istio.io/use-waypoint=default-ns-waypoint -namespace/default labeled -``` - -***NOTE: Also need to replace the original image of waypoint with the Kmesh customized image.*** +Deploy a waypoint for the `default` namespace with default name `waypoint`. By specifying `--enroll-namespace`, the namespace will be labeled with `istio.io/use-waypoint=waypoint` ```bash -[root@ ~]# kubectl annotate gateway default-ns-waypoint sidecar.istio.io/proxyImage=ghcr.io/kmesh-net/waypoint:latest +[root@ ~]# kmeshctl waypoint apply -n default --enroll-namespace +waypoint default/waypoint applied +namespace default labels with "istio.io/use-waypoint: waypoint" ``` -Then any requests from any pods using the Kmesh, to any service running in `default` namespace, will be routed through that waypoint for L7 processing and policy enforcement. +#### Configure waypoint for a specific pod: + +Deploy a waypoint called reviews-v2-pod-waypoint for the `reviews-v2-5979c6fc9c-72bst` pod. -#### Install waypoint in pod granularity: ```bash -[root@ ~]# istioctl x waypoint apply -n default --name reviews-v2-pod-waypoint --for workload +[root@ ~]# kmeshctl waypoint apply -n default --name reviews-v2-pod-waypoint --for workload waypoint default/reviews-v2-pod-waypoint applied # Label the `reviews-v2` pod to use `reviews-v2-pod-waypoint` waypoint. -[root@ ~]# kubectl label pod -l version=v2,app=reviews istio.io/use-waypoint=reviews-v2-pod-waypoint +[root@ ~]# kubectl label pod reviews-v2-5979c6fc9c-72bst istio.io/use-waypoint=reviews-v2-pod-waypoint pod/reviews-v2-5b667bcbf8-spnnh labeled ``` -***NOTE: Also need to replace the original image of waypoint with the Kmesh customized image.*** - -```bash -[root@ ~]# kubectl annotate gateway reviews-v2-pod-waypoint sidecar.istio.io/proxyImage=ghcr.io/kmesh-net/waypoint:latest -``` - Now any requests from pods in the Kmesh to the `reviews-v2` pod IP will be routed through `reviews-v2-pod-waypoint` waypoint for L7 processing and policy enforcement. ### Cleanup @@ -156,22 +137,22 @@ If you are **not** planning to explore any follow-on tasks, go on with the clean 1. Remove waypoint: -#### Remove waypoint in service granularity +#### Remove waypoint for service ```bash -[root@ ~]# istioctl x waypoint delete reviews-svc-waypoint +[root@ ~]# kmeshctl waypoint delete reviews-svc-waypoint [root@ ~]# kubectl label service reviews istio.io/use-waypoint- ``` -#### Remove waypoint in namespace granularity +#### Remove waypoint for namespace ```bash -[root@ ~]# istioctl x waypoint delete default-ns-waypoint +[root@ ~]# kmeshctl waypoint delete waypoint [root@ ~]# kubectl label namespace default istio.io/use-waypoint- ``` -#### Remove waypoint in pod granularity +#### Remove waypoint for pod ```bash -[root@ ~]# istioctl x waypoint delete reviews-v2-pod-waypoint +[root@ ~]# kmeshctl waypoint delete reviews-v2-pod-waypoint [root@ ~]# kubectl label pod -l version=v2,app=reviews istio.io/use-waypoint- ``` diff --git a/content/zh/docs/userguide/try_waypoint.md b/content/zh/docs/userguide/try_waypoint.md index 10c0461..6b06d67 100644 --- a/content/zh/docs/userguide/try_waypoint.md +++ b/content/zh/docs/userguide/try_waypoint.md @@ -11,6 +11,8 @@ type: docs --- +如果想使用Kmesh双引擎模式的七层治理功能,请参考本文档安装waypoint。 + ### 准备 1. 部署Kmesh: @@ -64,31 +66,61 @@ sleep-9454cc476-86vgb 1/1 Running 0 62s 6. 部署waypoint: -为service account `bookinfo-reviews` 部署一个waypoint,这样所有发往service `reviews` 的流量都将被这个waypoint proxy接管 +Waypoint可以在三个粒度级别使用:命名空间、服务和Pod。您还可以在一个命名空间内以不同粒度安装多个waypoint。 以下是我们将学习如何为不同粒度部署不同waypoint的方法。我们可以使用`kmeshctl waypoint`子命令生成waypoint。 -```bash -[root@ ~]# istioctl x waypoint apply --service-account bookinfo-reviews -[root@ ~]# kubectl get pods -NAME READY STATUS RESTARTS AGE -bookinfo-reviews-istio-waypoint-5d544b6d54-v5tc9 1/1 Running 0 4s -details-v1-5f4d584748-bz42z 1/1 Running 0 4m35s -productpage-v1-564d4686f-2rjqc 1/1 Running 0 4m35s -ratings-v1-686ccfb5d8-dnzkf 1/1 Running 0 4m35s -reviews-v1-86896b7648-fqm4z 1/1 Running 0 4m35s -reviews-v2-b7dcd98fb-nn42q 1/1 Running 0 4m35s -reviews-v3-5c5cc7b6d-q4r5h 1/1 Running 0 4m35s -sleep-9454cc476-86vgb 1/1 Running 0 4m25s -``` +要配置命名空间、服务或Pod waypoint,请添加带有waypoint名称的`istio.io/use-waypoint`标签。 我们还可以使用`--image`指定自定义的waypoint镜像,默认情况下,这个镜像为ghcr.io/kmesh-net/waypoint:{VERSION}。 -用Kmesh自定义的镜像替换waypoint的原生镜像。基于istio-proxy,Kmesh增加了一个名为[Kmesh_tlv](https://github.com/kmesh-net/waypoint/tree/master/source/extensions/filters/listener/kmesh_tlv)的自定义listener filter,它会解析Kmesh编码的自定义TLV协议,从中获取目标地址以及元数据,从而能够连接L4和L7 +- 为特定服务配置waypoint: -```bash -[root@ ~]# kubectl get gateways.gateway.networking.k8s.io -NAME CLASS ADDRESS PROGRAMMED AGE -bookinfo-reviews istio-waypoint 10.96.207.125 True 8m36s -``` + 为服务reviews部署waypoint reviews-svc-waypoint,这样任何由Kmesh管理的客户端访问reviews的流量都会通过waypoint代理进行处理。 + + ```bash + [root@ ~]# kmeshctl waypoint apply --for service -n default --name=reviews-svc-waypoint + + waypoint default/reviews-svc-waypoint applied + ``` + + 为服务打上标签,使用刚创建的waypoint + + ```bash + [root@ ~]# $ kubectl label service reviews istio.io/use-waypoint=reviews-svc-waypoint + + service/reviews labeled + ``` + Waypoint 运行后, Kmesh 七层治理就绪! + + ```bash + [root@ ~]# kubectl get pods + NAME READY STATUS RESTARTS AGE + details-v1-cdd874bc9-xcdnj 1/1 Running 0 30m + productpage-v1-5bb9985d4d-z8cws 1/1 Running 0 30m + ratings-v1-6484d64bbc-pkv6h 1/1 Running 0 30m + reviews-svc-waypoint-8cb4bdbf-9d5mj 1/1 Running 0 30m + reviews-v1-598f9b58fc-2rw7r 1/1 Running 0 30m + reviews-v2-5979c6fc9c-72bst 1/1 Running 0 30m + reviews-v3-7bbb5b9cf7-952d8 1/1 Running 0 30m + sleep-5577c64d7c-n7rxp 1/1 Running 0 30m + ``` +- 为特定命名空间配置waypoint: + + 为default命名空间部署一个名为`waypoint`的waypoint。通过指定`--enroll-namespace`,该命名空间将被打上标签`istio.io/use-waypoint=waypoint`。 + ```bash + [root@ ~]# kmeshctl waypoint apply -n default --enroll-namespace + waypoint default/waypoint applied + namespace default labels with "istio.io/use-waypoint: waypoint" + ``` + +- 为特定pod配置waypoint: + + 为reviews-v2-5979c6fc9c-72bst Pod部署一个名为reviews-v2-pod-waypoint的waypoint。 -在`bookinfo-reviews` gateway的annotations当中添加sidecar.istio.io/proxyImage: ghcr.io/kmesh-net/waypoint-{arch}:v0.3.0,将{arch}转换为所在宿主机的架构,当前可选的取值为x86和arm。在gateway pod重启之后,Kmesh就具备L7能力了! + ```bash + [root@ ~]# kmeshctl waypoint apply -n default --name reviews-v2-pod-waypoint --for workload + waypoint default/reviews-v2-pod-waypoint applied + # Label the `reviews-v2` pod to use `reviews-v2-pod-waypoint` waypoint. + [root@ ~]# kubectl label pod reviews-v2-5979c6fc9c-72bst istio.io/use-waypoint=reviews-v2-pod-waypoint + pod/reviews-v2-5b667bcbf8-spnnh labeled + ``` ### 应用基于权重的路由