Merge pull request #99 from hzxuzhonghu/update-quickstart

Update waypoint install

Author: kmesh-bot

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.

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 "<title>.*</title>"
@@ -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-
 ```
 

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
+    ```
 
 ### 应用基于权重的路由