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
- Variables
- func BackendSpace(backend string) string
- func ExcludePrefixes(trusted []string, out []netip.Prefix) []string
- func ParseProxyProtocol(prefixes []string) ([]string, error)
- func ParseTrustedProxies(prefixes []string) ([]string, error)
- type Backend
- type CORS
- type Certificate
- type ClientSetter
- type Config
- type Driver
- type LoadReader
- type Rule
- type Server
- type ServerLoad
- type TCPRoute
Constants ¶
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 )
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.
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.
const MaxCORSMaxAgeSeconds = 86400
MaxCORSMaxAgeSeconds bounds how long browsers may keep a preflight answer.
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.
const MaxWeight = 256
MaxWeight is the largest server weight.
Variables ¶
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.
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 ¶
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 ¶
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 ¶
ParseProxyProtocol checks the prefixes of load balancers that send the PROXY protocol like ParseTrustedProxies: any of them may name any client.
func ParseTrustedProxies ¶
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 Certificate ¶
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 (Config) TCPBackends ¶
TCPBackends returns the names of the backends that serve TCP.
func (Config) ToProto ¶
func (c Config) ToProto() *armadav1.ProxyConfig
ToProto converts to the wire format.
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 ¶
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 ¶
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. |