Providers

Providers in Goma Gateway enable dynamic configuration management by automatically discovering and loading routes and middleware from external sources.

Instead of manual editing configuration files, providers allow you to adopt modern patterns such as GitOps, service discovery, and centralized configuration management.

Why Use Providers?

Providers unlock a more scalable and automated way to manage your gateway:

Dynamic Discovery
Automatically detect and configure services without manual updates
GitOps Integration
Store and version gateway configuration in Git repositories
Centralized Management
Control multiple gateway instances from a single source
Zero-Downtime Updates
Apply configuration changes without restarting the gateway

Available Providers

Goma Gateway supports both built-in and external providers.

Built-in Providers

File — Load configuration from the local filesystem (with hot reload)
HTTP — Fetch configuration from remote APIs
Git — Pull configuration from Git repositories (GitOps)

External Providers

Docker / Swarm — Generate configuration from container labels
Kubernetes — Integrate with CRDs and annotations
HTTP API — Manage configuration via REST APIs

How Providers Work

All providers follow a continuous synchronization cycle:

Key Behaviors

Safe updates — Invalid configurations never break the gateway
Fallback mechanism — Last valid configuration remains active
Caching — HTTP and Git providers cache successful configurations
Live reload — File provider watches for filesystem changes

File Provider

The File Provider loads configuration from a local directory and optionally watches for changes.

Configuration

Field	Type	Required	Description
`enabled`	bool	Yes	Enable the provider
`directory`	string	Yes	Directory containing configuration files
`watch`	bool	No	Enable automatic reload on file changes

Example

gateway:
  providers:
    file:
      enabled: true
      directory: /etc/goma/providers
      watch: true

HTTP Provider

The HTTP Provider fetches configuration from a remote endpoint. It is ideal for centralized configuration services or control planes.

Features

Retry mechanism
TLS configuration
Response caching
Custom headers support

Supported Content Types

application/json
application/yaml
application/x-yaml
text/yaml

Configuration

Field	Type	Required	Default	Description
`enabled`	bool	Yes	—	Enable the provider
`endpoint`	string	Yes	—	Remote configuration URL
`interval`	duration	No	60s	Polling interval
`timeout`	duration	No	10s	Request timeout
`retryAttempts`	int	No	3	Max retry attempts
`retryDelay`	duration	No	2s	Delay between retries
`cacheDir`	string	No	/tmp/goma/cache/config.json	Cache file path
`insecureSkipVerify`	bool	No	false	Skip TLS verification
`headers`	map	No	—	Custom HTTP headers

Example

gateway:
  providers:
    http:
      enabled: true
      endpoint: "https://config.example.com/api/gateway/config"
      interval: 60s
      timeout: 10s
      retryAttempts: 3
      retryDelay: 2s
      cacheDir: ""
      insecureSkipVerify: false
      headers:
        X-Goma-Gateway-Id: "goma-prod-01"
        X-Goma-Environment: "production"
        Authorization: "${GOMA_AUTHORIZATION}"

Response Format

The endpoint must return a valid Goma configuration in YAML or JSON.

version: "1"
timestamp: 2024-10-01T12:00:00Z
checksum: "..."
metadata:
  gateway-id: goma-prod-01
  environment: production

routes:
  - name: api-example
    enabled: true
    path: /
    target: http://api-example:8080

middlewares:
  - name: rate-limit
    type: rateLimit

Git Provider

The Git Provider retrieves configuration from a Git repository, enabling GitOps workflows.

Supported Authentication

Type	Credentials
token	token
basic	username + password
ssh	private SSH key

Configuration

Field	Type	Required	Default	Description
`enabled`	bool	Yes	—	Enable the provider
`url`	string	Yes	—	Git repository URL
`branch`	string	No	main	Branch to pull
`path`	string	No	/	Path to configuration
`interval`	duration	No	60s	Sync interval
`cloneDir`	string	No	temp	Local clone directory
`auth`	object	No	—	Authentication configuration

Authentication fields

Field	Type	Description
`auth.type`	string	One of `token`, `basic`, or `ssh`.
`auth.token`	string	Access token. Used when `type: token`.
`auth.username`	string	Username. Used when `type: basic`.
`auth.password`	string	Password. Used when `type: basic`.
`auth.sshKeyPath`	string	Path to a private SSH key file. Used when `type: ssh`.
`auth.sshKeyData`	string	The private SSH key inline, base64-encoded. Used when `type: ssh`.

Provide either sshKeyPath or sshKeyData — sshKeyData suits environments where the key arrives through an environment variable or a mounted secret rather than a file on disk.

SSH host verification

For type: ssh, the Git host is verified before anything is cloned. Configure one of:

Field	Description
`auth.hostKey`	A pinned host key in `authorized_keys` format (`ssh-ed25519 AAAA…`). Takes precedence.
`auth.knownHostsPath`	An OpenSSH `known_hosts` file. Defaults to `~/.ssh/known_hosts`.

A host that verifies against neither is refused. Without this, anyone able to MITM or DNS-hijack the route to the Git host could serve an arbitrary configuration repository — and its routes are merged into the running gateway.

Example

gateway:
  providers:
    git:
      enabled: true
      url: "https://github.com/jkaninda/goma-gateway-production-deployment.git"
      branch: main
      path: /gateway
      interval: 60s
      auth:
        type: token
        token: ${GIT_TOKEN}
      cloneDir: ""

Signing configuration bundles

Bundles from the HTTP and Git providers arrive over the network and are merged straight into the live gateway. Their routes are sorted longest-path-first, so a bundle carrying a longer path shadows a real route and receives its traffic under the gateway's own TLS.

The bundle checksum does not protect against this: it is recomputed locally from the bytes just received, so it detects corruption, not forgery. Sign the bundles instead.

1. Generate a keypair — once, wherever bundles are published from:

goma config keygen -o signing.key
# Public key  (providers.signing.publicKey): D0lLjT2/f12T4hoi3Zyn9Q1SAW0tTtOzPjTDPwPGHaw=

2. Sign each bundle before publishing it:

goma config sign --key-file signing.key gateway/routes.yml

sign writes a detached Ed25519 signature into the bundle's signature field, over a canonical checksum that excludes the signature, checksum and timestamp fields — so the value survives re-serialization.

3. Configure the trust anchor on the gateway:

gateway:
  providers:
    signing:
      publicKey: "D0lLjT2/f12T4hoi3Zyn9Q1SAW0tTtOzPjTDPwPGHaw="
      # Or, to allow more than one signer while rotating a key:
      # publicKeyFile: /etc/goma/signers.pub
    git:
      enabled: true
      # ...

Once publicKey or publicKeyFile is set, an HTTP or Git bundle that is unsigned, altered after signing, or signed by an unlisted key is refused, and the gateway keeps serving its previous configuration. With neither set the gateway warns at load and applies bundles unverified, so enabling signing is a deliberate step rather than a breaking upgrade.

The file provider is not covered: it reads a local directory at the same trust level as the main configuration file.

Field	Type	Required	Description
`publicKey`	string	No	Base64 Ed25519 public key. Takes precedence over `publicKeyFile`.
`publicKeyFile`	string	No	File of base64 public keys, one per line; `#` comments allowed.

Control Plane vs Data Plane

Goma follows a modern architecture:

Goma Gateway → Data plane (fast, lightweight, execution)
Goma Admin → Control plane (management, UI, orchestration)

The gateway intentionally avoids embedding heavy integrations (like Docker or UI) to remain lightweight, modular, and high-performance.

Goma Admin (Control Plane)

Goma Admin provides a centralized interface to manage gateway configurations.

Key Features

Multi-instance management
File & HTTP provider integration
Docker-based service discovery
Import / Export of configurations
API key management
Metrics & monitoring (Prometheus)
OAuth2 integration (Keycloak, Authentik, Gitea)
Audit logs (configuration history)
Git synchronization (bi-directional)

Docker Provider (via Goma Admin)

The Goma Docker Provider automatically generates configuration from container labels.

This approach is similar to Traefik:

Routing rules defined via labels
Automatic service discovery
No manual configuration required

Example (Docker Compose)

services:
  web-service:
    image: jkaninda/okapi-example
    labels:
      - "goma.enable=true"
      - "goma.port=8080"
      - "goma.hosts=example.com,www.example.com"

👉 Goma Admin

External Providers

Docker / Swarm

Use the external Docker provider for container-based environments.

👉 Goma Docker Provider

HTTP API Provider

Expose a REST API for dynamic configuration management.

Ideal for:

Internal platforms
Automation workflows
Custom control planes

👉 Goma HTTP Provider

Summary

Providers are a core building block of Goma Gateway:

They enable automation
They support modern deployment models
They decouple configuration from runtime

For advanced setups, combine:

Git Provider → GitOps
HTTP Provider → centralized control
Goma Admin → full control plane experience

Why Use Providers?​

Available Providers​

Built-in Providers​

External Providers​

How Providers Work​

Key Behaviors​

File Provider

Configuration​

Example​

HTTP Provider

Features​

Supported Content Types​

Configuration​

Example​

Response Format​

Git Provider

Supported Authentication​

Configuration​

Authentication fields​

SSH host verification​

Example​

Signing configuration bundles

Control Plane vs Data Plane

Goma Admin (Control Plane)​

Key Features​

Docker Provider (via Goma Admin)​

Example (Docker Compose)​

External Providers​

Docker / Swarm​

HTTP API Provider​

Summary​

Why Use Providers?

Available Providers

Built-in Providers

External Providers

How Providers Work

Key Behaviors

Configuration

Example

Features

Supported Content Types

Configuration

Example

Response Format

Supported Authentication

Configuration

Authentication fields

SSH host verification

Example

Goma Admin (Control Plane)

Key Features

Docker Provider (via Goma Admin)

Example (Docker Compose)

External Providers

Docker / Swarm

HTTP API Provider

Summary