integration: add the k3s Tailscale Kubernetes operator dimension

Add a k3s plus Tailscale Kubernetes operator integration dimension and
run TestK8sOperator in a dedicated CI job.

Author: kradalby

.github/workflows/gh-action-integration-generator.go

@@ -39,6 +39,27 @@ var testsToSplit = map[string][]string{
 	},
 }
 
+// testsExcludedFromMatrix are tests that must NOT be added to the shared
+// sqlite/postgres matrices because they have special runner requirements and
+// run in their own dedicated job. TestK8sOperator needs a runner that permits
+// privileged cgroup-v2 containers (it runs a real k3s cluster), which the
+// shared integration-test-template job is not guaranteed to provide.
+var testsExcludedFromMatrix = map[string]bool{
+	"TestK8sOperator": true,
+}
+
+// filterExcluded drops tests that run in their own dedicated job.
+func filterExcluded(tests []string) []string {
+	var kept []string
+	for _, test := range tests {
+		if testsExcludedFromMatrix[test] {
+			continue
+		}
+		kept = append(kept, test)
+	}
+	return kept
+}
+
 // expandTests takes a list of test names and expands any that need splitting
 // into multiple subtest patterns.
 func expandTests(tests []string) []string {
@@ -117,6 +138,9 @@ func updateYAML(tests []string, jobName string, testPath string) {
 func main() {
 	tests := findTests()
 
+	// Drop tests that run in their own dedicated job (special runner needs).
+	tests = filterExcluded(tests)
+
 	// Expand tests that should be split into multiple jobs
 	expandedTests := expandTests(tests)
 

.github/workflows/integration-test-template.yml

@@ -78,6 +78,12 @@ jobs:
           echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
           sudo systemctl restart docker
           docker version
+      - name: Load br_netfilter for in-cluster service routing
+        # TestK8sOperator runs k3s in a container; without br_netfilter on the
+        # host, bridged pod-to-pod traffic skips kube-proxy's ClusterIP DNAT and
+        # in-cluster DNS (kube-dns) is unreachable. The module cannot be loaded
+        # from inside the unprivileged-module rancher/k3s image, so load it here.
+        run: sudo modprobe br_netfilter
       - name: Login to Docker Hub
         env:
           DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}

.github/workflows/test-integration.yaml

@@ -403,3 +403,25 @@ jobs:
       test: ${{ matrix.test }}
       postgres_flag: "--postgres=1"
       database_name: "postgres"
+  # k8s-operator: TestK8sOperator stands up a real k3s cluster (rancher/k3s) as
+  # a privileged sibling container and installs the Tailscale Kubernetes
+  # operator via Helm against an in-test Headscale.
+  #
+  # PRIVILEGED-CI REQUIREMENT: this job MUST run on a runner that permits
+  # privileged containers with a writable cgroup-v2 hierarchy (k3s runs
+  # containerd, manages iptables/ipvs and mounts /sys/fs/cgroup). The standard
+  # GitHub-hosted ubuntu-24.04-arm runner used by the shared template supports
+  # this; self-hosted or hardened runners that disallow --privileged or remount
+  # /sys/fs/cgroup read-only will fail this test. It is kept out of the
+  # generator-managed sqlite/postgres matrices (see
+  # .github/workflows/gh-action-integration-generator.go) precisely because of
+  # this special requirement.
+  k8s-operator:
+    needs: [build, build-tailscale-released]
+    if: needs.build.outputs.files-changed == 'true'
+    uses: ./.github/workflows/integration-test-template.yml
+    secrets: inherit
+    with:
+      test: "TestK8sOperator"
+      postgres_flag: "--postgres=0"
+      database_name: "sqlite"

cmd/hi/cleanup.go

@@ -194,7 +194,8 @@ func isTestContainerName(names []string) bool {
 		if strings.Contains(name, "headscale-test-suite") ||
 			strings.Contains(name, "hs-") ||
 			strings.Contains(name, "ts-") ||
-			strings.Contains(name, "derp-") {
+			strings.Contains(name, "derp-") ||
+			strings.Contains(name, "k3s-") {
 			return true
 		}
 	}

cmd/hi/docker.go

@@ -735,7 +735,9 @@ func getCurrentTestContainers(containers []container.Summary, testContainerID st
 	for _, cont := range containers {
 		for _, name := range cont.Names {
 			containerName := strings.TrimPrefix(name, "/")
-			if strings.HasPrefix(containerName, "hs-") || strings.HasPrefix(containerName, "ts-") {
+			if strings.HasPrefix(containerName, "hs-") ||
+				strings.HasPrefix(containerName, "ts-") ||
+				strings.HasPrefix(containerName, "k3s-") {
 				// Check if container has matching run ID label
 				if cont.Labels != nil && cont.Labels["hi.run-id"] == runID {
 					testRunContainers = append(testRunContainers, testContainer{

cmd/hi/doctor.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/juanfont/headscale/integration/dockertestutil"
+	"github.com/juanfont/headscale/integration/k3sic"
 )
 
 const (
@@ -21,6 +22,7 @@ const (
 	nameDockerContext = "Docker Context"
 	nameDockerSocket  = "Docker Socket"
 	nameGolangImage   = "Golang Image"
+	nameK3sImage      = "K3s Image"
 	nameGoInstall     = "Go Installation"
 )
 
@@ -66,6 +68,7 @@ func runDoctorCheck(ctx context.Context) error {
 		results = append(results, checkDockerSocket(ctx))
 		results = append(results, checkDockerHubCredentials())
 		results = append(results, checkGolangImage(ctx))
+		results = append(results, checkK3sImage(ctx))
 	}
 
 	// Check 3: Go installation
@@ -242,6 +245,47 @@ func checkGolangImage(ctx context.Context) DoctorResult {
 	return pass(nameGolangImage, fmt.Sprintf("Golang image %s is now available", imageName))
 }
 
+// checkK3sImage verifies the rancher/k3s image used by TestK8sOperator is
+// available locally or can be pulled. Like the golang image, the public
+// rancher/k3s image is rate-limited on anonymous Docker Hub pulls, so this
+// check doubles as a reminder to configure Docker Hub credentials.
+func checkK3sImage(ctx context.Context) DoctorResult {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fail(nameK3sImage, "Cannot create Docker client for image check")
+	}
+	defer cli.Close()
+
+	imageName := k3sic.K3sImage
+
+	available, err := checkImageAvailableLocally(ctx, cli, imageName)
+	if err != nil {
+		return fail(
+			nameK3sImage,
+			fmt.Sprintf("Cannot check k3s image %s: %v", imageName, err),
+			"Check Docker daemon status",
+			"Try: docker images | grep rancher/k3s",
+		)
+	}
+
+	if available {
+		return pass(nameK3sImage, fmt.Sprintf("K3s image %s is available locally", imageName))
+	}
+
+	err = ensureImageAvailable(ctx, cli, imageName, false)
+	if err != nil {
+		return warn(
+			nameK3sImage,
+			fmt.Sprintf("K3s image %s not available locally and could not pull: %v", imageName, err),
+			"Only TestK8sOperator needs this image; other tests are unaffected",
+			"Configure Docker Hub credentials (docker login) to avoid rate limits",
+			"Try: docker pull "+imageName,
+		)
+	}
+
+	return pass(nameK3sImage, fmt.Sprintf("K3s image %s is now available", imageName))
+}
+
 // checkGoInstallation verifies Go is installed and working.
 func checkGoInstallation(ctx context.Context) DoctorResult {
 	_, err := exec.LookPath("go")