Goma Gateway

Goma Gateway is a high-performance, security-focused, cloud-native API Gateway. It puts security at the edge — automatic HTTPS, mTLS, built-in authentication, and exploit protection — and built to run where your services run: containers, Kubernetes, and dynamic, horizontally scaled environments. With declarative configuration, zero-downtime reloads, and first-class observability, Goma helps you route, secure, and scale traffic effortlessly.

The project is named after Goma, a vibrant city located in the eastern region of the Democratic Republic of the Congo — known for its resilience, beauty, and energy.

Features

More than just a reverse proxy: Goma Gateway secures, routes, and scales your traffic from a single declarative configuration, with enterprise-grade features and none of the enterprise complexity.

Security & Access Control

• TLS with Automatic Certificate Management

  • Free, auto-generated certificates via Let's Encrypt, with automatic renewal and storage.
  • Custom TLS certificates, falling back to auto-generation when none is provided.

• Mutual TLS (mTLS) Authenticate clients with certificates before traffic reaches your services.

• Authentication Middleware

  • Built-in Basic Auth, JWT, OAuth, OpenID Connect, and LDAP.
  • ForwardAuth for external authorization services.

• Access Policy Enforcement Allow or deny traffic based on route-specific rules (IP, headers, methods, etc.), with geo-blocking by country.

• Exploit Protection Middleware Block common attack patterns such as SQL injection and cross-site scripting (XSS).

• Bot Detection Identify and block traffic from known bots using user-agent analysis.

• Rate Limiting & Abuse Prevention

  • In-memory limits for single-instance deployments, or Redis for enforcement across many instances.
  • Automatic client banning for repeated violations.
  • Configurable thresholds and keys (IP address, API key, header, or cookie).

• Request Hardening

  • CORS policies per route for controlled cross-origin access.
  • Body size limits and explicit per-route HTTP method restrictions.
  • Custom header injection for fine-grained request/response control.

Cloud-Native by Design

• Kubernetes Operator Manage gateways, routes, and middleware as Kubernetes-native Gateway, Route, and Middleware resources.

• Dynamic Configuration Providers Load configuration from File, HTTP, Docker, and Kubernetes providers, and add or remove backends without restarting the gateway.

• Horizontal Scalability Run many stateless gateway instances, sharing rate-limit and cache state through Redis.

• Health & Readiness Endpoints /healthz and /readyz plug directly into orchestrator liveness and readiness probes.

• Live Configuration Reload Apply changes and enable or disable routes on the fly, with zero downtime.

• GitOps-Ready, Modular Configuration

  • Split routes and middleware across multiple .yml or .yaml files.
  • Version-control your gateway configuration for traceable, automated deployments.

Routing & Traffic Management

• Declarative Routing Define routes, middleware, policies, and TLS in clear, maintainable YAML.

• Domain & Host-Based Routing Route requests by domain, host, or path, across multiple domains in one configuration.

• Reverse Proxy Forward client requests to backend services, abstracting service details from clients.

• WebSocket, gRPC, TCP & UDP Native WebSocket and gRPC routing, plus TCP/UDP forwarding through the PassThrough entry point.

• Load Balancing Round-robin and weighted algorithms, with integrated health checks that route only to healthy upstreams.

• Canary Deployments

  • Weighted Backends – Gradually shift traffic between service versions using percentage-based routing.
  • Conditional Routing – Route requests based on user groups, headers, query parameters, or cookies for targeted rollouts.

• Regex URL Rewriting Modify request paths on the fly using regex rules.

• Backend Error Interception Intercept and handle backend errors gracefully to improve reliability and user experience.

Performance & Observability

• HTTP Caching

  • In-memory for low-latency single-node setups, or Redis for distributed cache sharing.
  • Respects standard Cache-Control headers and exposes X-Cache-Status for transparency.
  • Time or event-based cache invalidation.

• Structured Logging Capture request/response details with configurable log levels (INFO, DEBUG, ERROR).

• Metrics Track response times, error rates, and throughput in Prometheus, with a prebuilt Grafana dashboard.

---

Architecture:

---

Ecosystem

Goma Gateway is the data plane: fast, lightweight, and deliberately free of heavy integrations. Management, service discovery and orchestration live in separate projects around it.

Project	Role
Goma Admin	Control plane — UI, multi-instance management, audit logs, Git sync
Kubernetes Operator	Manage gateways, routes and middleware as Kubernetes CRDs
HTTP Provider	Serve configuration to the gateway over a REST API
Docker Provider	Generate configuration from container labels
Kubernetes Provider	Generate configuration from Kubernetes resources

Built on Goma Gateway

Miabi is a self-hosted, developer-first Platform-as-a-Service for containerized apps — push from a Git repo, a Docker image or a marketplace template, and it handles build, deploy, domains, automatic SSL, databases, scaling, backups and monitoring.

Miabi runs Goma Gateway as its edge gateway. Every app deployed on the platform is exposed through it, and the gateway is the only public listening surface on the node: it terminates TLS, issues certificates, applies middleware and routes traffic to the application containers. Miabi's control plane drives it by writing route files into a watched directory, and remote clusters run their own gateway that pulls its routes over HTTP.

It is a useful reference for anyone building a platform on top of Goma — see Providers for how the integration works, and the Miabi architecture overview.

---

We are open to receiving stars, PRs, and issues!

---

The jkaninda/goma-gateway Docker image can be deployed on Docker, Docker in Swarm mode, and Kubernetes.

Available image registries

This Docker image is published to both Docker Hub and the GitHub container registry. Depending on your preferences and needs, you can reference both jkaninda/goma-gateway as well as ghcr.io/jkaninda/goma-gateway:

docker pull jkaninda/goma-gateway
docker pull ghcr.io/jkaninda/goma-gateway

Documentation references Docker Hub, but all examples will work using ghcr.io just as well.