diff --git a/docs/developer-guide/Kmeshctl-usage/installation.md b/docs/developer-guide/Kmeshctl-usage/installation.md deleted file mode 100644 index bfa31220..00000000 --- a/docs/developer-guide/Kmeshctl-usage/installation.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Kmeshctl Installation -sidebar_position: 1 ---- - -## Installation - -### 1. From Release Binaries - -Pre-built binaries are available on our [releases page](https://github.com/kmesh-net/kmesh/releases). - -```bash -# For AMD64 / x86_64 -[ $(uname -m) = x86_64 ] && curl -Lo ./kmeshctl https://github.com/kmesh-net/kmesh/releases/download/v1.0.0/kmeshctl-linux-amd64 -# For ARM64 -[ $(uname -m) = aarch64 ] && curl -Lo ./kmeshctl https://github.com/kmesh-net/kmesh/releases/download/v1.0.0/kmeshctl-linux-arm64 -chmod +x ./kmeshctl -sudo mv ./kmeshctl /usr/local/bin/kmeshctl -``` - -### 2. From Source - -Kmeshctl is still in rapid development. If you want to try the latest features, you can directly build and install it from source. - -```bash -# Clone source code from github -git clone https://github.com/kmesh-net/kmesh.git - -# Build and install kmeshctl -cd kmesh/ -make kmeshctl -chmod +x ./kmeshctl -sudo mv ./kmeshctl /usr/local/bin/kmeshctl -``` - -## Commands Reference - -### kmeshctl accesslog - -Enable or disable Kmesh's accesslog - -```bash -kmeshctl accesslog [flags] -``` - -**Examples** - -```bash -# Enable Kmesh's accesslog: -kmeshctl accesslog enable - -# Disable Kmesh's accesslog: -kmeshctl accesslog disable -``` - -**Options** - -```bash - -h, --help help for accesslog -``` diff --git a/docs/developer-guide/website/versioning-doc.md b/docs/developer-guide/website/versioning-doc.md deleted file mode 100644 index 038121a5..00000000 --- a/docs/developer-guide/website/versioning-doc.md +++ /dev/null @@ -1,361 +0,0 @@ ---- -title: Version management -sidebar_position: 2 ---- - -# Versioning Documentation in Docusaurus: A Comprehensive Guide - -Docusaurus offers robust built-in support for versioning documentation, a critical feature for projects that evolve over time. Versioning allows you to maintain multiple versions of your documentation, ensuring users can access information relevant to the specific version of your software they are using. This comprehensive document will walk you through the process of setting up, managing, and optimizing versioned documentation in Docusaurus. - ---- - -## 1. Understanding Versioning in Docusaurus - -Docusaurus provides a straightforward system for versioning documentation: - -- **Current Version**: This is the latest, actively maintained version of your documentation, stored in the `docs/` folder. It typically represents the "Next" version or the most recent unreleased changes. -- **Versioned Docs**: These are snapshots of your documentation at specific points in time, usually tied to software releases. They are stored in folders named `versioned_docs/version-/`, such as `versioned_docs/version-1.0/` for version 1.0. - -For example: - -```text -// Project directory structure with versioning -my-docusaurus-project/ -├── docs/ # Current version documentation -├── versioned_docs/ # All versioned documentation -│ ├── version-1.0/ # Version 1.0 documentation -│ └── version-1.1/ # Version 1.1 documentation -├── versioned_sidebars/ # Sidebars for each version -│ ├── version-1.0-sidebars.json -│ └── version-1.1-sidebars.json -└── versions.json # List of all available versions -``` - -Each versioned set of documentation is a complete copy of the `docs/` folder at the time the version was created. - ---- - -## 2. Setting Up Versioning - -To begin versioning your documentation in Docusaurus, follow these steps: - -### Step 1: Create Your First Version - -When you're ready to release a new version of your software, create a versioned snapshot of your current documentation: - -- Run the following command in your terminal: - -```bash -# File: terminal command -npm run docusaurus docs:version -``` - -or - -```bash -# File: terminal command -yarn docusaurus docs:version -``` - -Replace `` with your desired version number, e.g., `1.0`. - -- **What Happens**: - - Docusaurus duplicates the entire `docs/` folder into `versioned_docs/version-1.0/`. - - It updates the `versions.json` file, which tracks all versioned documentation. - -Example `versions.json` after creating version 1.0: - -```json -// File: versions.json -[ - "1.0" -] -``` - -### Step 2: Customize Version Labels - -By default, the version number (e.g., "1.0") appears in the sidebar and version selector. You can customize these labels in `docusaurus.config.js`: - -```javascript -// File: docusaurus.config.js -module.exports = { - // ... other configuration - themeConfig: { - // ... other theme configuration - docs: { - sidebar: { - versionLabels: { - '1.0': 'Version 1.0 (Legacy)', - '1.1': 'Version 1.1', - 'current': 'Next (Unreleased)' - }, - }, - }, - }, -}; -``` - ---- - -## 3. Managing Versioned Documentation - -Once versioning is set up, you can manage your documentation as follows: - -### Updating Documentation - -- **Current Version**: Edit files in the `docs/` folder to reflect the latest changes and features. -- **Versioned Docs**: To update a specific version (e.g., for corrections or clarifications), modify files in `versioned_docs/version-/`. - -**Note**: Limit changes to versioned docs to minor fixes. Major updates should go into the current version (`docs/`). - -### Adding New Versions - -When releasing a new software version: - -```bash -# File: terminal command -# 1. Update docs/ folder with latest content -# 2. Run the versioning command -npm run docusaurus docs:version 2.0 -``` - -This creates a new snapshot in `versioned_docs/version-2.0/` and updates `versions.json`: - -```json -// File: versions.json (after adding version 2.0) -[ - "2.0", - "1.0" -] -``` - -### Removing Versions - -To delete a version: - -```bash -# File: terminal command -# 1. Remove the version folder -rm -rf versioned_docs/version-1.0 -rm -rf versioned_sidebars/version-1.0-sidebars.json - -# 2. Update versions.json manually -``` - -Edit `versions.json` to remove the version: - -```json -// File: versions.json (after removing version 1.0) -[ - "2.0" -] -``` - ---- - -## 4. Configuring the Sidebar for Versioned Docs - -Docusaurus handles sidebars for each version automatically, but you can customize them if needed. - -### Automatic Sidebar Generation - -When you create a version, Docusaurus automatically creates a sidebar configuration: - -```json -// File: versioned_sidebars/version-1.0-sidebars.json (automatically generated) -{ - "version-1.0/docs": [ - { - "type": "category", - "label": "Getting Started", - "items": [ - { - "type": "doc", - "id": "version-1.0/intro" - }, - { - "type": "doc", - "id": "version-1.0/installation" - } - ] - } - ] -} -``` - -### Manual Sidebar Configuration - -For more control, you can modify the versioned sidebar file directly: - -```javascript -// File: versioned_sidebars/version-1.0-sidebars.json (customized) -{ - "version-1.0/docs": [ - { - "type": "category", - "label": "Getting Started", - "items": [ - { - "type": "doc", - "id": "version-1.0/intro" - }, - { - "type": "doc", - "id": "version-1.0/installation" - } - ] - }, - { - "type": "category", - "label": "Advanced Topics", - "items": [ - { - "type": "doc", - "id": "version-1.0/advanced/configuration" - } - ] - } - ] -} -``` - ---- - -## 5. Linking to Versioned Docs - -### Version Dropdown Component - -Docusaurus adds a version selector dropdown to your site navigation: - -```jsx -// File: src/theme/Navbar.js (automatically handled by Docusaurus) -import React from 'react'; -import VersionsDropdown from '@theme/VersionsDropdown'; - -function Navbar() { - return ( - - ); -} -``` - -### Creating Custom Links to Specific Versions - -In your documentation, you can link to specific versions: - -```markdown - - -Check our [installation guide for v1.0](/docs/1.0/installation) or the [latest installation guide](/docs/installation). -``` - ---- - -## 6. Best Practices for Versioning - -- **Version Naming**: Use semantic versioning (e.g., 1.0, 1.1, 2.0) for clarity. - - ```text - // Recommended version naming - 1.0, 1.1, 2.0 // ✓ Semantic versioning - - // Not recommended - stable, beta, old // ✗ Ambiguous naming - ``` - -- **Configuration Example** for managing version labels and visibility: - - ```javascript - // File: docusaurus.config.js - module.exports = { - // ... other configuration - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - // ... other docs configuration - lastVersion: 'current', - versions: { - current: { - label: 'Next', - path: 'next', - }, - '2.0': { - label: '2.0', - path: '2.0', - }, - '1.0': { - label: '1.0 (Legacy)', - path: '1.0', - banner: 'unmaintained', // Adds a banner indicating this version is no longer maintained - }, - }, - }, - }, - ], - ], - }; - ``` - ---- - -## 7. Example Scenario - -Let's walk through versioning for a software project with two releases: 1.0 and 2.0. - -```bash -# File: terminal commands for versioning workflow -# Initial setup - create version 1.0 -npm run docusaurus docs:version 1.0 - -# Result: -# - versioned_docs/version-1.0/ contains a snapshot of docs/ -# - versioned_sidebars/version-1.0-sidebars.json is created -# - versions.json now includes "1.0" - -# Later - update docs/ with changes for version 2.0 and create version 2.0 -npm run docusaurus docs:version 2.0 - -# Result: -# - versioned_docs/version-2.0/ is created -# - versioned_sidebars/version-2.0-sidebars.json is created -# - versions.json now includes "2.0" and "1.0" -# - docs/ becomes the "Next" version -``` - -Final project structure: - -```text -# File: Project structure after versioning -my-docusaurus-project/ -├── docs/ # Current "Next" version -├── versioned_docs/ -│ ├── version-2.0/ # Version 2.0 documentation -│ └── version-1.0/ # Version 1.0 documentation -├── versioned_sidebars/ -│ ├── version-2.0-sidebars.json -│ └── version-1.0-sidebars.json -└── versions.json # ["2.0", "1.0"] -``` - -The result is a site where users can easily navigate between versions through the dropdown menu: - -- **Next**: Latest unreleased changes -- **2.0**: Documentation for version 2.0 -- **1.0 (Legacy)**: Documentation for version 1.0 - ---- - -## 8. Additional Resources - -For more in-depth information, refer to the official Docusaurus documentation: - -- [https://docusaurus.io/docs/versioning](https://docusaurus.io/docs/versioning) - ---- - -This guide provides everything you need to create and manage versioned documentation in Docusaurus. By following these steps, you can ensure your users have access to the right documentation for their software version. Happy documenting! diff --git a/docs/setup/quick-start.md b/docs/setup/quick-start.md index c0e153cb..f828a264 100644 --- a/docs/setup/quick-start.md +++ b/docs/setup/quick-start.md @@ -302,3 +302,479 @@ If you installed the Gateway API CRDs, remove them: ```shell kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=444631bfe06f3bcca5d0eadf1857eac1d369421d" | kubectl delete -f - ``` + +# Kmesh Installation Guide for macOS + +This guide provides comprehensive instructions for installing and developing Kmesh on macOS systems, including both Intel and Apple Silicon Macs. + +## Why This Guide Exists + +Kmesh is a high-performance service mesh data plane that relies on eBPF and Linux kernel features. Since macOS doesn't natively support these technologies, macOS users need to run Kmesh in a Linux environment using virtualization or containerization. + +## Prerequisites + +### System Requirements + +- **macOS**: 10.15+ (Intel) or 11.0+ (Apple Silicon) +- **Memory**: 16GB RAM recommended (8GB minimum) +- **Storage**: 64GB available disk space +- **Hardware**: Intel Mac or Apple Silicon (M1/M2/M3/M4) + +### Required Software + +- **Homebrew** (package manager) +- **UTM** (recommended for Apple Silicon) or **VMware Fusion/Parallels** (Intel) +- **Docker Desktop** (alternative approach) + +## Installation Methods + +### Method 1: UTM Virtual Machine (Recommended for Apple Silicon) + +UTM provides excellent ARM64 Linux virtualization on Apple Silicon Macs with near-native performance. + +#### Step 1: Install UTM + +```bash + +# Install via Homebrew +brew install --cask utm + +# Or download directly from https://mac.getutm.app/ +``` + +#### Step 2: Download Ubuntu Server + +```bash + +# For Apple Silicon (ARM64) +curl -LO https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04-live-server-arm64.iso + +# For Intel Macs (x86_64) +curl -LO https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04-live-server-amd64.iso +``` + +#### Step 3: Create Virtual Machine + +1. **Open UTM** and click "Create a New Virtual Machine" +2. **Select Type**: + - Apple Silicon: Choose **"Virtualize"** + - Intel Mac: Choose **"Emulate"** +3. **Choose OS**: Select **"Linux"** +4. **Select ISO**: Browse to your downloaded Ubuntu ISO +5. **Configure Resources**: + + ```bash + + Memory: 8GB minimum (16GB recommended) + CPU Cores: 4-6 cores + Storage: 64GB (SSD recommended) + Network: Shared Network + ``` + +6. **Enable Hardware Acceleration** (Apple Silicon only) + +#### Step 4: Install Ubuntu + +1. **Boot the VM** and follow Ubuntu Server installation +2. **Installation Options**: + - Choose **"Ubuntu Server (minimized)"** to save space + - Enable **SSH server** during installation + - Create a user with sudo privileges + - Skip snap packages for faster installation + +3. **Post-Installation Setup**: + + ```bash + + # Update system + sudo apt update && sudo apt upgrade -y + + # Install essential packages + sudo apt install -y curl wget vim git htop + ``` + +#### Step 5: Install Development Dependencies + +```bash +# Install build tools +sudo apt install -y \ + build-essential \ + clang \ + llvm \ + libelf-dev \ + libbpf-dev \ + pkg-config \ + protobuf-compiler \ + libprotobuf-c-dev \ + linux-headers-$(uname -r) + +# Install Docker +sudo apt install -y docker.io +sudo usermod -aG docker $USER +# Log out and back in for group changes + +# Install Go 1.22+ +wget https://go.dev/dl/go1.22.0.linux-arm64.tar.gz # ARM64 +# wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz # Intel + +sudo tar -C /usr/local -xzf go1.22.0.linux-*.tar.gz +echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc +echo 'export GOPATH=$HOME/go' >> ~/.bashrc +source ~/.bashrc + +# Verify installation +go version +docker --version +``` + +### Method 2: Docker Desktop (Intel and Apple Silicon) + +Docker Desktop provides a consistent containerized development environment across platforms. + +#### Step 1: Install Docker Desktop + +```bash +# Install via Homebrew +brew install --cask docker + +# Or download from https://www.docker.com/products/docker-desktop/ +``` + +#### Step 2: Configure Docker + +1. **Start Docker Desktop** +2. **Increase Resources** in Settings: + + ```bash + Memory: 8GB minimum + CPU: 4+ cores + Disk: 64GB + ``` + +3. **Enable Kubernetes** (optional, for testing) + +#### Step 3: Clone and Build Kmesh + +```bash +# Clone repository +git clone https://github.com/kmesh-net/kmesh.git +cd kmesh + +# Pull appropriate build image +# For Apple Silicon +docker pull ghcr.io/kmesh-net/kmesh-build-arm:latest + +# For Intel Mac +docker pull ghcr.io/kmesh-net/kmesh-build-x86:latest + +# Build Kmesh using Docker +make build + +# Verify build artifacts +ls out/arm64/ # or out/amd64/ for Intel +``` + +## Building Kmesh + +### Option 1: Build in VM (UTM Method) + +```bash +# Inside your Ubuntu VM +git clone https://github.com/kmesh-net/kmesh.git +cd kmesh + +# Generate BPF objects +cd bpf/kmesh/bpf2go +go generate ./... +cd ../../.. + +# Build Kmesh +make build + +# Build artifacts location +ls out/arm64/ # or out/amd64/ +``` + +### Option 2: Build with Docker + +```bash +# From macOS terminal, in Kmesh directory +make build + +# For custom build options +make build BUILD_OPTS="--mode=kernel-native" + +# Build Docker image +make docker +``` + +## Running Tests + +### Unit Tests + +```bash +# Using Docker (recommended) +./hack/run-ut.sh --docker + +# Or inside VM +./hack/run-ut.sh --local + +# Run specific tests +go test ./pkg/... -v +``` + +### BPF Unit Tests + +```bash +# Inside VM only (requires kernel headers) +make -C test/bpf_ut run +``` + +### Integration Tests + +```bash +# Requires Kubernetes cluster +go test ./test/e2e/... -v +``` + +## Setting Up Kubernetes + +### Option 1: kind (Kubernetes in Docker) + +```bash +# Install kind (inside VM or with Docker Desktop) +# For ARM64 +[ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-arm64 +# For x86_64 +[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64 + +chmod +x ./kind +sudo mv ./kind /usr/local/bin/kind + +# Create cluster +kind create cluster --config=deploy/kind/kind.yaml +``` + +### Option 2: minikube + +```bash +# Install minikube +curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-arm64 # ARM64 +# curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 # x86_64 + +sudo install minikube-linux-* /usr/local/bin/minikube + +# Start cluster +minikube start --driver=docker --memory=8192 --cpus=4 +``` + +## Troubleshooting + +### Common Build Issues + +#### Missing BPF Object Files + +```bash +# Error: pattern *.o: no matching files found +cd bpf/kmesh/bpf2go +go generate ./... + +# For all BPF programs +find bpf -name "*.go" -path "*/bpf2go/*" -exec dirname {} \; | sort -u | xargs -I {} sh -c 'cd {} && go generate' +``` + +#### Go Version Issues + +```bash +# Error: invalid go version '1.23.0' +# Edit go.mod and change "go 1.23.0" to "go 1.23" +sed -i 's/go 1\.23\.0/go 1.23/' go.mod +``` + +#### Docker Permission Issues + +```bash +# Error: permission denied while connecting to docker socket +sudo usermod -aG docker $USER +# Then logout and login again, or: +newgrp docker +``` + +#### Missing Dependencies + +```bash +# Install missing headers +sudo apt install -y linux-headers-$(uname -r) + +# For missing protobuf +sudo apt install -y protobuf-compiler libprotobuf-c-dev + +# For missing libelf +sudo apt install -y libelf-dev +``` + +### Performance Issues + +#### Slow VM Performance + +```bash +# For UTM on Apple Silicon +# 1. Ensure "Use Apple Virtualization" is enabled +# 2. Allocate maximum CPU cores +# 3. Use QCOW2 format with SSD option +# 4. Enable hardware acceleration + +# Check VM resource usage +htop +iostat -x 1 +``` + +#### Slow Docker Builds + +```bash +# Increase Docker Desktop resources +# Settings > Resources > Advanced +# Memory: 8GB+, CPU: 4+ cores + +# Use build cache +docker system prune -a --volumes # Clean up first +make build # Should be faster on subsequent runs +``` + +### Networking Issues + +#### VM Network Connectivity + +```bash +# Test connectivity +ping google.com +curl -I https://github.com + +# Fix DNS issues +sudo systemctl restart systemd-resolved +``` + +#### Docker Network Issues + +```bash +# Reset Docker network +docker network prune +docker system restart +``` + +## Development Workflow + +### Recommended Setup + +1. **Code Editor**: Use VS Code on macOS with Remote-SSH extension +2. **File Synchronization**: Set up shared folders between macOS and VM +3. **Terminal Access**: Use SSH for command-line access to VM + +### SSH Setup for VM + +```bash +# Get VM IP address (inside VM) +hostname -I + +# From macOS terminal +ssh username@ + +# Set up SSH key for passwordless access +ssh-copy-id username@ +``` + +### VS Code Remote Development + +```bash +# Install Remote-SSH extension in VS Code +# Connect to VM using Command Palette: +# "Remote-SSH: Connect to Host..." +# Enter: username@ +``` + +## Advanced Configuration + +### Custom Kernel Configuration + +If you need specific kernel features: + +```bash +# Check current kernel config +cat /boot/config-$(uname -r) | grep -i bpf + +# Install kernel with BPF features (usually enabled by default in Ubuntu) +sudo apt install -y linux-generic-hwe-22.04 +``` + +### Cross-Compilation + +```bash +# Build for different architectures +export GOARCH=arm64 +export GOOS=linux +make build + +# Reset to default +unset GOARCH GOOS +``` + +## Best Practices + +### Resource Management + +- **UTM VMs**: Allocate 50-70% of available RAM +- **Docker**: Limit resource usage to prevent macOS slowdown +- **Storage**: Use SSD-backed storage for better performance + +### Development Efficiency + +- **Use tmux/screen**: For persistent terminal sessions +- **Enable SSH keys**: For passwordless VM access +- **Set up aliases**: For common commands +- **Use Docker volumes**: For persistent data + +### Security Considerations + +- **Keep VM updated**: Regular security updates +- **Use SSH keys**: Instead of passwords +- **Firewall configuration**: Limit VM network exposure +- **Backup important data**: Regular backups of development work + +## Migration from Other Platforms + +### From Linux Native Development + +- VMs provide near-native Linux experience +- All existing scripts and workflows work unchanged +- Performance overhead is minimal on Apple Silicon + +### From Windows WSL + +- UTM provides better integration than WSL equivalents +- Full Linux kernel access for eBPF development +- More reliable networking and file system performance + +## Community Resources + +- **Kmesh GitHub**: https://github.com/kmesh-net/kmesh +- **Documentation**: https://kmesh.net/docs/ +- **UTM Support**: https://mac.getutm.app/support/ +- **Docker Desktop Docs**: https://docs.docker.com/desktop/mac/ + +## Contributing + +When contributing to Kmesh from macOS: + +1. **Test thoroughly**: Verify changes work in Linux environment +2. **Follow conventions**: Use Linux-style paths and commands in documentation +3. **Cross-platform awareness**: Consider impact on other platforms +4. **Documentation updates**: Update relevant guides when adding features + +--- + +**Next Steps**: Once your development environment is set up, proceed to the main [Quick Start Guide](../setup/quick-start.md) to install Kmesh in your Kubernetes cluster. + +```bash + +This comprehensive guide covers everything a macOS user needs to successfully develop with Kmesh, from initial setup through advanced configuration and troubleshooting. +```