integration/tsric: add TailscaleRustInContainer package

Add TailscaleRustInContainer (tsric), a Rust-client counterpart to
integration/tsic. It runs the axum example from tailscale-rs in a
Docker container and exposes the same lifecycle hooks as tsic
(Shutdown, SaveLog, Execute, WriteFile) so integration tests can
treat it as any other Tailscale node.

Dockerfile.tailscale-rs clones tailscale-rs at build time, so no
local source checkout is required. The repo URL and ref are Docker
build arguments (TAILSCALE_RS_REPO, TAILSCALE_RS_REF) exposed as
tsric.WithRepo / tsric.WithRef options. The HEADSCALE_INTEGRATION_
TAILSCALE_RS_IMAGE environment variable provides an escape hatch for
using a pre-built image instead of building from source.

The default ref is upstream main. Two upstream changes wire the
example to a local headscale:

  - tailscale/tailscale-rs#109 — env fallback for control URL and
    auth key in the axum example (merged 2026-04-21)
  - tailscale/tailscale-rs#111 — plain-HTTP control-key fetching
    behind the ts_control insecure-keyfetch Cargo feature
    (merged 2026-04-22)

The Dockerfile patches the cloned root Cargo.toml to expose
ts_control's insecure-keyfetch through the tailscale crate so it
can be enabled when building the axum example, since headscale's
integration harness runs the control plane over plain HTTP.

Author: kradalby

Dockerfile.tailscale-rs

@@ -0,0 +1,28 @@
+FROM rust:1.94-bookworm AS builder
+
+# Build the tailscale-rs axum example from upstream main. The env var and
+# plain-HTTP control support needed to target a local headscale landed in
+# upstream PRs #109 and #111.
+ARG TAILSCALE_RS_REPO=https://github.com/tailscale/tailscale-rs.git
+ARG TAILSCALE_RS_REF=main
+
+WORKDIR /app
+RUN git clone --depth 1 --branch "$TAILSCALE_RS_REF" "$TAILSCALE_RS_REPO" .
+
+# Headscale runs the control plane over plain HTTP in integration tests.
+# Upstream tailscale-rs gates plain-HTTP control-key fetching behind
+# ts_control's `insecure-keyfetch` Cargo feature; expose it through the
+# root `tailscale` crate so it can be enabled when building the example.
+RUN sed -i '/^axum = \["dep:axum"\]/a insecure-keyfetch = ["ts_control/insecure-keyfetch"]' Cargo.toml
+
+RUN cargo build --release --features axum,insecure-keyfetch --example axum
+
+FROM debian:bookworm-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    iproute2 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/target/release/examples/axum /usr/local/bin/axum

integration/tsric/tsric.go

@@ -0,0 +1,349 @@
+// Package tsric provides a TailscaleRustInContainer (tsric) implementation
+// that runs the tailscale-rs axum example inside a Docker container for
+// integration testing with headscale.
+//
+// Unlike tsic (which runs the official Tailscale client), tsric runs a Rust
+// implementation of a Tailscale node. It does not have the `tailscale` CLI,
+// so verification is done externally via headscale API and peer connectivity.
+package tsric
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"strings"
+
+	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/juanfont/headscale/integration/dockertestutil"
+	"github.com/juanfont/headscale/integration/integrationutil"
+	"github.com/ory/dockertest/v3"
+	"github.com/ory/dockertest/v3/docker"
+)
+
+const (
+	tsricHashLength = 6
+	caCertRoot      = "/usr/local/share/ca-certificates"
+
+	// dockerfileName is the name of the Dockerfile used to build the
+	// tailscale-rs axum container. It lives in the headscale repo root
+	// and clones tailscale-rs from the public upstream repository.
+	dockerfileName = "Dockerfile.tailscale-rs"
+
+	// dockerContextPath is the path from integration/ to the headscale
+	// repo root where the Dockerfile lives and acts as the build context.
+	dockerContextPath = "../."
+
+	// Build-arg names forwarded to the Dockerfile for sourcing tailscale-rs.
+	buildArgRepo = "TAILSCALE_RS_REPO"
+	buildArgRef  = "TAILSCALE_RS_REF"
+)
+
+// getPrebuiltImage returns the pre-built tailscale-rs Docker image name if set.
+func getPrebuiltImage() string {
+	return os.Getenv("HEADSCALE_INTEGRATION_TAILSCALE_RS_IMAGE")
+}
+
+// TailscaleRustInContainer is a Docker container running the tailscale-rs
+// axum example, which joins a tailnet and serves HTTP on port 80.
+type TailscaleRustInContainer struct {
+	hostname string
+
+	pool      *dockertest.Pool
+	container *dockertest.Resource
+	network   *dockertest.Network
+
+	// Configuration
+	caCerts      [][]byte
+	headscaleURL string
+	authKey      string
+	extraHosts   []string
+	repo         string
+	ref          string
+}
+
+// Option represents optional settings for a TailscaleRustInContainer instance.
+type Option = func(c *TailscaleRustInContainer)
+
+// WithCACert adds a CA certificate to the trusted certificates of the container.
+func WithCACert(cert []byte) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.caCerts = append(t.caCerts, cert)
+	}
+}
+
+// WithNetwork sets the Docker container network.
+func WithNetwork(network *dockertest.Network) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.network = network
+	}
+}
+
+// WithHeadscaleURL sets the headscale control server URL.
+func WithHeadscaleURL(url string) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.headscaleURL = url
+	}
+}
+
+// WithAuthKey sets the pre-authentication key for joining the tailnet.
+func WithAuthKey(key string) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.authKey = key
+	}
+}
+
+// WithExtraHosts adds extra /etc/hosts entries to the container.
+func WithExtraHosts(hosts []string) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.extraHosts = append(t.extraHosts, hosts...)
+	}
+}
+
+// WithRepo overrides the tailscale-rs git repository URL used by the
+// Dockerfile. Defaults to the public github.com/tailscale/tailscale-rs.
+func WithRepo(url string) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.repo = url
+	}
+}
+
+// WithRef overrides the tailscale-rs git ref (branch, tag, commit) used
+// by the Dockerfile. Defaults to "main".
+func WithRef(ref string) Option {
+	return func(t *TailscaleRustInContainer) {
+		t.ref = ref
+	}
+}
+
+// buildEntrypoint constructs the container entrypoint command.
+//
+// The upstream axum example reads the control-server URL from the
+// TS_CONTROL_URL environment variable (clap env-arg) and takes the
+// requested hostname from the -H/--hostname flag. The auth key is
+// passed via -k. The key file (-c) is created on first run
+// automatically.
+func (t *TailscaleRustInContainer) buildEntrypoint() []string {
+	var commands []string
+
+	// Wait for network to be ready
+	commands = append(commands,
+		"while ! ip route show default >/dev/null 2>&1; do sleep 0.1; done")
+
+	// If CA certs are configured, wait for them to be written
+	if len(t.caCerts) > 0 {
+		commands = append(commands,
+			fmt.Sprintf("while [ ! -f %s/user-0.crt ]; do sleep 0.1; done", caCertRoot))
+	}
+
+	// Update CA certificates
+	commands = append(commands, "update-ca-certificates 2>/dev/null || true")
+
+	commands = append(commands,
+		fmt.Sprintf(`export TS_CONTROL_URL=%q`, t.headscaleURL),
+		"export TS_RS_EXPERIMENT=this_is_unstable_software",
+	)
+
+	axumCmd := "/usr/local/bin/axum -c /tmp/tsrs-keys.json -H " + t.hostname
+	if t.authKey != "" {
+		axumCmd += " -k " + t.authKey
+	}
+
+	commands = append(commands, "exec "+axumCmd)
+
+	return []string{"/bin/sh", "-c", strings.Join(commands, " ; ")}
+}
+
+// New creates and starts a new TailscaleRustInContainer instance.
+func New(
+	pool *dockertest.Pool,
+	opts ...Option,
+) (*TailscaleRustInContainer, error) {
+	hash, err := util.GenerateRandomStringDNSSafe(tsricHashLength)
+	if err != nil {
+		return nil, err
+	}
+
+	runID := dockertestutil.GetIntegrationRunID()
+
+	var hostname string
+
+	if runID != "" {
+		runIDShort := runID[len(runID)-6:]
+		hostname = fmt.Sprintf("tsrs-%s-%s", runIDShort, hash)
+	} else {
+		hostname = "tsrs-" + hash
+	}
+
+	t := &TailscaleRustInContainer{
+		hostname: hostname,
+		pool:     pool,
+	}
+
+	for _, opt := range opts {
+		opt(t)
+	}
+
+	if t.network == nil {
+		return nil, errors.New("tsric: no network set") //nolint:err113
+	}
+
+	if t.headscaleURL == "" {
+		return nil, errors.New("tsric: no headscale URL set") //nolint:err113
+	}
+
+	if t.authKey == "" {
+		return nil, errors.New("tsric: no auth key set") //nolint:err113
+	}
+
+	// Build the entrypoint
+	entrypoint := t.buildEntrypoint()
+
+	runOptions := &dockertest.RunOptions{
+		Name:       hostname,
+		Networks:   []*dockertest.Network{t.network},
+		Entrypoint: entrypoint,
+		ExtraHosts: append(t.extraHosts, "host.docker.internal:host-gateway"),
+		Env:        []string{},
+	}
+
+	// Add integration test labels
+	dockertestutil.DockerAddIntegrationLabels(runOptions, "tailscale-rs")
+
+	// Remove any existing container with this name
+	err = pool.RemoveContainerByName(hostname)
+	if err != nil {
+		return nil, err
+	}
+
+	var container *dockertest.Resource
+
+	if prebuiltImage := getPrebuiltImage(); prebuiltImage != "" {
+		// Use a pre-built image (set via HEADSCALE_INTEGRATION_TAILSCALE_RS_IMAGE)
+		log.Printf("Using pre-built tailscale-rs image: %s", prebuiltImage)
+
+		repo, tag, ok := strings.Cut(prebuiltImage, ":")
+		if !ok {
+			return nil, fmt.Errorf("tsric: invalid image format %q, expected repository:tag", prebuiltImage) //nolint:err113
+		}
+
+		runOptions.Repository = repo
+		runOptions.Tag = tag
+
+		container, err = pool.RunWithOptions(
+			runOptions,
+			dockertestutil.DockerRestartPolicy,
+			dockertestutil.DockerAllowLocalIPv6,
+			dockertestutil.DockerMemoryLimit,
+		)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"tsric: could not start pre-built tailscale-rs container %s: %w",
+				hostname, err,
+			)
+		}
+	} else {
+		// Build from the Dockerfile in the headscale repo root. The Dockerfile
+		// clones tailscale-rs from the public upstream repository at build
+		// time, so no local source checkout is required.
+		var buildArgs []docker.BuildArg
+
+		if t.repo != "" {
+			buildArgs = append(buildArgs, docker.BuildArg{Name: buildArgRepo, Value: t.repo})
+		}
+
+		if t.ref != "" {
+			buildArgs = append(buildArgs, docker.BuildArg{Name: buildArgRef, Value: t.ref})
+		}
+
+		buildOptions := &dockertest.BuildOptions{
+			Dockerfile: dockerfileName,
+			ContextDir: dockerContextPath,
+			BuildArgs:  buildArgs,
+		}
+
+		log.Printf("Building tailscale-rs container %s from upstream (this may take a while for the first build)...", hostname)
+
+		container, err = pool.BuildAndRunWithBuildOptions(
+			buildOptions,
+			runOptions,
+			dockertestutil.DockerRestartPolicy,
+			dockertestutil.DockerAllowLocalIPv6,
+			dockertestutil.DockerMemoryLimit,
+		)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"tsric: could not build and start tailscale-rs container %s: %w",
+				hostname, err,
+			)
+		}
+	}
+
+	log.Printf("Created tailscale-rs container %s", hostname)
+
+	t.container = container
+
+	// Write CA certificates into the container
+	for i, cert := range t.caCerts {
+		err = t.WriteFile(fmt.Sprintf("%s/user-%d.crt", caCertRoot, i), cert)
+		if err != nil {
+			return nil, fmt.Errorf("writing TLS certificate to container: %w", err)
+		}
+	}
+
+	return t, nil
+}
+
+// Hostname returns the hostname of the TailscaleRustInContainer instance.
+func (t *TailscaleRustInContainer) Hostname() string {
+	return t.hostname
+}
+
+// ContainerID returns the Docker container ID.
+func (t *TailscaleRustInContainer) ContainerID() string {
+	return t.container.Container.ID
+}
+
+// Shutdown stops and cleans up the container.
+func (t *TailscaleRustInContainer) Shutdown() (string, string, error) {
+	stdoutPath, stderrPath, err := t.SaveLog("/tmp/control")
+	if err != nil {
+		log.Printf(
+			"saving log from %s: %s",
+			t.hostname,
+			fmt.Errorf("saving log: %w", err),
+		)
+	}
+
+	return stdoutPath, stderrPath, t.pool.Purge(t.container)
+}
+
+// SaveLog saves the current container logs to the given path.
+func (t *TailscaleRustInContainer) SaveLog(path string) (string, string, error) {
+	return dockertestutil.SaveLog(t.pool, t.container, path)
+}
+
+// WriteLogs writes the current stdout/stderr log of the container to
+// the given io.Writers.
+func (t *TailscaleRustInContainer) WriteLogs(stdout, stderr io.Writer) error {
+	return dockertestutil.WriteLog(t.pool, t.container, stdout, stderr)
+}
+
+// Execute runs a command inside the container.
+func (t *TailscaleRustInContainer) Execute(
+	command []string,
+	options ...dockertestutil.ExecuteCommandOption,
+) (string, string, error) {
+	return dockertestutil.ExecuteCommand(
+		t.container,
+		command,
+		[]string{},
+		options...,
+	)
+}
+
+// WriteFile writes a file into the container.
+func (t *TailscaleRustInContainer) WriteFile(path string, data []byte) error {
+	return integrationutil.WriteFileToContainer(t.pool, t.container, path, data)
+}