Skip to content

docs: add kernel-native mode install guide to quick-start #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AAdIprog wants to merge 1 commit into
base: main
Choose a base branch
from
+39 −40
Open

docs: add kernel-native mode install guide to quick-start #268

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 39 additions & 40 deletions docs/setup/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -83,7 +86,10 @@ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \

## Install Kmesh

We offer several ways to install Kmesh:
We offer several ways to install Kmesh. Please choose your preferred mode:

<Tabs>
<TabItem value="dual-engine" label="Dual Engine (Default)" default>

### Option 1: Install from OCI Registry (Recommended)

Expand Down Expand Up @@ -119,28 +125,40 @@ kubectl create namespace kmesh-system
kubectl apply -f ./deploy/yaml/
```

You can confirm the status of Kmesh with the following command:
</TabItem>
<TabItem value="kernel-native" label="Kernel Native">

```shell
kubectl get pod -n kmesh-system
NAME READY STATUS RESTARTS AGE
kmesh-v2frk 1/1 Running 0 18h
```
> **Note**: Kernel-Native mode depends on enhanced kernel features (e.g., L7 traffic control). Please refer to [Use Enhanced Kernel](use-enhanced-kernel.md) to ensure your environment meets the requirements.

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
```
### Option 1: Install from Helm (Recommended)
Copy link

Copilot AI Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing an "Install from OCI Registry" option for the Kernel Native tab. While the Dual Engine tab provides this as Option 1 (Recommended), users following the Kernel Native instructions don't have an equivalent option explained. Consider adding instructions for how to install from the OCI registry with kernel-native mode, possibly using Helm's --set flag to override the mode parameter, or explicitly state that OCI registry installation is not recommended for kernel-native mode and explain why.

Copilot uses AI. Check for mistakes.

To install Kmesh in Kernel-Native mode, it is recommended to use the local Helm chart to easily modify the configuration.

1. Modify the startup mode to `kernel-native`:

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

@gemini-code-assist gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The sed -i command is not portable and will fail on macOS, which uses BSD sed. To improve the user experience for developers on macOS, please add a note about the difference. For example, you could add a note above the code block mentioning that macOS users should use sed -i '' 's/--mode=dual-engine/--mode=kernel-native/' ....

```

2. Install Kmesh:

```shell
helm install kmesh ./deploy/charts/kmesh-helm -n kmesh-system --create-namespace
```

### Option 2: Install from Yaml
Copy link

Copilot AI Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Install from Helm Chart Archive" option (Option 3) is missing from the Kernel Native tab. This creates an inconsistency with the Dual Engine tab which offers four installation options. Consider adding this option to maintain consistency, or explicitly state that not all installation methods are available for kernel-native mode.

Copilot uses AI. Check for mistakes.

1. Modify the startup mode in the Yaml configuration files (you may need to locate the specific DaemonSet configuration).
Copy link

@gemini-code-assist gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This instruction is too vague for a quick-start guide. Users may not know which file to look for or what to change. Please provide more specific instructions, similar to the Helm installation section. It would be helpful to specify the exact file in deploy/yaml/ to modify and show an example of the change (e.g., using sed or a diff).


Comment on lines +151 to +152
Copy link

Copilot AI Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction to modify the startup mode in Yaml configuration files is vague and unhelpful. Unlike the Helm option which provides a specific sed command, this option only mentions "you may need to locate the specific DaemonSet configuration" without providing concrete guidance on:

  1. Which file(s) to modify
  2. What the current value looks like
  3. What the new value should be
  4. The exact location within the file

Consider adding more specific instructions similar to the Helm option, or at least specify the file path and the parameter name to change.

Suggested change
1. Modify the startup mode in the Yaml configuration files (you may need to locate the specific DaemonSet configuration).
1. Open the Kmesh DaemonSet manifest under `deploy/yaml/` (for example, `deploy/yaml/kmesh-daemonset.yaml`) and update the startup mode:
- Locate the container `args` entry that contains `--mode=dual-engine`.
- Change it to `--mode=kernel-native`.
For example:
```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: kmesh-daemon
spec:
template:
spec:
containers:
- name: kmesh
args:
- "--mode=kernel-native"
```

Copilot uses AI. Check for mistakes.
2. Install Kmesh:

```shell
kubectl create namespace kmesh-system
kubectl apply -f ./deploy/yaml/
```

</TabItem>
</Tabs>

## Verify Installation

Expand Down Expand Up @@ -212,25 +230,6 @@ Verify CNI configuration:
cat /etc/cni/net.d/kmesh-cni-kubeconfig
```

## Change Kmesh Start Mode

Kmesh supports two start up 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.

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

We can use the following command to make the modification:

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

## 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.
Expand Down
Loading