Kubernetes Integration#

Tinyauth integrates with the Kubernetes Ingress API (networking.k8s.io/v1) to dynamically read per-app access control configuration from ingress annotations. This is one of three label-provider modes — docker, kubernetes, and none — selected at startup via the LabelProvider config value 1. In auto mode, Tinyauth selects Kubernetes when the KUBERNETES_SERVICE_HOST environment variable is set 2.

The integration was refactored as part of v5.1.0 (released 2026-07-15), which migrated all services and controllers to Uber's dig dependency-injection container 3.

Architecture Overview#

Bootstrap
  └── getLabelProvider()
        └── NewKubernetesService(KubernetesServiceInput) [dig-injected]
              ├── Validate in-cluster config & probe Ingress API
              ├── Register watchGVR goroutine (via ding)
              └── Returns *KubernetesService implementing LabelProvider
                    └── GetLabels(domain) → *model.App

KubernetesService#

Entry point: internal/service/kubernetes_service.go

KubernetesService holds:

• A dynamic.Interface Kubernetes client
• An ingressApps map keyed by {namespace, name}
• A domainIndex and appNameIndex for O(1) lookup

Initialization & Fail-Fast Probing#

NewKubernetesService uses a dig.In input struct 4 and performs a 5-second timeout probe of the Ingress API at startup 5. If the probe fails, the constructor returns a non-nil error — this is the intentional fail-fast signal. The bootstrap layer catches that error and degrades gracefully: if the provider was set to kubernetes explicitly it logs a warning and continues without it; the service is simply disabled 6.

Watch Loop & Resync#

Once initialized, a background goroutine (managed by ding at RingMajor priority) runs watchGVR, which:

1. Initial resync — lists all ingresses and calls updateFromItem on each 7
2. Watch loop — streams Added/Modified/Deleted events via k8s.io/client-go/dynamic 8
3. Periodic resync — every 5 minutes via a ticker to catch missed events
4. Auto-restart — if the watch channel closes, it waits 5 seconds and restarts; failed watch starts wait 10 seconds before retry

Label Parsing & Annotation Format#

updateFromItem reads ingress annotations via decoders.DecodeLabels[model.Apps] using the "apps" prefix key. The expected annotation format mirrors the Docker label pattern: tinyauth.apps.<app-name>.<field>. Apps with no matching Config.Domain or whose domain doesn't appear in the ingress spec.rules.host list are skipped with a warning 11.

A security warning is emitted if an ingress rule lacks a catch-all / path — a non-/ path could allow another ingress with a different path to bypass auth on the same host 12.

Label Lookup#

GetLabels(domain) implements the LabelProvider interface 13. It:

1. Returns nil, nil immediately if the service didn't start 14
2. Looks up by exact domain via domainIndex 15
3. Falls back to the first subdomain component as an app-name lookup via appNameIndex 16

Dependency Injection (dig)#

The v5.1.0 refactor (PR #936) replaced manual constructor calls throughout the service layer with Uber's dig container 3. Key points:

• Every service now declares a <Name>ServiceInput struct embedding dig.In, replacing positional constructor arguments 3.
• Services registered via dig.Provide(); any failure is a hard error — the for _, provider := range serviceProvideFor loop returns immediately on error 17.
• Optional services (LdapService, TailscaleService) use the optional:"true" struct tag to allow absent providers without failing the container 3.
• The LabelProvider interface is wired in as a concrete factory before other services are registered, ensuring all downstream services see the correct provider 18.

Fail-fast bootstrap: errors from Provide() or Invoke() propagate up through setupServices() → getLabelProvider() and abort application startup immediately, preventing partially-initialized states 3 19.

Key Files#