From 942c10e22d5e09d04d1a97f85e877582e90cedaa Mon Sep 17 00:00:00 2001 From: vanshika2720 Date: Sun, 17 May 2026 16:26:16 +0530 Subject: [PATCH 1/2] docs: standardize and improve the getting started guide - Restructure quick-start guide using Docusaurus Tabs for cluster preparation, Istio installation, Kmesh installation, verification, and uninstallation sections - Use label selectors instead of hardcoded pod names for portability - Fix kubectl logs JSONPath to target first pod in multi-node clusters - Remove premature connectivity test from verification section - Separate commands from output into distinct code blocks - Synchronize install/uninstall tabs via shared groupId Signed-off-by: vanshika2720 --- docs/setup/quick-start.md | 384 +++++++++++++++++++++----------------- 1 file changed, 213 insertions(+), 171 deletions(-) diff --git a/docs/setup/quick-start.md b/docs/setup/quick-start.md index e8f2576fd..bf00d4dec 100644 --- a/docs/setup/quick-start.md +++ b/docs/setup/quick-start.md @@ -4,6 +4,9 @@ description: This guide lets you quickly install Kmesh. sidebar_position: 1 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Quick Start Guide This guide lets you quickly install Kmesh. @@ -12,217 +15,220 @@ This guide lets you quickly install Kmesh. Before installing Kmesh, ensure your environment meets the following requirements: -| Requirement | Version | Notes | -| ----------- | ------- | --------------------- | -| Kubernetes | 1.26+ | Tested on 1.26-1.29 | +| Requirement | Version | Notes | +| ----------- | ------- | ------------------------------------------- | +| Kubernetes | 1.26+ | Tested on 1.26-1.29 | | Istio | 1.22+ | Tested on 1.22-1.25 (ambient mode required) | -| Helm | 3.0+ | For helm installation | -| Memory | 4GB+ | Recommended minimum | -| CPU | 2 cores | Recommended minimum | -| Kernel | 5.10+ | For eBPF support | +| Helm | 3.0+ | For helm installation | +| Memory | 4GB+ | Recommended minimum | +| CPU | 2 cores | Recommended minimum | +| Kernel | 5.10+ | For eBPF support | ## Preparation -Kmesh needs to run on a Kubernetes cluster. Kubernetes 1.26+ are currently supported. We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) to quickly provide a Kubernetes cluster (We provide a [document](develop-with-kind/) for developing and deploying Kmesh using kind). Of course, you can also use [minikube](https://minikube.sigs.k8s.io/docs/) and other ways to create Kubernetes clusters. - -Currently, Kmesh makes use of [istio](https://istio.io/) as its control plane. Before installing Kmesh, please install the Istio control plane. We recommend installing istio ambient mode because Kmesh `dual-engine` mode need it. For details, see [ambient mode istio](https://istio.io/latest/docs/ops/ambient/getting-started/). - -You can view the results of istio installation using the following command: - -```shell -kubectl get po -n istio-system -NAME READY STATUS RESTARTS AGE -istio-cni-node-xbc85 1/1 Running 0 18h -istiod-5659cfbd55-9s92d 1/1 Running 0 18h -ztunnel-4jlvv 1/1 Running 0 18h -``` +### 1. Kubernetes Cluster Preparation -> **Note**: To use waypoint you need to install the Kubernetes Gateway API CRDs, which don't come installed by default on most Kubernetes clusters: +Kmesh requires a Kubernetes cluster (v1.26+). Choose one of the following methods to prepare your cluster: -```shell -kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ - { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } -``` + + + We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) for quick local development and testing. See our [Developing with kind](develop-with-kind/) guide for detailed Kmesh deployment instructions. + + + You can use [minikube](https://minikube.sigs.k8s.io/docs/) to create your local Kubernetes cluster. Ensure you configure sufficient CPU (2+ cores) and Memory (4GB+). + + + If you are using an existing managed or bare-metal Kubernetes cluster, ensure your kernel version is 5.10+ for eBPF support. + + -### Only install Istiod +### 2. Istio Control Plane Installation -Installing ambient mode istio by above steps will install additional istio components. +Kmesh utilizes [Istio](https://istio.io/) as its control plane. Choose your preferred Istio installation method: -The process of installing only `istiod` as the control plane for Kmesh is provided next. + + + We recommend installing Istio in ambient mode, as Kmesh's `dual-engine` mode requires it. For complete details, see the [Istio Ambient Mode Getting Started Guide](https://istio.io/latest/docs/ops/ambient/getting-started/). -#### Install Istio CRDs + Verify your Istio installation using the following command: -```shell -helm repo add istio https://istio-release.storage.googleapis.com/charts -helm repo update -``` + ```shell + kubectl get po -n istio-system + ``` -To install the chart with the release name `istio-base`: + ```console + NAME READY STATUS RESTARTS AGE + istio-cni-node-xbc85 1/1 Running 0 18h + istiod-5659cfbd55-9s92d 1/1 Running 0 18h + ztunnel-4jlvv 1/1 Running 0 18h + ``` -```shell -kubectl create namespace istio-system -helm install istio-base istio/base -n istio-system -``` + > **Note**: To use Waypoints, you need to install the Kubernetes Gateway API CRDs, which do not come installed by default on most Kubernetes clusters: -#### Install Istiod + ```shell + kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } + ``` -To install the chart with the release name `istiod`: + + + Installing ambient mode via the standard steps installs additional components like `ztunnel`. If you prefer a minimal installation with only `istiod` as the control plane for Kmesh: -```shell -helm install istiod istio/istiod --namespace istio-system --version 1.24.0 --set pilot.env.PILOT_ENABLE_AMBIENT=true -``` + **1. Install Istio CRDs** -> **Important:** Must set `pilot.env.PILOT_ENABLE_AMBIENT=true`. otherwise Kmesh will not be able to establish grpc links with istiod! If you want to use the Waypoint feature, you should use the istio version 1.23 ~ 1.25. + ```shell + helm repo add istio https://istio-release.storage.googleapis.com/charts + helm repo update + kubectl create namespace istio-system + helm install istio-base istio/base -n istio-system + ``` -After installing istiod, it's time to install Kubernetes Gateway API CRDs. + **2. Install Istiod** -```shell -kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ - { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } -``` + ```shell + helm install istiod istio/istiod --namespace istio-system --version 1.24.0 --set pilot.env.PILOT_ENABLE_AMBIENT=true + ``` -## Install Kmesh + > **Important:** You must set `pilot.env.PILOT_ENABLE_AMBIENT=true`, otherwise Kmesh will not be able to establish gRPC connections with Istiod. If you plan to use the Waypoint feature, ensure you use Istio version 1.23 ~ 1.25. -We offer several ways to install Kmesh: + **3. Install Gateway API CRDs** -### Option 1: Install from OCI Registry (Recommended) + ```shell + kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } + ``` -You can install Kmesh directly from the GitHub Container Registry without cloning the repository: + + -```shell -helm install kmesh oci://ghcr.io/kmesh-net/kmesh-helm --version x.y.z -n kmesh-system --create-namespace -``` +## Install Kmesh -- Replace `x.y.z` with your desired version from [kmesh-helm packages](https://github.com/orgs/kmesh-net/packages/container/package/kmesh-helm): - - For stable releases, use a version like `v1.1.0`. - - For pre-releases, use a version like `v1.1.0-alpha`. - - Omit the `--version` flag to install the latest version (not recommended for production). +We offer several ways to install Kmesh. Select the method that best fits your environment: -### Option 2: Install from Helm + + + You can install Kmesh directly from the GitHub Container Registry without cloning the repository: -```shell -helm install kmesh ./deploy/charts/kmesh-helm -n kmesh-system --create-namespace -``` + ```shell + helm install kmesh oci://ghcr.io/kmesh-net/kmesh-helm --version x.y.z -n kmesh-system --create-namespace + ``` -### Option 3: Install from Helm Chart Archive + - Replace `x.y.z` with your desired version from [kmesh-helm packages](https://github.com/orgs/kmesh-net/packages/container/package/kmesh-helm): + - For stable releases, use a version like `v1.1.0`. + - For pre-releases, use a version like `v1.1.0-alpha`. + - Omit the `--version` flag to install the latest version (not recommended for production). -```shell -helm install kmesh ./kmesh-helm-.tgz -n kmesh-system --create-namespace -``` + + + If you have cloned the Kmesh repository locally: -- Download the `kmesh-helm-.tgz` archive from [GitHub Releases](https://github.com/kmesh-net/kmesh/releases). Replace `` in the command above with the version you downloaded (e.g., `v1.1.0`). + ```shell + helm install kmesh ./deploy/charts/kmesh-helm -n kmesh-system --create-namespace + ``` -### Option 4: Install from Yaml + + + Download the `kmesh-helm-.tgz` archive from [GitHub Releases](https://github.com/kmesh-net/kmesh/releases). Replace `` in the command below with the version you downloaded (e.g., `v1.1.0`): -```shell -kubectl create namespace kmesh-system -kubectl apply -f ./deploy/yaml/ -``` + ```shell + helm install kmesh ./kmesh-helm-.tgz -n kmesh-system --create-namespace + ``` -You can confirm the status of Kmesh with the following command: + + + If you prefer using standard Kubernetes manifests directly from a local clone: -```shell -kubectl get pod -n kmesh-system -NAME READY STATUS RESTARTS AGE -kmesh-v2frk 1/1 Running 0 18h -``` + ```shell + kubectl create namespace kmesh-system + kubectl apply -f ./deploy/yaml/ + ``` -View the running status of Kmesh service: - -```log -time="2024-04-25T13:17:40Z" level=info msg="bpf Start successful" subsys=manager -time="2024-04-25T13:17:40Z" level=info msg="controller Start successful" subsys=manager -time="2024-04-25T13:17:40Z" level=info msg="dump StartServer successful" subsys=manager -time="2024-04-25T13:17:40Z" level=info msg="start write CNI config\n" subsys="cni installer" -time="2024-04-25T13:17:40Z" level=info msg="kmesh cni use chained\n" subsys="cni installer" -time="2024-04-25T13:17:41Z" level=info msg="Copied /usr/bin/kmesh-cni to /opt/cni/bin." subsys="cni installer" -time="2024-04-25T13:17:41Z" level=info msg="kubeconfig either does not exist or is out of date, writing a new one" subsys="cni installer" -time="2024-04-25T13:17:41Z" level=info msg="wrote kubeconfig file /etc/cni/net.d/kmesh-cni-kubeconfig" subsys="cni installer" -time="2024-04-25T13:17:41Z" level=info msg="cni config file: /etc/cni/net.d/10-kindnet.conflist" subsys="cni installer" -time="2024-04-25T13:17:41Z" level=info msg="command Start cni successful" subsys=manager -``` + + ## Verify Installation -After installing Kmesh, verify all components are functioning correctly: - -### 1. Verify Core Components - -Check Kmesh pod status: - -```shell -kubectl get pod -n kmesh-system -NAME READY STATUS RESTARTS AGE -kmesh-v2frk 1/1 Running 0 18h -``` +After installing Kmesh, verify that all components are functioning correctly by checking the core components, pod integration, logs, and CNI configuration: -Check Istio components: - -```shell -kubectl get pods -n istio-system -NAME READY STATUS RESTARTS AGE -istiod-5659cfbd55-9s92d 1/1 Running 0 18h -``` + + + Check Kmesh pod status: -### 2. Verify Pod Integration + ```shell + kubectl get pod -n kmesh-system + ``` -Deploy a test pod and verify Kmesh annotation: + ```console + NAME READY STATUS RESTARTS AGE + kmesh-v2frk 1/1 Running 0 18h + ``` -```shell -kubectl describe po | grep Annotations -Annotations: kmesh.net/redirection: enabled -``` + Check Istio components: -### 3. Verify Service Connectivity + ```shell + kubectl get pods -n istio-system + ``` -Test service access using the sleep pod: + ```console + NAME READY STATUS RESTARTS AGE + istiod-5659cfbd55-9s92d 1/1 Running 0 18h + ``` -```shell -kubectl exec sleep-7656cf8794-xjndm -c sleep -- curl -IsS "http://httpbin:8000/status/200" -``` + + + Deploy a test pod and verify the Kmesh redirection annotation: -Expected response should show HTTP 200 OK status. + ```shell + kubectl describe po | grep Annotations + ``` -### 4. Verify Kmesh Service Logs + ```console + Annotations: kmesh.net/redirection: enabled + ``` -Check for successful initialization messages: + -```shell -kubectl logs -n kmesh-system $(kubectl get pods -n kmesh-system -o jsonpath='{.items.metadata.name}') -``` + + Check for successful initialization messages in the Kmesh daemon logs: -Look for these key messages: + ```shell + kubectl logs -n kmesh-system $(kubectl get pods -n kmesh-system -o jsonpath='{.items[0].metadata.name}') + ``` -- "bpf Start successful" -- "controller Start successful" -- "dump StartServer successful" -- "command Start cni successful" + Look for these key startup messages: + - `bpf Start successful` + - `controller Start successful` + - `dump StartServer successful` + - `command Start cni successful` -### 5. Verify CNI Configuration + + + Check the CNI binary installation: -Check CNI binary installation: + ```shell + ls -l /opt/cni/bin/kmesh-cni + ``` -```shell -ls -l /opt/cni/bin/kmesh-cni -``` + Verify the CNI kubeconfig: -Verify CNI configuration: + ```shell + cat /etc/cni/net.d/kmesh-cni-kubeconfig + ``` -```shell -cat /etc/cni/net.d/kmesh-cni-kubeconfig -``` + + ## Change Kmesh Start Mode -Kmesh supports two start up modes: `dual-engine` and `kernel-native`. +Kmesh supports two startup modes: `dual-engine` and `kernel-native`. -The specific mode to be used is defined in deploy/charts/kmesh-helm/values.yaml, and we can modify the startup parameters in that file. +The specific mode to be used is defined in `deploy/charts/kmesh-helm/values.yaml`, and we can modify the startup parameters in that file: ```yaml -...... - containers: - kmeshDaemonArgs: "--mode=dual-engine --enable-bypass=false" -...... +# ...... +containers: + kmeshDaemonArgs: "--mode=dual-engine --enable-bypass=false" +# ...... ``` We can use the following command to make the modification: @@ -233,45 +239,51 @@ sed -i 's/--mode=dual-engine/--mode=kernel-native/' deploy/charts/kmesh-helm/val ## Deploy the Sample Applications -Kmesh can manage pods in a namespace with a label `istio.io/dataplane-mode=Kmesh`, and meanwhile the pod should have no `istio.io/dataplane-mode=none` label. +Kmesh manages pods in namespaces labeled with `istio.io/dataplane-mode=Kmesh`, provided the pod does not have the `istio.io/dataplane-mode=none` label. ```shell # Enable Kmesh for the specified namespace kubectl label namespace default istio.io/dataplane-mode=Kmesh ``` -Apply the following configuration to deploy sleep and httpbin: +Apply the following configuration to deploy sample `sleep` and `httpbin` applications: ```shell kubectl apply -f ./samples/httpbin/httpbin.yaml - kubectl apply -f ./samples/sleep/sleep.yaml ``` -Check the applications status: +Check the status of the applications: ```shell kubectl get pod +``` + +```console NAME READY STATUS RESTARTS AGE httpbin-65975d4c6f-96kgw 1/1 Running 0 3h38m sleep-7656cf8794-8tp9n 1/1 Running 0 3h38m ``` -You can confirm if a pod is managed by Kmesh by looking at the pod's annotation. +You can confirm if a pod is managed by Kmesh by checking the pod's annotations: ```shell -kubectl describe po httpbin-65975d4c6f-96kgw | grep Annotations +kubectl describe po -l app=httpbin | grep Annotations +``` +```console Annotations: kmesh.net/redirection: enabled ``` ## Test Service Access -After the applications have been manage by Kmesh, we can test that they can still communicate successfully. +After the applications are managed by Kmesh, test that they can communicate successfully: ```shell -kubectl exec sleep-7656cf8794-xjndm -c sleep -- curl -IsS "http://httpbin:8000/status/200" +kubectl exec $(kubectl get pod -l app=sleep -o jsonpath='{.items[0].metadata.name}') -c sleep -- curl -IsS "http://httpbin:8000/status/200" +``` +```http HTTP/1.1 200 OK Server: gunicorn/19.9.0 Date: Sun, 28 Apr 2024 07:31:51 GMT @@ -282,36 +294,66 @@ Access-Control-Allow-Credentials: true Content-Length: 0 ``` -Note: 10.244.0.21 is the IP of httpbin +> **Note**: `10.244.0.21` is the example IP of the `httpbin` pod. ## Clean Up -If you don't want to use Kmesh to manage the application anymore, you can remove the labels from the namespace. +If you no longer wish to use Kmesh to manage applications in the namespace, you can remove the label and recreate the pods: ```shell kubectl label namespace default istio.io/dataplane-mode- -kubectl delete pod httpbin-65975d4c6f-96kgw sleep-7656cf8794-8tp9n -kubectl describe pod httpbin-65975d4c6f-h2r99 | grep Annotations +kubectl delete pod -l app=httpbin +kubectl delete pod -l app=sleep +kubectl describe pod -l app=httpbin | grep Annotations +``` +```console Annotations: ``` ### Delete Kmesh -If you installed Kmesh using any of the Helm options above: +Select the uninstallation method corresponding to how you installed Kmesh: -```shell -helm uninstall kmesh -n kmesh-system -kubectl delete ns kmesh-system -``` + + + If you installed Kmesh from the OCI registry: -If you installed Kmesh using yaml: + ```shell + helm uninstall kmesh -n kmesh-system + kubectl delete ns kmesh-system + ``` -```shell -kubectl delete -f ./deploy/yaml/ -``` + + + If you installed Kmesh using the local Helm chart: + + ```shell + helm uninstall kmesh -n kmesh-system + kubectl delete ns kmesh-system + ``` + + + + If you installed Kmesh using the Helm chart archive: + + ```shell + helm uninstall kmesh -n kmesh-system + kubectl delete ns kmesh-system + ``` + + + + If you installed Kmesh using YAML manifests: + + ```shell + kubectl delete -f ./deploy/yaml/ + ``` + + + -To remove the sleep and httpbin applications: +To remove the sample `sleep` and `httpbin` applications: ```shell kubectl delete -f samples/httpbin/httpbin.yaml From 5fe28de12e1a0a6d3ff3c1a80694458d084d9758 Mon Sep 17 00:00:00 2001 From: vanshika2720 Date: Sun, 17 May 2026 21:56:13 +0530 Subject: [PATCH 2/2] docs: clean up MDX structure and indentation inside Docusaurus Tabs Signed-off-by: vanshika2720 --- docs/setup/quick-start.md | 322 +++++++++++++++++++------------------- 1 file changed, 159 insertions(+), 163 deletions(-) diff --git a/docs/setup/quick-start.md b/docs/setup/quick-start.md index bf00d4dec..dd9de3bcc 100644 --- a/docs/setup/quick-start.md +++ b/docs/setup/quick-start.md @@ -31,15 +31,21 @@ Before installing Kmesh, ensure your environment meets the following requirement Kmesh requires a Kubernetes cluster (v1.26+). Choose one of the following methods to prepare your cluster: - - We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) for quick local development and testing. See our [Developing with kind](develop-with-kind/) guide for detailed Kmesh deployment instructions. - - - You can use [minikube](https://minikube.sigs.k8s.io/docs/) to create your local Kubernetes cluster. Ensure you configure sufficient CPU (2+ cores) and Memory (4GB+). - - - If you are using an existing managed or bare-metal Kubernetes cluster, ensure your kernel version is 5.10+ for eBPF support. - + + +We recommend using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) for quick local development and testing. See our [Developing with kind](develop-with-kind/) guide for detailed Kmesh deployment instructions. + + + + +You can use [minikube](https://minikube.sigs.k8s.io/docs/) to create your local Kubernetes cluster. Ensure you configure sufficient CPU (2+ cores) and Memory (4GB+). + + + + +If you are using an existing managed or bare-metal Kubernetes cluster, ensure your kernel version is 5.10+ for eBPF support. + + ### 2. Istio Control Plane Installation @@ -47,58 +53,57 @@ Kmesh requires a Kubernetes cluster (v1.26+). Choose one of the following method Kmesh utilizes [Istio](https://istio.io/) as its control plane. Choose your preferred Istio installation method: - - We recommend installing Istio in ambient mode, as Kmesh's `dual-engine` mode requires it. For complete details, see the [Istio Ambient Mode Getting Started Guide](https://istio.io/latest/docs/ops/ambient/getting-started/). + - Verify your Istio installation using the following command: +We recommend installing Istio in ambient mode, as Kmesh's `dual-engine` mode requires it. For complete details, see the [Istio Ambient Mode Getting Started Guide](https://istio.io/latest/docs/ops/ambient/getting-started/). - ```shell - kubectl get po -n istio-system - ``` +Verify your Istio installation using the following command: + +```shell +kubectl get po -n istio-system +NAME READY STATUS RESTARTS AGE +istio-cni-node-xbc85 1/1 Running 0 18h +istiod-5659cfbd55-9s92d 1/1 Running 0 18h +ztunnel-4jlvv 1/1 Running 0 18h +``` - ```console - NAME READY STATUS RESTARTS AGE - istio-cni-node-xbc85 1/1 Running 0 18h - istiod-5659cfbd55-9s92d 1/1 Running 0 18h - ztunnel-4jlvv 1/1 Running 0 18h - ``` +> **Note**: To use Waypoints, you need to install the Kubernetes Gateway API CRDs, which do not come installed by default on most Kubernetes clusters: - > **Note**: To use Waypoints, you need to install the Kubernetes Gateway API CRDs, which do not come installed by default on most Kubernetes clusters: +```shell +kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } +``` - ```shell - kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ - { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } - ``` + + - - - Installing ambient mode via the standard steps installs additional components like `ztunnel`. If you prefer a minimal installation with only `istiod` as the control plane for Kmesh: +Installing ambient mode via the standard steps installs additional components like `ztunnel`. If you prefer a minimal installation with only `istiod` as the control plane for Kmesh: - **1. Install Istio CRDs** +**1. Install Istio CRDs** - ```shell - helm repo add istio https://istio-release.storage.googleapis.com/charts - helm repo update - kubectl create namespace istio-system - helm install istio-base istio/base -n istio-system - ``` +```shell +helm repo add istio https://istio-release.storage.googleapis.com/charts +helm repo update +kubectl create namespace istio-system +helm install istio-base istio/base -n istio-system +``` - **2. Install Istiod** +**2. Install Istiod** - ```shell - helm install istiod istio/istiod --namespace istio-system --version 1.24.0 --set pilot.env.PILOT_ENABLE_AMBIENT=true - ``` +```shell +helm install istiod istio/istiod --namespace istio-system --version 1.24.0 --set pilot.env.PILOT_ENABLE_AMBIENT=true +``` - > **Important:** You must set `pilot.env.PILOT_ENABLE_AMBIENT=true`, otherwise Kmesh will not be able to establish gRPC connections with Istiod. If you plan to use the Waypoint feature, ensure you use Istio version 1.23 ~ 1.25. +> **Important:** You must set `pilot.env.PILOT_ENABLE_AMBIENT=true`, otherwise Kmesh will not be able to establish gRPC connections with Istiod. If you plan to use the Waypoint feature, ensure you use Istio version 1.23 ~ 1.25. - **3. Install Gateway API CRDs** +**3. Install Gateway API CRDs** - ```shell - kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ - { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } - ``` +```shell +kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl apply -f -; } +``` - + ## Install Kmesh @@ -106,44 +111,48 @@ Kmesh utilizes [Istio](https://istio.io/) as its control plane. Choose your pref We offer several ways to install Kmesh. Select the method that best fits your environment: - - You can install Kmesh directly from the GitHub Container Registry without cloning the repository: + + +You can install Kmesh directly from the GitHub Container Registry without cloning the repository: + +```shell +helm install kmesh oci://ghcr.io/kmesh-net/kmesh-helm --version x.y.z -n kmesh-system --create-namespace +``` + +- Replace `x.y.z` with your desired version from [kmesh-helm packages](https://github.com/orgs/kmesh-net/packages/container/package/kmesh-helm): + - For stable releases, use a version like `v1.1.0`. + - For pre-releases, use a version like `v1.1.0-alpha`. + - Omit the `--version` flag to install the latest version (not recommended for production). - ```shell - helm install kmesh oci://ghcr.io/kmesh-net/kmesh-helm --version x.y.z -n kmesh-system --create-namespace - ``` + + - - Replace `x.y.z` with your desired version from [kmesh-helm packages](https://github.com/orgs/kmesh-net/packages/container/package/kmesh-helm): - - For stable releases, use a version like `v1.1.0`. - - For pre-releases, use a version like `v1.1.0-alpha`. - - Omit the `--version` flag to install the latest version (not recommended for production). +If you have cloned the Kmesh repository locally: + +```shell +helm install kmesh ./deploy/charts/kmesh-helm -n kmesh-system --create-namespace +``` - - - If you have cloned the Kmesh repository locally: + + - ```shell - helm install kmesh ./deploy/charts/kmesh-helm -n kmesh-system --create-namespace - ``` +Download the `kmesh-helm-.tgz` archive from [GitHub Releases](https://github.com/kmesh-net/kmesh/releases). Replace `` in the command below with the version you downloaded (e.g., `v1.1.0`): - - - Download the `kmesh-helm-.tgz` archive from [GitHub Releases](https://github.com/kmesh-net/kmesh/releases). Replace `` in the command below with the version you downloaded (e.g., `v1.1.0`): +```shell +helm install kmesh ./kmesh-helm-.tgz -n kmesh-system --create-namespace +``` - ```shell - helm install kmesh ./kmesh-helm-.tgz -n kmesh-system --create-namespace - ``` + + - - - If you prefer using standard Kubernetes manifests directly from a local clone: +If you prefer using standard Kubernetes manifests directly from a local clone: - ```shell - kubectl create namespace kmesh-system - kubectl apply -f ./deploy/yaml/ - ``` +```shell +kubectl create namespace kmesh-system +kubectl apply -f ./deploy/yaml/ +``` - + ## Verify Installation @@ -151,71 +160,66 @@ We offer several ways to install Kmesh. Select the method that best fits your en After installing Kmesh, verify that all components are functioning correctly by checking the core components, pod integration, logs, and CNI configuration: - - Check Kmesh pod status: + - ```shell - kubectl get pod -n kmesh-system - ``` +Check Kmesh pod status: - ```console - NAME READY STATUS RESTARTS AGE - kmesh-v2frk 1/1 Running 0 18h - ``` +```shell +kubectl get pod -n kmesh-system +NAME READY STATUS RESTARTS AGE +kmesh-v2frk 1/1 Running 0 18h +``` - Check Istio components: +Check Istio components: - ```shell - kubectl get pods -n istio-system - ``` +```shell +kubectl get pods -n istio-system +NAME READY STATUS RESTARTS AGE +istiod-5659cfbd55-9s92d 1/1 Running 0 18h +``` + + + - ```console - NAME READY STATUS RESTARTS AGE - istiod-5659cfbd55-9s92d 1/1 Running 0 18h - ``` +Deploy a test pod and verify the Kmesh redirection annotation: - - - Deploy a test pod and verify the Kmesh redirection annotation: +```shell +kubectl describe po | grep Annotations +Annotations: kmesh.net/redirection: enabled +``` - ```shell - kubectl describe po | grep Annotations - ``` + + - ```console - Annotations: kmesh.net/redirection: enabled - ``` +Check for successful initialization messages in the Kmesh daemon logs: - +```shell +kubectl logs -n kmesh-system $(kubectl get pods -n kmesh-system -o jsonpath='{.items[0].metadata.name}') +``` - - Check for successful initialization messages in the Kmesh daemon logs: +Look for these key startup messages: - ```shell - kubectl logs -n kmesh-system $(kubectl get pods -n kmesh-system -o jsonpath='{.items[0].metadata.name}') - ``` +- `bpf Start successful` +- `controller Start successful` +- `dump StartServer successful` +- `command Start cni successful` - Look for these key startup messages: - - `bpf Start successful` - - `controller Start successful` - - `dump StartServer successful` - - `command Start cni successful` + + - - - Check the CNI binary installation: +Check the CNI binary installation: - ```shell - ls -l /opt/cni/bin/kmesh-cni - ``` +```shell +ls -l /opt/cni/bin/kmesh-cni +``` - Verify the CNI kubeconfig: +Verify the CNI kubeconfig: - ```shell - cat /etc/cni/net.d/kmesh-cni-kubeconfig - ``` +```shell +cat /etc/cni/net.d/kmesh-cni-kubeconfig +``` - + ## Change Kmesh Start Mode @@ -257,9 +261,6 @@ Check the status of the applications: ```shell kubectl get pod -``` - -```console NAME READY STATUS RESTARTS AGE httpbin-65975d4c6f-96kgw 1/1 Running 0 3h38m sleep-7656cf8794-8tp9n 1/1 Running 0 3h38m @@ -269,9 +270,6 @@ You can confirm if a pod is managed by Kmesh by checking the pod's annotations: ```shell kubectl describe po -l app=httpbin | grep Annotations -``` - -```console Annotations: kmesh.net/redirection: enabled ``` @@ -281,9 +279,6 @@ After the applications are managed by Kmesh, test that they can communicate succ ```shell kubectl exec $(kubectl get pod -l app=sleep -o jsonpath='{.items[0].metadata.name}') -c sleep -- curl -IsS "http://httpbin:8000/status/200" -``` - -```http HTTP/1.1 200 OK Server: gunicorn/19.9.0 Date: Sun, 28 Apr 2024 07:31:51 GMT @@ -305,9 +300,6 @@ kubectl label namespace default istio.io/dataplane-mode- kubectl delete pod -l app=httpbin kubectl delete pod -l app=sleep kubectl describe pod -l app=httpbin | grep Annotations -``` - -```console Annotations: ``` @@ -316,41 +308,45 @@ Annotations: Select the uninstallation method corresponding to how you installed Kmesh: - - If you installed Kmesh from the OCI registry: + + +If you installed Kmesh from the OCI registry: - ```shell - helm uninstall kmesh -n kmesh-system - kubectl delete ns kmesh-system - ``` +```shell +helm uninstall kmesh -n kmesh-system +kubectl delete ns kmesh-system +``` - - - If you installed Kmesh using the local Helm chart: + + - ```shell - helm uninstall kmesh -n kmesh-system - kubectl delete ns kmesh-system - ``` +If you installed Kmesh using the local Helm chart: - - - If you installed Kmesh using the Helm chart archive: +```shell +helm uninstall kmesh -n kmesh-system +kubectl delete ns kmesh-system +``` - ```shell - helm uninstall kmesh -n kmesh-system - kubectl delete ns kmesh-system - ``` + + - - - If you installed Kmesh using YAML manifests: +If you installed Kmesh using the Helm chart archive: - ```shell - kubectl delete -f ./deploy/yaml/ - ``` +```shell +helm uninstall kmesh -n kmesh-system +kubectl delete ns kmesh-system +``` + + + + +If you installed Kmesh using YAML manifests: + +```shell +kubectl delete -f ./deploy/yaml/ +``` - + To remove the sample `sleep` and `httpbin` applications: