proxy

package
v0.1.0-alpha.41 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 22, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package proxy defines the ingress configuration pushed to every node and the Driver interface implemented by proxy backends (HAProxy in v0.1, Nginx planned for v0.2).

Index

Constants

View Source
const (
	// WakeHeader names the app a request on the agent's wake socket is for
	// (ADR 0021). Only the proxy sets it, overwriting any value from the
	// client.
	WakeHeader = "X-Armada-Wake"
	// WakeTimeout is how long a request for an app scaled to zero waits for
	// a replica.
	WakeTimeout = 60 * time.Second
	// MaxTimeoutSeconds bounds Backend.TimeoutSeconds.
	MaxTimeoutSeconds = 3600
)
View Source
const (
	// The limits bound what a compromised control plane can make an agent
	// render, far above what a cluster needs: a backend per app and labelled
	// revision, a rule per host and route.
	MaxBackends     = 100_000
	MaxRules        = 1_000_000
	MaxCertificates = 100_000
	// MaxServers leaves room for an app at spec.MaxReplicas while a rollout
	// or a move adds replicas next to the ones that serve.
	MaxServers = 2 * spec.MaxReplicas

	// MaxTrustedProxies bounds the prefixes of TrustedProxies.
	MaxTrustedProxies = 64
	// MaxTCPRoutes bounds the TCP routes, and MaxTCPPorts the listeners
	// they make on each node.
	MaxTCPRoutes = 100_000
	MaxTCPPorts  = 4096
)

Limits on what a single configuration may contain.

View Source
const ClientIPHeader = "X-Real-IP"

ClientIPHeader carries the client's address to every app behind the public frontend: the address the client address rules judge (ADR 0035), worked out from the connection and the trusted proxies. The proxy always sets it itself, or removes it when the address is unknown; a value from the request, a trusted proxy's included, never reaches an app.

View Source
const MaxCORSMaxAgeSeconds = 86400

MaxCORSMaxAgeSeconds bounds how long browsers may keep a preflight answer.

View Source
const MaxLoadEntries = 20000

MaxLoadEntries bounds the busy replicas in one usage report: an agent with more reports its load as unmeasured, and the server takes no more.

View Source
const MaxWeight = 256

MaxWeight is the largest server weight.

Variables

View Source
var ClientAddressHeaders = []string{"Forwarded", "X-Forwarded-For", "CF-Connecting-IP", "True-Client-IP"}

ClientAddressHeaders are the headers applications read a client's address from, set by proxies. They are only believed from TrustedProxies.

View Source
var ForwardedURLHeaders = []string{"X-Forwarded-Host", "X-Forwarded-Port", "X-Forwarded-Prefix", "X-Forwarded-Server"}

ForwardedURLHeaders are the headers applications build their own URLs from (links in emails, redirects). The public frontend routed the request on its Host and serves only HTTPS on 443, so these are removed from every request, a trusted proxy's included: proxies in front commonly pass a client's value on unchanged.

Functions

func BackendSpace

func BackendSpace(backend string) string

BackendSpace returns the space of the app a backend serves (a backend is named by the app ID, or <label>--<app ID> for a revision label), or "" for an invalid name.

func ExcludePrefixes

func ExcludePrefixes(trusted []string, out []netip.Prefix) []string

ExcludePrefixes returns trusted with every address of out taken away, in canonical form, sorted: a prefix inside one of out is dropped, and one that holds one of out is split into the prefixes around it. The leader takes the cluster's container ranges out of the trusted proxies this way, so a workload is never a trusted proxy (T79).

func ParseProxyProtocol

func ParseProxyProtocol(prefixes []string) ([]string, error)

ParseProxyProtocol checks the prefixes of load balancers that send the PROXY protocol like ParseTrustedProxies: any of them may name any client.

func ParseTrustedProxies

func ParseTrustedProxies(prefixes []string) ([]string, error)

ParseTrustedProxies checks prefixes of proxies in front of the nodes and returns them in canonical form, sorted and without duplicates. A prefix that matches every address is refused: it would let any client claim any address.

Types

type Backend

type Backend struct {
	Name       string
	Servers    []Server
	HealthPath string
	// Wake routes requests to the agent's wake socket while no server is
	// up, so an app scaled to zero starts on demand (ADR 0021).
	Wake bool
	// LocalFirst makes each node's proxy prefer the replicas on its own
	// node (ADR 0024).
	LocalFirst bool
	// TimeoutSeconds is how long a request may wait for an answer; 0 means
	// the proxy's default.
	TimeoutSeconds int
	// IPAllow lets only clients in these prefixes reach the backend through
	// the public frontend; IPDeny refuses those in them. At most one is set,
	// as masked prefixes (ADR 0035).
	IPAllow []string
	IPDeny  []string
	// Sticky keeps a client on one server through a cookie (ADR 0036).
	Sticky bool
	// CORS is the app's cross-origin policy; nil for none (ADR 0037).
	CORS *CORS
}

Backend is one app's set of replicas.

type CORS

type CORS struct {
	Origins, Methods, Headers, Expose []string
	MaxAgeSeconds                     int
	Credentials                       bool
}

CORS is what the proxy answers browsers about other origins.

type Certificate

type Certificate struct {
	Name string
	PEM  []byte
}

Certificate is a PEM bundle (chain + key) for Name, which may be a wildcard ("*.apps.example.com").

func (Certificate) FileName

func (c Certificate) FileName() string

FileName returns a filesystem-safe name for the certificate.

type ClientSetter

type ClientSetter interface {
	// SetClients maps the addresses of this node's containers to their app
	// IDs; an address not in the map reaches no internal route.
	SetClients(ctx context.Context, clients map[netip.Addr]string) error
}

ClientSetter is implemented by drivers whose internal frontend checks who calls (ADR 0026).

type Config

type Config struct {
	Backends     []Backend
	Rules        []Rule
	Certificates []Certificate
	// ACMEAddress is the control plane's HTTP-01 responder (private ip:port).
	ACMEAddress string
	// TrustedProxies are the prefixes whose requests keep the client address
	// headers they carry (ClientAddressHeaders). Requests from anywhere else
	// lose them, so a client cannot claim another address.
	TrustedProxies []string
	// TCP are the internal TCP listeners (ADR 0039).
	TCP []TCPRoute
	// PlainHTTP serves the public routes over plain HTTP on port 80 instead
	// of redirecting to HTTPS: the cluster obtains no certificates.
	PlainHTTP bool
	// ProxyProtocol are the prefixes of load balancers whose connections
	// start with a PROXY protocol header naming the client; the client's
	// address then counts as the connection's own. Only these may send it.
	ProxyProtocol []string
}

Config is the complete ingress configuration for a node.

func FromProto

func FromProto(p *armadav1.ProxyConfig) Config

FromProto converts the wire format.

func (Config) TCPBackends

func (c Config) TCPBackends() map[string]bool

TCPBackends returns the names of the backends that serve TCP.

func (Config) TCPPorts

func (c Config) TCPPorts() []int

TCPPorts returns the distinct ports of the TCP routes, sorted.

func (Config) ToProto

func (c Config) ToProto() *armadav1.ProxyConfig

ToProto converts to the wire format.

func (Config) Validate

func (c Config) Validate() error

Validate re-checks every field that reaches generated proxy configuration. The server validates specs too; this is defense in depth against a bug or a compromised control plane injecting configuration directives.

type Driver

type Driver interface {
	// Apply makes the proxy serve cfg. On failure the previous configuration
	// stays active.
	Apply(ctx context.Context, cfg Config) error
	// Health reports whether the proxy is running and responsive.
	Health(ctx context.Context) error
}

Driver applies ingress configuration to the local proxy.

type LoadReader

type LoadReader interface {
	// Load returns, per server name for every server the proxy routes to,
	// the requests in progress (being served or queued) and the total
	// requests sent to it so far.
	Load(ctx context.Context) (map[string]ServerLoad, error)
}

LoadReader is implemented by drivers that can count the requests in progress per server, which the autoscaler uses (ADR 0020).

type Rule

type Rule struct {
	Host        string
	PathPrefix  string
	StripPrefix bool
	Backend     string
	Internal    bool
	// Allow, for internal rules on nodes that know their callers, lists
	// the app IDs that may call (the app itself included); empty lets
	// every app of the backend's space (ADR 0026).
	Allow []string
}

Rule routes requests for Host whose path is PathPrefix or starts with PathPrefix + "/" to Backend. Internal rules serve <app>.internal on the internal frontend only; the others serve the public frontends only.

type Server

type Server struct {
	Name    string
	Address string
	// Weight is the server's share of its backend's requests, 1 to
	// MaxWeight; 0 means 1 (traffic splitting, ADR 0022).
	Weight int
}

Server is one replica.

func (Server) EffectiveWeight

func (s Server) EffectiveWeight() int

EffectiveWeight is the weight the proxy applies.

type ServerLoad

type ServerLoad struct {
	InFlight int64
	// Total counts requests; it keeps growing across reloads, and may start
	// over when the proxy crashes or the agent restarts.
	Total int64
}

ServerLoad is one server's load.

type TCPRoute

type TCPRoute struct {
	Port    int
	Backend string
	Allow   []string
}

TCPRoute sends connections to Port on a node's bridge gateway from apps of the backend's space to Backend, which then serves plain TCP (ADR 0039). A port serves at most one backend per space: the caller's space picks it. Allow, when set, lists the app IDs that may connect (the app itself included); empty lets every app of the space.

Directories

Path Synopsis
Package fake provides an in-memory proxy.Driver for tests.
Package fake provides an in-memory proxy.Driver for tests.
Package haproxy implements proxy.Driver with HAProxy running as an Armada-managed system container.
Package haproxy implements proxy.Driver with HAProxy running as an Armada-managed system container.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL