docs: add Support Matrix section under Get More Help (#764)

* Add Support Matrix section under Get More Help Adds /help/support-matrix with an overview, NetBird client (split into per-OS pages following the get-started/install layout), Kubernetes operator, Terraform provider, and self-hosted sub-sections. Linux/Windows/macOS pages pre-fill OS version cutoffs derived from the Go toolchain's minimum OS requirements at each NetBird release's Go version (sourced from go.mod at release tags). Each derived page carries a Warning callout marking the values as inferences pending team confirmation. Mobile/TV pages and the other component pages remain TBD placeholders. * Rework Linux support page around client modes Drops the per-distro TBD table and consolidates the description with the Warning callout. Splits Linux support by client mode: userspace follows the Go toolchain's minimum OS requirements; kernel mode depends on the host's iptables/nftables features. Notes Ubuntu 20.04 as the end-to-end test floor. * Add full Linux e2e test matrix to support page Replaces the single Ubuntu 20.04 floor reference with the full set of distributions covered by the NetBird team's end-to-end tests: Ubuntu 20.04/22.04/24.04, Debian 12, Rocky Linux 9, and Fedora 41. Ubuntu 20.04 remains called out as the oldest tested release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> ---------
2026-08-25 01:01:27 +02:00 · 2026-05-22 11:47:42 +02:00
parent 2cc722e436
commit a28e476670
13 changed files with 429 additions and 0 deletions
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -821,6 +821,60 @@ export const docsNavigation = [
        href: '/help/troubleshooting-client',
      },
      { title: 'Report bugs and issues', href: '/help/report-bug-issues' },
+      {
+        title: 'Support Matrix',
+        isOpen: false,
+        links: [
+          { title: 'Overview', href: '/help/support-matrix' },
+          {
+            title: 'NetBird Client',
+            href: '/help/support-matrix/netbird-client',
+            isOpen: false,
+            links: [
+              {
+                title: 'Linux',
+                href: '/help/support-matrix/netbird-client/linux',
+              },
+              {
+                title: 'Windows',
+                href: '/help/support-matrix/netbird-client/windows',
+              },
+              {
+                title: 'macOS',
+                href: '/help/support-matrix/netbird-client/macos',
+              },
+              {
+                title: 'iOS',
+                href: '/help/support-matrix/netbird-client/ios',
+              },
+              {
+                title: 'Android',
+                href: '/help/support-matrix/netbird-client/android',
+              },
+              {
+                title: 'Android TV',
+                href: '/help/support-matrix/netbird-client/android-tv',
+              },
+              {
+                title: 'tvOS',
+                href: '/help/support-matrix/netbird-client/tvos',
+              },
+            ],
+          },
+          {
+            title: 'Kubernetes Operator',
+            href: '/help/support-matrix/kubernetes-operator',
+          },
+          {
+            title: 'Terraform Provider',
+            href: '/help/support-matrix/terraform-provider',
+          },
+          {
+            title: 'Self-Hosted',
+            href: '/help/support-matrix/self-hosted',
+          },
+        ],
+      },
    ],
  },
 ]
--- a/src/pages/help/support-matrix/index.mdx
+++ b/src/pages/help/support-matrix/index.mdx
@@ -0,0 +1,49 @@
+import { Warning } from '@/components/mdx'
+import { Tiles } from '@/components/Tiles'
+
+export const description =
+  'Supported versions for NetBird client, integrations, and tooling.'
+
+# Support Matrix
+
+This page lists the versions of operating systems, runtimes, and platforms officially supported across NetBird's client, integrations, and tooling. Use it to confirm compatibility before deploying or upgrading.
+
+Each sub-page is maintained alongside its component and updated when support windows change.
+
+<Warning>
+  This support matrix is a work in progress. Entries may change as we finalize support windows with the team.
+</Warning>
+
+<Tiles
+  title="Components"
+  items={[
+    {
+      href: '/help/support-matrix/netbird-client',
+      name: 'NetBird Client',
+      description: 'Supported operating systems and Go versions.',
+    },
+    {
+      href: '/help/support-matrix/kubernetes-operator',
+      name: 'Kubernetes Operator',
+      description: 'Supported Kubernetes and NetBird control-plane versions.',
+    },
+    {
+      href: '/help/support-matrix/terraform-provider',
+      name: 'Terraform Provider',
+      description: 'Supported Terraform and NetBird API versions.',
+    },
+    {
+      href: '/help/support-matrix/self-hosted',
+      name: 'Self-Hosted',
+      description: 'Supported operating systems and dependencies for self-hosted deployments.',
+    },
+  ]}
+/>
+
+## How to read these tables
+
+- **Supported** — covered by bug fixes and security updates.
+- **Best-effort** — known to work; issues triaged but not prioritized.
+- **Unsupported** — outside the support window; upgrade recommended.
+
+If you need help confirming compatibility for a version not listed, see [Report bugs and issues](/help/report-bug-issues).
--- a/src/pages/help/support-matrix/kubernetes-operator.mdx
+++ b/src/pages/help/support-matrix/kubernetes-operator.mdx
@@ -0,0 +1,18 @@
+export const description =
+  'Kubernetes and NetBird control-plane versions supported by the NetBird Kubernetes operator.'
+
+# Kubernetes Operator Support Matrix
+
+## Kubernetes compatibility
+
+The NetBird Kubernetes operator targets the Kubernetes minor versions that are currently receiving patch releases from upstream. The [Kubernetes release policy](https://kubernetes.io/releases/) keeps release branches active for the three most recent minor versions, with roughly one year of patch support each — the operator tracks that same window.
+
+In practice this means the operator avoids depending on Kubernetes APIs or features that are not yet available across every supported minor version. When upstream drops a minor version from patch support, the operator may begin adopting capabilities that became generally available during that version's lifetime.
+
+## NetBird control-plane compatibility
+
+The operator is developed against the latest NetBird control-plane release. Older control-plane versions may continue to work, but compatibility is not actively verified outside the current release.
+
+## Reporting compatibility issues
+
+If you hit a problem on a supported combination, see [Report bugs and issues](/help/report-bug-issues). Include your operator version, Kubernetes version (`kubectl version`), and NetBird control-plane version.
--- a/src/pages/help/support-matrix/netbird-client/android-tv.mdx
+++ b/src/pages/help/support-matrix/netbird-client/android-tv.mdx
@@ -0,0 +1,23 @@
+import { Note } from '@/components/mdx'
+
+export const description =
+  'Supported Android TV versions for the NetBird client.'
+
+# Android TV
+
+The NetBird client supports the Android TV versions listed below.
+
+<Note>
+  Entries marked **TBD** will be filled in once the support windows are confirmed with the team.
+</Note>
+
+## Android TV versions
+
+| Version (API level) | Architectures | Version Supported |
+|---|---|---|
+| TBD | TBD | TBD |
+| TBD | TBD | TBD |
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your Android TV version, device model, and NetBird client version.
--- a/src/pages/help/support-matrix/netbird-client/android.mdx
+++ b/src/pages/help/support-matrix/netbird-client/android.mdx
@@ -0,0 +1,23 @@
+import { Note } from '@/components/mdx'
+
+export const description =
+  'Supported Android versions and architectures for the NetBird client.'
+
+# Android
+
+The NetBird client supports the Android versions listed below.
+
+<Note>
+  Entries marked **TBD** will be filled in once the support windows are confirmed with the team.
+</Note>
+
+## Android versions
+
+| Version (API level) | Architectures | Version Supported |
+|---|---|---|
+| TBD | TBD | TBD |
+| TBD | TBD | TBD |
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your Android version, device model, and NetBird client version.
--- a/src/pages/help/support-matrix/netbird-client/index.mdx
+++ b/src/pages/help/support-matrix/netbird-client/index.mdx
@@ -0,0 +1,70 @@
+import { Note } from '@/components/mdx'
+import { Tiles } from '@/components/Tiles'
+
+export const description =
+  'Operating systems and Go toolchain versions supported by the NetBird client.'
+
+# NetBird Client Support Matrix
+
+The NetBird client runs across desktop, mobile, and TV platforms. Pick an OS family below for its distributions, versions, and architectures.
+
+<Note>
+  Until this matrix is complete, also check the latest [Go-compatible platforms](https://go.dev/wiki/#platform-specific-information) alongside NetBird's own guidance.
+</Note>
+
+<Tiles
+  title="Operating systems"
+  items={[
+    {
+      href: '/help/support-matrix/netbird-client/linux',
+      name: 'Linux',
+      description: 'Distributions, kernel, and libc support.',
+    },
+    {
+      href: '/help/support-matrix/netbird-client/windows',
+      name: 'Windows',
+      description: 'Supported Windows versions and architectures.',
+    },
+    {
+      href: '/help/support-matrix/netbird-client/macos',
+      name: 'macOS',
+      description: 'Supported macOS releases and architectures.',
+    },
+    {
+      href: '/help/support-matrix/netbird-client/ios',
+      name: 'iOS',
+      description: 'Supported iOS versions and devices.',
+    },
+    {
+      href: '/help/support-matrix/netbird-client/android',
+      name: 'Android',
+      description: 'Supported Android API levels and architectures.',
+    },
+    {
+      href: '/help/support-matrix/netbird-client/android-tv',
+      name: 'Android TV',
+      description: 'Supported Android TV API levels.',
+    },
+    {
+      href: '/help/support-matrix/netbird-client/tvos',
+      name: 'tvOS',
+      description: 'Supported tvOS versions.',
+    },
+  ]}
+/>
+
+## Go toolchain
+
+The client is built with the Go versions listed below. Building from source against an unsupported Go release is not guaranteed to succeed. Each Go version sets a floor on OS support for that NetBird release — see the per-OS pages above for the resulting cutoffs.
+
+| NetBird client version | Go version |
+|---|---|
+| v0.20.0 – v0.25.3 | 1.20 |
+| v0.25.4 – v0.29.1 | 1.21 |
+| v0.29.2 – v0.60.2 | 1.23 |
+| v0.60.3 – v0.62.3 | 1.24 |
+| v0.63.0 – current | 1.25 |
+
+## Reporting compatibility issues
+
+If you hit a problem on a supported platform, see [Report bugs and issues](/help/report-bug-issues). Include your client version (`netbird version`) and OS details.
--- a/src/pages/help/support-matrix/netbird-client/ios.mdx
+++ b/src/pages/help/support-matrix/netbird-client/ios.mdx
@@ -0,0 +1,23 @@
+import { Note } from '@/components/mdx'
+
+export const description =
+  'Supported iOS versions for the NetBird client.'
+
+# iOS
+
+The NetBird client supports the iOS versions listed below.
+
+<Note>
+  Entries marked **TBD** will be filled in once the support windows are confirmed with the team.
+</Note>
+
+## iOS versions
+
+| Version | Devices | Version Supported |
+|---|---|---|
+| TBD | TBD | TBD |
+| TBD | TBD | TBD |
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your iOS version, device model, and NetBird client version.
--- a/src/pages/help/support-matrix/netbird-client/linux.mdx
+++ b/src/pages/help/support-matrix/netbird-client/linux.mdx
@@ -0,0 +1,37 @@
+import { Warning } from '@/components/mdx'
+
+export const description =
+  'Supported Linux kernel versions and modes for the NetBird client.'
+
+# Linux
+
+NetBird's Linux support depends on the client mode you run:
+
+- **Userspace mode** is supported wherever the Go toolchain is supported. The kernel floor for each NetBird release follows Go's minimum OS requirements (see the table below).
+- **Kernel mode** depends on the iptables / nftables features available on the host distribution.
+
+The NetBird team's end-to-end tests cover the distributions below — **Ubuntu 20.04** is the oldest tested release:
+
+- Ubuntu 20.04, 22.04, 24.04
+- Debian 12
+- Rocky Linux 9
+- Fedora 41
+
+Other distributions are not actively tested; their compatibility follows the mode-specific rules above.
+
+<Warning>
+  The kernel range below is derived from Go's [minimum OS requirements](https://go.dev/wiki/MinimumRequirements) per NetBird release's Go version, and applies to userspace mode. Kernel mode may have stricter requirements depending on the distribution — confirm with the team for production deployments.
+</Warning>
+
+## Linux kernel (userspace mode)
+
+| Kernel range | NetBird release range |
+|---|---|
+| 3.2 and newer | v0.60.3 onwards (Go 1.24+) |
+| 2.6.32 – 3.1 | ≤ v0.60.2 (Go ≤1.23) |
+
+The 2.6.32 floor primarily affected RHEL 6, CentOS 6, Ubuntu 14.04, and Debian 8 — all upstream EOL.
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your distro, kernel version (`uname -r`), and NetBird client version (`netbird version`).
--- a/src/pages/help/support-matrix/netbird-client/macos.mdx
+++ b/src/pages/help/support-matrix/netbird-client/macos.mdx
@@ -0,0 +1,24 @@
+import { Warning } from '@/components/mdx'
+
+export const description =
+  'Supported macOS versions and architectures for the NetBird client.'
+
+# macOS
+
+The NetBird client supports the macOS versions listed below. The floor moves whenever NetBird upgrades its Go toolchain and Go drops an older macOS release.
+
+<Warning>
+  The version cutoffs below are derived from the [Go toolchain's minimum OS requirements](https://go.dev/wiki/MinimumRequirements) for each NetBird release's Go version. NetBird may have stricter requirements than Go — confirm with the team before relying on them.
+</Warning>
+
+## macOS versions
+
+| Version | Architectures | Version Supported |
+|---|---|---|
+| macOS 12 Monterey and newer | x86_64, arm64 | NetBird latest |
+| macOS 11 Big Sur | x86_64, arm64 | ≤ v0.62.3 |
+| macOS 10.15 Catalina | x86_64 | ≤ v0.29.1 |
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your macOS version, hardware architecture, and NetBird client version (`netbird version`).
--- a/src/pages/help/support-matrix/netbird-client/tvos.mdx
+++ b/src/pages/help/support-matrix/netbird-client/tvos.mdx
@@ -0,0 +1,23 @@
+import { Note } from '@/components/mdx'
+
+export const description =
+  'Supported tvOS versions for the NetBird client.'
+
+# tvOS
+
+The NetBird client supports the tvOS versions listed below.
+
+<Note>
+  Entries marked **TBD** will be filled in once the support windows are confirmed with the team.
+</Note>
+
+## tvOS versions
+
+| Version | Devices | Version Supported |
+|---|---|---|
+| TBD | TBD | TBD |
+| TBD | TBD | TBD |
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your tvOS version, device model, and NetBird client version.
--- a/src/pages/help/support-matrix/netbird-client/windows.mdx
+++ b/src/pages/help/support-matrix/netbird-client/windows.mdx
@@ -0,0 +1,25 @@
+import { Warning } from '@/components/mdx'
+
+export const description =
+  'Supported Windows versions and architectures for the NetBird client.'
+
+# Windows
+
+Windows 10 and 11 run on the latest NetBird client. Windows 7 and 8 are frozen at NetBird **v0.25.3** — the last release built with Go 1.20, the last Go toolchain to target those Windows versions. Older Windows releases may continue to work on pinned client versions but are not covered by bug fixes or security updates.
+
+<Warning>
+  The version cutoffs below are derived from the [Go toolchain's minimum OS requirements](https://go.dev/wiki/MinimumRequirements) for each NetBird release's Go version. NetBird may have stricter requirements than Go — confirm with the team before relying on them.
+</Warning>
+
+## Windows versions
+
+| Version | Architectures | Version Supported |
+|---|---|---|
+| Windows 11 | x86_64, arm64 | NetBird latest |
+| Windows 10 / Server 2016 and newer | x86_64, arm64 | NetBird latest |
+| Windows 8 / Server 2012 / 2012 R2 | all | ≤ v0.25.3 |
+| Windows 7 / Server 2008 R2 | all | ≤ v0.25.3 |
+
+## Reporting compatibility issues
+
+See [Report bugs and issues](/help/report-bug-issues). Include your Windows build (`winver`) and NetBird client version (`netbird version`).
--- a/src/pages/help/support-matrix/self-hosted.mdx
+++ b/src/pages/help/support-matrix/self-hosted.mdx
@@ -0,0 +1,30 @@
+import { Note } from '@/components/mdx'
+
+export const description =
+  'Operating systems and dependencies supported for self-hosted NetBird deployments.'
+
+# Self-Hosted Support Matrix
+
+The self-hosted NetBird stack is tested against the operating systems and dependency versions listed below. Running outside the supported window may work but is not covered by bug fixes or security updates.
+
+<Note>
+  Entries marked **TBD** will be filled in once the support windows are confirmed with the team.
+</Note>
+
+## Operating systems
+
+| OS | Architectures | Version Supported | Status |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+| TBD | TBD | TBD | TBD |
+
+## Dependencies
+
+| Component | Minimum version | Version Supported | Status |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+| TBD | TBD | TBD | TBD |
+
+## Reporting compatibility issues
+
+If you hit a problem on a supported platform, see [Report bugs and issues](/help/report-bug-issues). Include your deployment topology, host OS, and NetBird version.
--- a/src/pages/help/support-matrix/terraform-provider.mdx
+++ b/src/pages/help/support-matrix/terraform-provider.mdx
@@ -0,0 +1,30 @@
+import { Note } from '@/components/mdx'
+
+export const description =
+  'Terraform and NetBird API versions supported by the NetBird Terraform provider.'
+
+# Terraform Provider Support Matrix
+
+The NetBird Terraform provider is tested against the Terraform CLI and NetBird API versions listed below. Running against an unsupported combination may work but is not covered by bug fixes or security updates.
+
+<Note>
+  Entries marked **TBD** will be filled in once the support windows are confirmed with the team.
+</Note>
+
+## Terraform CLI versions
+
+| Provider version | Minimum Terraform | Maximum Terraform | Status |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+| TBD | TBD | TBD | TBD |
+
+## NetBird API compatibility
+
+| Provider version | Minimum NetBird API | Latest tested | Status |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+| TBD | TBD | TBD | TBD |
+
+## Reporting compatibility issues
+
+If you hit a problem on a supported combination, see [Report bugs and issues](/help/report-bug-issues). Include your provider version, Terraform version (`terraform version`), and NetBird API version.