From 1df7ecde9c7bf6431690dca368c839b65f5fa162 Mon Sep 17 00:00:00 2001 From: Aaron U'Ren Date: Mon, 9 Mar 2026 21:01:43 -0500 Subject: [PATCH] doc: add table of contents to long markdown files --- Makefile | 9 ++++++-- docs/bgp.md | 21 +++++++++++++++++ docs/troubleshoot.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ docs/user-guide.md | 34 ++++++++++++++++++++++++++++ 4 files changed, 116 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 8cc9925f..45bb20f6 100644 --- a/Makefile +++ b/Makefile @@ -30,6 +30,8 @@ RUNTIME_BASE?=alpine:3.23 DOCKER_LINT_IMAGE?=golangci/golangci-lint:v2.8.0 # See Versions: https://hub.docker.com/r/tmknom/markdownlint/tags DOCKER_MARKDOWNLINT_IMAGE?=tmknom/markdownlint:0.45.0 +# See Versions: https://www.npmjs.com/package/doctoc +DOCTOC_VERSION=2.3.0 # See Versions: https://github.com/osrg/gobgp/releases GOBGP_VERSION=v4.2.0 QEMU_IMAGE?=multiarch/qemu-user-static @@ -66,7 +68,7 @@ FILE_ARCH=x86-64 DOCKER_ARCH= endif $(info Building for GOARCH=$(GOARCH)) -all: lint test-pretty kube-router container ## Default target. Lints code, runs tests, builds binaries and images. +all: doctoc lint test-pretty kube-router container ## Default target. Lints code, runs tests, builds binaries and images. kube-router: @echo Starting kube-router binary build. @@ -128,6 +130,9 @@ endif markdownlint: $(DOCKER) run -v $(PWD):/work $(DOCKER_MARKDOWNLINT_IMAGE) -- README.md docs +doctoc: ## Regenerates table of contents in docs that have doctoc markers. + $(DOCKER) run --rm -v $(PWD):/work -w /work node:alpine npx doctoc@$(DOCTOC_VERSION) docs/ --github --maxlevel 3 --notitle --update-only + run: kube-router ## Runs "kube-router --help". ./kube-router --help @@ -266,6 +271,6 @@ help: .PHONY: clean container run release goreleaser push gofmt gofmt-fix gomoqs .PHONY: test test-pretty lint docker-login push-manifest push-manifest-release -.PHONY: push-release github-release help multiarch-binverify markdownlint +.PHONY: push-release github-release help multiarch-binverify markdownlint doctoc .DEFAULT: all diff --git a/docs/bgp.md b/docs/bgp.md index 665f8948..ce1438c0 100644 --- a/docs/bgp.md +++ b/docs/bgp.md @@ -4,6 +4,27 @@ When kube-router is used to provide pod-to-pod networking, BGP is used to exchan provides flexible networking models to support different deployments (public vs private cloud, routable vs non-routable pod IPs, service IPs, etc.). + + + +- [Peering Within The Cluster](#peering-within-the-cluster) + - [Full Node-To-Node Mesh](#full-node-to-node-mesh) + - [Node-To-Node Peering Without Full Mesh](#node-to-node-peering-without-full-mesh) + - [Route-Reflector setup Without Full Mesh](#route-reflector-setup-without-full-mesh) +- [Peering Outside The Cluster](#peering-outside-the-cluster) + - [Global External BGP Peers](#global-external-bgp-peers) + - [Node Specific External BGP Peers](#node-specific-external-bgp-peers) + - [AS Path Prepending](#as-path-prepending) + - [BGP Peer Local IP configuration](#bgp-peer-local-ip-configuration) + - [BGP Peer Password Authentication](#bgp-peer-password-authentication) + - [BGP Communities](#bgp-communities) + - [Custom BGP Import Policy Reject](#custom-bgp-import-policy-reject) +- [BGP listen address list](#bgp-listen-address-list) +- [Overriding the next hop](#overriding-the-next-hop) +- [Overriding the next hop and enable IPIP/tunnel](#overriding-the-next-hop-and-enable-ipiptunnel) + + + ## Peering Within The Cluster ### Full Node-To-Node Mesh diff --git a/docs/troubleshoot.md b/docs/troubleshoot.md index 1124e28d..e798656c 100644 --- a/docs/troubleshoot.md +++ b/docs/troubleshoot.md @@ -4,6 +4,60 @@ This guide covers the most common issues encountered when running kube-router, b hundreds of real-world deployments. Each section describes symptoms, diagnostic commands, root causes, and solutions. + + + +- [General Diagnostic Tools](#general-diagnostic-tools) + - [Log Verbosity](#log-verbosity) + - [IPVS and Service Proxy](#ipvs-and-service-proxy) + - [ipset](#ipset) + - [iptables](#iptables) + - [BGP and Routing](#bgp-and-routing) + - [Network and Interfaces](#network-and-interfaces) + - [Observing Dropped Traffic](#observing-dropped-traffic) + - [Health Endpoint](#health-endpoint) +- [Prerequisites and Common Setup Issues](#prerequisites-and-common-setup-issues) + - [Required Kernel Modules](#required-kernel-modules) + - [iptables Backend: legacy vs nft](#iptables-backend-legacy-vs-nft) + - [iptables Version Compatibility](#iptables-version-compatibility) + - [Cleaning Up kube-proxy](#cleaning-up-kube-proxy) + - [Required Flags](#required-flags) +- [Service Proxy (IPVS) Issues](#service-proxy-ipvs-issues) + - [Services Showing "No Destination Available"](#services-showing-no-destination-available) + - ["No Route to Host" for Service IPs](#no-route-to-host-for-service-ips) + - [NodePort Not Accessible from Outside the Node](#nodeport-not-accessible-from-outside-the-node) + - [High CPU Usage with Many Services](#high-cpu-usage-with-many-services) + - [Hairpin NAT Not Working](#hairpin-nat-not-working) +- [BGP and Routing Issues](#bgp-and-routing-issues) + - [Routes Not Being Advertised](#routes-not-being-advertised) + - [Routes Lost After Network Interface Bounce](#routes-lost-after-network-interface-bounce) + - [Mismatched Local Address with External Peers](#mismatched-local-address-with-external-peers) + - [Slow BGP Convergence on Startup](#slow-bgp-convergence-on-startup) + - [Scaling Issues with Large Clusters](#scaling-issues-with-large-clusters) + - [PMTU / Path MTU Discovery Failures](#pmtu--path-mtu-discovery-failures) +- [Network Policy Issues](#network-policy-issues) + - [Egress Policy Blocking Service Access](#egress-policy-blocking-service-access) + - [Pods Have Network Access Before Policy is Applied](#pods-have-network-access-before-policy-is-applied) + - [ipBlock Not Matching Real Client IP](#ipblock-not-matching-real-client-ip) +- [Overlay and Tunnel Issues](#overlay-and-tunnel-issues) + - [Cross-Subnet Connectivity Failures](#cross-subnet-connectivity-failures) + - [MTU Issues with Tunnels](#mtu-issues-with-tunnels) +- [DSR (Direct Server Return) Issues](#dsr-direct-server-return-issues) + - [DSR with containerd / CRI-O](#dsr-with-containerd--cri-o) + - [Large Packet Failures with DSR](#large-packet-failures-with-dsr) + - [Policy Routing Setup Failures](#policy-routing-setup-failures) +- [System Integration Issues](#system-integration-issues) + - [systemd-networkd Purging Routes](#systemd-networkd-purging-routes) + - [Docker iptables Rules Conflicting](#docker-iptables-rules-conflicting) + - [CrashLoopBackOff and Liveness Probe Failures](#crashloopbackoff-and-liveness-probe-failures) + - [API Server Connectivity Loss](#api-server-connectivity-loss) +- [IPv6 and Dual-Stack Issues](#ipv6-and-dual-stack-issues) + - [Common Dual-Stack Pitfalls](#common-dual-stack-pitfalls) + - [IPv6 Route Advertisement Issues](#ipv6-route-advertisement-issues) +- [Getting Further Help](#getting-further-help) + + + ## General Diagnostic Tools Before diving into specific problems, familiarize yourself with these essential diagnostic commands. Most can be run diff --git a/docs/user-guide.md b/docs/user-guide.md index f7e57871..86bb2734 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,5 +1,39 @@ # User Guide + + + +- [Try kube-router with cluster installers](#try-kube-router-with-cluster-installers) + - [kops](#kops) + - [kubeadm](#kubeadm) + - [k0sproject](#k0sproject) + - [k3sproject](#k3sproject) + - [generic](#generic) + - [Amazon specific notes](#amazon-specific-notes) + - [Azure specific notes](#azure-specific-notes) +- [deployment](#deployment) +- [command line options](#command-line-options) +- [requirements](#requirements) +- [running as daemonset](#running-as-daemonset) +- [running as agent](#running-as-agent) +- [cleanup configuration](#cleanup-configuration) + - [Docker](#docker) + - [containerd](#containerd) +- [trying kube-router as alternative to kube-proxy](#trying-kube-router-as-alternative-to-kube-proxy) +- [Advertising IPs](#advertising-ips) +- [Controlling Service Locality / Traffic Policies](#controlling-service-locality--traffic-policies) +- [Hairpin Mode](#hairpin-mode) + - [Hairpin Mode Example](#hairpin-mode-example) +- [SNATing Service Traffic](#snating-service-traffic) +- [Load balancing Scheduling Algorithms](#load-balancing-scheduling-algorithms) +- [HostPort support](#hostport-support) +- [IPVS Graceful termination support](#ipvs-graceful-termination-support) +- [MTU](#mtu) +- [BGP configuration](#bgp-configuration) +- [Metrics](#metrics) + + + ## Try kube-router with cluster installers The best way to get started is to deploy Kubernetes with kube-router using a cluster installer.