Skip to main content

Quick Start Guide

This guide lets you quickly install Kmesh.

Prerequisites​

Before installing Kmesh, ensure your environment meets the following requirements:

RequirementVersionNotes
Kubernetes1.26+Tested on 1.26-1.29
Istio1.22+Tested on 1.22-1.25 (ambient mode required)
Helm3.0+For helm installation
Memory4GB+Recommended minimum
CPU2 coresRecommended minimum
Kernel5.10+For eBPF support

Preparation​

1. Kubernetes Cluster Preparation​

Kmesh requires a Kubernetes cluster (v1.26+). Choose one of the following methods to prepare your cluster:

We recommend using kind for quick local development and testing. See our Developing with kind guide for detailed Kmesh deployment instructions.

2. Istio Control Plane Installation​

Kmesh utilizes Istio 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.

Verify your Istio installation using the following command:

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

Note: To use Waypoints, you need to install the Kubernetes Gateway API CRDs, which do not come installed by default on most Kubernetes clusters:

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​

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:

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:
    • 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).

Verify Installation​

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:

kubectl get pod -n kmesh-system
NAME          READY   STATUS    RESTARTS   AGE
kmesh-v2frk   1/1     Running   0          18h

Check Istio components:

kubectl get pods -n istio-system
NAME                      READY   STATUS    RESTARTS   AGE
istiod-5659cfbd55-9s92d   1/1     Running   0          18h

Change Kmesh Start Mode​

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:

# ......
containers:
  kmeshDaemonArgs: "--mode=dual-engine --enable-bypass=false"
# ......

We can use the following command to make the modification:

sed -i 's/--mode=dual-engine/--mode=kernel-native/' deploy/charts/kmesh-helm/values.yaml

Deploy the Sample Applications​

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.

# Enable Kmesh for the specified namespace
kubectl label namespace default istio.io/dataplane-mode=Kmesh

Apply the following configuration to deploy sample sleep and httpbin applications:

kubectl apply -f ./samples/httpbin/httpbin.yaml
kubectl apply -f ./samples/sleep/sleep.yaml

Check the status of the applications:

kubectl get pod
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 checking the pod's annotations:

kubectl describe po -l app=httpbin | grep Annotations
Annotations:      kmesh.net/redirection: enabled

Test Service Access​

After the applications are managed by Kmesh, test that they can communicate successfully:

kubectl exec $(kubectl get pod -l app=sleep -o jsonpath='{.items[0].metadata.name}') -c sleep -- curl -IsS "http://httpbin:8000/status/200"
HTTP/1.1 200 OK
Server: gunicorn/19.9.0
Date: Sun, 28 Apr 2024 07:31:51 GMT
Connection: keep-alive
Content-Type: text/html; charset=utf-8
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Content-Length: 0

Note: 10.244.0.21 is the example IP of the httpbin pod.

Clean Up​

If you no longer wish to use Kmesh to manage applications in the namespace, you can remove the label and recreate the pods:

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
Annotations:      <none>

Delete Kmesh​

Select the uninstallation method corresponding to how you installed Kmesh:

If you installed Kmesh from the OCI registry:

helm uninstall kmesh -n kmesh-system
kubectl delete ns kmesh-system

To remove the sample sleep and httpbin applications:

kubectl delete -f samples/httpbin/httpbin.yaml
kubectl delete -f samples/sleep/sleep.yaml

If you installed the Gateway API CRDs, remove them:

kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl delete -f -