jkaninda/goma-k8s-provider repository overview

⁠goma-k8s-provider

A lightweight sidecar that watches Kubernetes Route and Middleware custom resources (defined by Goma Operator⁠) and materializes them into a config bundle on disk that Goma Gateway⁠ consumes via its file provider.

It runs alongside the gateway container in the same Pod, giving the gateway near-instant, restart-free reloads whenever a Route/Middleware changes.

⁠How it works

flowchart TB
    subgraph Pod["Gateway Pod"]
        direction LR
        Gateway["goma-gateway<br/>(file provider)"]
        Provider["goma-k8s-provider<br/>(this image)"]
        Gateway <-. "shared volume<br/>/etc/goma/..." .-> Provider
    end

    K8sAPI["Kubernetes API<br/>Route / Middleware CRs<br/>(owned by a Gateway CR)"]

    Provider -- "watch" --> K8sAPI

1. The sidecar watches Route and Middleware CRs scoped to a single Gateway (by name, via GOMA_K8S_GATEWAY).
2. On change, events are debounced and converted into the native Goma Gateway config format.
3. The resulting bundle is written atomically to GOMA_K8S_OUTPUT_DIR (default /etc/goma/providers/k8s), where the gateway's file provider picks it up and reloads.
4. Optionally, the sidecar also syncs the gateway's ACME store (acme.json) to a Kubernetes Secret, so certificates survive pod restarts and rescheduling.

The sidecar is injected automatically by goma-operator unless disabled via:

spec:
  providers:
    kubernetes:
      enabled: false

⁠Configuration

All configuration is via environment variables.

⁠RBAC

The sidecar needs read access to routes and middlewares in the watched namespace(s), plus read/write on the ACME Secret (when ACME sync is enabled). When installed via goma-operator, these permissions are granted automatically.

Minimal rules:

- apiGroups: ["gateway.jkaninda.dev"]
  resources: ["routes", "middlewares"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "create", "update", "patch"]

⁠Running locally

The sidecar falls back to $HOME/.kube/config when not running in-cluster:

export GOMA_K8S_GATEWAY=ingress
export GOMA_K8S_NAMESPACE=default
export GOMA_K8S_OUTPUT_DIR=/tmp/goma-k8s
export GOMA_K8S_LOG_LEVEL=debug

go run ./cmd

⁠Build

make build            # local binary
make docker-build     # container image

⁠Related Projects

• Goma Gateway⁠ — Cloud-native API Gateway
• Goma HTTP Provider⁠ — Goma Operator
• Goma Operator⁠ — Kubernetes Operator for Goma Gateway
• Goma Admin⁠ — Control Plane for Goma Gateway — Manage, configure, and monitor distributed Goma Gateway.

⁠License

This project is licensed under the Apache-2.0.

⁠Support

• Email: meAtjkaninda.dev
• LinkedIn: LinkedIn⁠

Copyright 2026 Jonas Kaninda