Documentation
¶
Overview ¶
Package proxy abstracts the reverse proxy / gateway (Goma Gateway). Routes and middlewares are written as YAML files in Goma's watched provider directory; an in-memory implementation backs dev and tests. TLS termination, ACME issuance and renewal are owned by Goma.
Index ¶
- Constants
- func CentralConfigKey() string
- func GomaName(workspaceID uint, name string) string
- func RenderBundle(routes []RenderedRoute, mws []RenderedMiddleware, cfgKey string) ([]byte, error)
- func RenderMiddleware(mw RenderedMiddleware) ([]byte, error)
- func RenderRoute(route RenderedRoute) ([]byte, error)
- type Backend
- type CertPair
- type Goma
- type Manager
- type MatchRule
- type Memory
- type RegistryProxy
- type RenderedMiddleware
- type RenderedRoute
- type RouteMaintenance
Constants ¶
const ConfigEncryptionKeyEnv = "GOMA_CONFIG_ENCRYPTION_KEY"
ConfigEncryptionKeyEnv is the passphrase the CENTRAL gateway — the one shipped beside the control plane — shares with Miabi. When set, Miabi encrypts sensitive rendered config (middleware rules and inline TLS material) so it is never written to the provider directory as plaintext. It MUST match that gateway's GOMA_CONFIG_ENCRYPTION_KEY.
It is NOT the key for the gateways Miabi deploys on nodes. Those each get their own, derived per node, so one compromised edge host cannot read another's config — see edgegateway.ConfigKey. The env var stays the operator's setting because the compose gateway's environment is theirs, not Miabi's, to write.
Variables ¶
This section is empty.
Functions ¶
func CentralConfigKey ¶ added in v1.10.6
func CentralConfigKey() string
CentralConfigKey returns the central gateway's passphrase, or "" when config encryption is off.
func GomaName ¶ added in v1.6.0
GomaName exposes the Goma identifier a workspace route is served under, so consumers of the gateway's telemetry (the analytics stream carries this name) can map an event back to the route it belongs to.
func RenderBundle ¶
func RenderBundle(routes []RenderedRoute, mws []RenderedMiddleware, cfgKey string) ([]byte, error)
RenderBundle produces a combined routes+middlewares Goma config document (the shape Goma's HTTP provider consumes), used to serve a remote node's config over the control plane's provider endpoint.
cfgKey is THAT NODE's key, not the central gateway's: every node encrypts under its own, so a bundle that escapes one host is unreadable on any other. Empty writes plaintext.
func RenderMiddleware ¶
func RenderMiddleware(mw RenderedMiddleware) ([]byte, error)
RenderMiddleware produces the YAML file content for a middleware, under the central gateway's key.
func RenderRoute ¶
func RenderRoute(route RenderedRoute) ([]byte, error)
RenderRoute produces the YAML file content for a route (exported for tests), under the central gateway's key.
Types ¶
type Backend ¶
type Backend struct {
Endpoint string // e.g. http://mb-app-1:8080
Weight int // relative weight; probability = weight / sum(weights)
Exclusive bool
Priority int
Match []MatchRule
}
Backend is a single upstream for a route. Weight enables canary / weighted load-balancing across backends; 0 means unweighted (single backend). Match, Exclusive and Priority add attribute-based canary routing: a matching Exclusive backend takes all of the matching traffic, while a matching non-exclusive one joins the weighted pool. Priority breaks ties between several matching exclusive backends.
type Goma ¶
type Goma struct {
// contains filtered or unexported fields
}
Goma drives Goma Gateway via its file provider: each route and middleware is written as a YAML file in Goma's watched directory, which Goma hot-reloads and merges. ACME is handled by Goma's global certManager; custom certs are inlined into the route's tls block.
func NewGoma ¶
NewGoma returns a Goma file-provider Manager writing into dir, encrypting sensitive fields under the central gateway's configured key (empty = write plaintext).
func (*Goma) SyncRegistry ¶
func (g *Goma) SyncRegistry(_ context.Context, cfg RegistryProxy) error
SyncRegistry writes the built-in registry's gateway config (route + HTTPS redirect, forwardAuth, and namespace-rewrite middlewares) to its own file, or removes the file when disabled / incompletely configured. Idempotent.
func (*Goma) SyncWorkspace ¶
func (g *Goma) SyncWorkspace(_ context.Context, workspaceID uint, routes []RenderedRoute, mws []RenderedMiddleware) error
SyncWorkspace writes (or removes) a workspace's single Goma config file holding all its routes and middlewares. The file is replaced atomically, so Goma always reads a route and the middlewares it references together.
type Manager ¶
type Manager interface {
// SyncWorkspace replaces a workspace's entire proxy config — all its routes and
// middlewares — atomically. Passing no routes and no middlewares removes the
// workspace's config entirely.
SyncWorkspace(ctx context.Context, workspaceID uint, routes []RenderedRoute, mws []RenderedMiddleware) error
// SyncRegistry writes (or, when disabled, removes) the built-in registry's
// gateway route + middlewares.
SyncRegistry(ctx context.Context, cfg RegistryProxy) error
}
Manager applies desired proxy state. A workspace's routes and middlewares are written together as one unit (Goma resolves a route's middleware references within the same file), so the workspace is the unit of sync rather than individual resources. Implementations are idempotent.
type MatchRule ¶ added in v1.9.0
type MatchRule struct {
Source string // header | query | cookie | ip
Name string // header/query/cookie key; unused for ip
Operator string // equals | not_equals | contains | not_contains | starts_with | ends_with | regex | in
Value string // compared value; comma-separated list for `in`
}
MatchRule is one condition on a request attribute. A backend carrying match rules is only eligible for requests satisfying all of them (attribute-based canary routing); Source, Operator and their valid values mirror the gateway's.
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory is an in-process Manager used when no real gateway is configured (dev/tests). It records the desired routes and middlewares per workspace.
func (*Memory) GetRoute ¶
func (m *Memory) GetRoute(id uint) (RenderedRoute, bool)
GetRoute returns the recorded route (used in tests).
func (*Memory) SyncRegistry ¶
func (m *Memory) SyncRegistry(_ context.Context, cfg RegistryProxy) error
SyncRegistry records the registry proxy config (no-op store for the in-memory manager; the Goma manager writes the actual gateway file).
func (*Memory) SyncWorkspace ¶
func (m *Memory) SyncWorkspace(_ context.Context, workspaceID uint, routes []RenderedRoute, mws []RenderedMiddleware) error
SyncWorkspace replaces the recorded state for a workspace: it drops the workspace's previous routes/middlewares and stores the supplied set.
type RegistryProxy ¶
type RegistryProxy struct {
Enabled bool // false removes the registry config
Host string // public host, e.g. registry.<domain>
Upstream string // http://mb-registry:5000
AuthURL string // forwardAuth target, e.g. http://miabi:9000/internal/registry/auth
TLSProvider string // certManager provider ("" = gateway default)
// UpstreamAuth is the Authorization header the gateway presents to the registry, which requires
// Basic auth even on the private network. It REPLACES the tenant's own header on the way
// upstream — by then forwardAuth has already decided whether that tenant may proceed. Empty
// renders no such middleware, which is the pre-credential behaviour.
UpstreamAuth string
// HTTPSRedirect adds the redirectScheme middleware. Off is for an install
// behind a TLS terminator whose gateway has no trusted proxies configured:
// Goma would see the plaintext hop, decide the request is not HTTPS, and
// redirect it back to the terminator — forever. See RegistryConfig.
HTTPSRedirect bool
}
RegistryProxy is the desired gateway config for the built-in Docker registry: one route fronted by the HTTPS-redirect, forwardAuth and namespace-rewrite middlewares. Rendered to a dedicated file, separate from the per-workspace configs.
type RenderedMiddleware ¶
type RenderedMiddleware struct {
ID uint
WorkspaceID uint // namespaces the Goma name (mb-ws<id>-<name>); routes reference it the same way
Name string
Type string
Paths []string
Rule map[string]interface{}
}
RenderedMiddleware is the desired Goma middleware definition.
type RenderedRoute ¶
type RenderedRoute struct {
ID uint
WorkspaceID uint // namespaces the Goma name (mb-ws<id>-<name>) to avoid cross-workspace collisions
Name string
Path string
Hosts []string
Methods []string
Rewrite string // path rewrite
Middlewares []string // referenced middleware names
Backends []Backend // one or more weighted upstreams
Certs []CertPair
// TLSProvider names the Goma certManager provider that serves this route's
// cert (multi-provider certManager). Empty = the gateway's default provider.
TLSProvider string
// TLSNone marks a route that opts out of TLS entirely; it renders an explicit
// tls.provider: "none" so the gateway never tries to obtain a cert for it.
TLSNone bool
// Disabled renders the route with Goma's `enabled: false` so the gateway keeps it defined but
// stops serving it. Zero value is enabled, matching Goma's default. Preferred over dropping the
// route, which doesn't reliably take effect across the file and HTTP providers.
Disabled bool
// AdvancedYAML, when set, is a raw Goma route config that supersedes the
// structured fields; Miabi still forces name/backends/tls into it.
AdvancedYAML string
ExploitProtection bool
Maintenance *RouteMaintenance
}
RenderedRoute is the desired Goma route. Backends (the upstreams) are injected by the caller from the application's network alias(es). A single backend means all traffic goes there; multiple weighted backends enable canary splits.