Documentation
¶
Overview ¶
Package envoy_validate provides functions to build representative Envoy bootstrap JSON configurations derived from the aether node-agent's actual xDS proxy builders. The resulting configs are validated with "envoy --mode validate" in the test to catch structural regressions before production.
Three scenarios are modelled:
- Node proxy – per-pod inbound (mTLS) + outbound HTTP listener, ORIGINAL_DST passthrough cluster, per-pod app cluster, EDS service cluster with SPIRE mTLS.
- Capture – transparent-capture listener, HTTP + TCP service clusters, passthrough chain.
- Edge – service EDS cluster with direct-to-SPIRE SDS, spire_agent static cluster.
Custom extensions (aether_stats) that require the custom Envoy binary are stripped before serialisation so that stock Envoy can validate the structural correctness of the config.
Index ¶
- Constants
- func CaptureBootstrapJSON() ([]byte, error)
- func CaptureRouteTargetBootstrapJSON() ([]byte, error)
- func CaptureTCPRouteBootstrapJSON() ([]byte, error)
- func CaptureTLSRouteBootstrapJSON() ([]byte, error)
- func CaptureUDPBootstrapJSON() ([]byte, error)
- func EdgeBootstrapJSON() ([]byte, error)
- func L4TCPBackendClusterA() string
- func L4TCPBackendClusterB() string
- func L4TLSBackendClusterA() string
- func L4TLSBackendClusterB() string
- func L4TLSParentFloorCluster() string
- func L4UDPBackendCluster() string
- func NodeBootstrapJSON() ([]byte, error)
- func NodeCleartextBootstrapJSON() ([]byte, error)
- func NodeUDSBootstrapJSON() ([]byte, error)
- func OutboundZeroVhostRouteBootstrapJSON() ([]byte, error)
- func UnpinnedInboundChains(bootstrapJSON []byte) ([]string, error)
- func UnpinnedMeshClusters(bootstrapJSON []byte) ([]string, error)
Constants ¶
const ( // L4TCPParentClusterIP and L4TLSParentClusterIP are the parent Services' // ClusterIPs: the /32 every chain of that leg matches on. L4TCPParentClusterIP = "10.96.2.20" L4TLSParentClusterIP = "10.96.2.30" // L4TCPWeightA and L4TCPWeightB are the TCPRoute fixture's backendRef // weights. Deliberately unequal and not co-prime with each other's sum, so // a builder that normalised or swapped them would be visible. L4TCPWeightA = 75 L4TCPWeightB = 25 // L4SNIAlpha and L4SNIBravo are the TLSRoute fixture's two hostnames — one // TLSRoute object each, because TLSRoute.Spec.Hostnames is route-level. L4SNIAlpha = "a.l4.test" L4SNIBravo = "b.l4.test" // L4UDPBackendPort is the backend's APPLICATION UDP port. The UDP floor has // no inbound mTLS hop, so udp_proxy dials this port directly. L4UDPBackendPort = 9001 )
Variables ¶
This section is empty.
Functions ¶
func CaptureBootstrapJSON ¶
CaptureBootstrapJSON builds the transparent-capture bootstrap config and returns its JSON representation.
func CaptureRouteTargetBootstrapJSON ¶
CaptureRouteTargetBootstrapJSON builds a bootstrap whose listener inlines the cap_http RouteConfiguration for a GAMMA route TARGET addressed on its REAL Service port (proposal 023 M2): the vhost carries "<svc>.<ns>.svc.cluster.local:<realPort>" domains and the GAMMA rules route to SA-backed backend clusters. Validating it through "envoy --mode validate" proves the M2 route table (real-port domains + path-based GAMMA action) is structurally accepted, complementing the Go-level captureVhosts unit test.
func CaptureTCPRouteBootstrapJSON ¶
CaptureTCPRouteBootstrapJSON builds a capture bootstrap whose per-ClusterIP floor chain is a TCPRoute-weighted tcp_proxy (proposal 018 Phase 3b) over two backends, 75/25.
The weighted form is what a TCPRoute produces and what the floor chain never carries without one, so this is the only place in the harness where Envoy parses a TcpProxy_WeightedClusters at all.
func CaptureTLSRouteBootstrapJSON ¶
CaptureTLSRouteBootstrapJSON builds a capture bootstrap carrying two TLSRoute SNI chains ALONGSIDE the parent's TCP floor chain on one listener.
The three chains all match prefix_ranges <ClusterIP>/32; two of them add server_names and one does not. Envoy resolves that by specificity — SNI match wins, no SNI match falls through to the floor — and rejects filter chains it cannot disambiguate, so `--mode validate` accepting this listener is the structural half of the fall-through behaviour #868 asks for.
func CaptureUDPBootstrapJSON ¶
CaptureUDPBootstrapJSON builds the connection-less UDP capture listener plus the plaintext "udp:" cluster it routes to (proposal 018 Phase 3b).
SCOPE, deliberately narrow: this models DELIVERY only. udp_proxy's route specifier here is a bare Cluster taken from the first backend of the lexicographically first service, so backend SELECTION is not expressible and weights are discarded — issue #873. An assertion that UDP picks between backends would fail by design, so there is none.
func EdgeBootstrapJSON ¶
EdgeBootstrapJSON builds the edge proxy bootstrap config and returns its JSON representation.
func L4TCPBackendClusterA ¶
func L4TCPBackendClusterA() string
L4TCPBackendClusterA and friends are the data-plane cluster names the L4 fixtures reference, exported so the test asserts on the names the builders actually emitted rather than re-deriving them from a second copy of the naming rule.
func L4TCPBackendClusterB ¶
func L4TCPBackendClusterB() string
L4TCPBackendClusterB is the second TCPRoute backend's TCP floor cluster.
func L4TLSBackendClusterA ¶
func L4TLSBackendClusterA() string
L4TLSBackendClusterA is the a.l4.test SNI chain's backend cluster.
func L4TLSBackendClusterB ¶
func L4TLSBackendClusterB() string
L4TLSBackendClusterB is the b.l4.test SNI chain's backend cluster.
func L4TLSParentFloorCluster ¶
func L4TLSParentFloorCluster() string
L4TLSParentFloorCluster is the TLS parent's own TCP floor cluster: where a connection whose SNI matches no TLSRoute deliberately lands.
func L4UDPBackendCluster ¶
func L4UDPBackendCluster() string
L4UDPBackendCluster is the UDPRoute backend's plaintext UDP cluster.
func NodeBootstrapJSON ¶
NodeBootstrapJSON builds the core node-proxy bootstrap config and returns its JSON representation (after stripping custom extensions).
func NodeCleartextBootstrapJSON ¶
NodeCleartextBootstrapJSON builds the SPIRE-off (cleartext) node-proxy bootstrap and returns its JSON. It exercises the cleartext inbound listener — a single default HCM chain with no downstream mTLS transport socket — so the offline `envoy --mode validate` gate covers the MESH-HTTP-on-kind path, not just mTLS.
func NodeUDSBootstrapJSON ¶
NodeUDSBootstrapJSON builds the UDS-delivery (proposal 034 Phase 1) node-proxy bootstrap and returns its JSON. It exercises the pipe app clusters (one per declared port, all dialing the same socket, no upstream bind config) and the HTTP/1.1 active health check over a pipe upstream, so stock Envoy proves the pipe delivery config is accepted.
func OutboundZeroVhostRouteBootstrapJSON ¶
OutboundZeroVhostRouteBootstrapJSON builds a bootstrap whose listener inlines the out_http RouteConfiguration the agent publishes when it has NOTHING to publish — zero service virtual hosts, i.e. the local-only start of issue #817.
That table used not to be emitted at all, which under delta ADS meant the egress listener's RDS subscription was answered with silence, warmed out, and went active with no routes (404 NR route_not_found on everything). It is now unconditional, so what a real Envoy has to accept is a RouteConfiguration consisting of the on-demand catch-all and nothing else: the liveness direct-response, the mesh-authority safe_regex → cluster_header ODCDS route, and the hard 404 fallthrough. Inlining it as a static route_config is the only way this offline gate can see an RDS-delivered table at all.
func UnpinnedInboundChains ¶
UnpinnedInboundChains returns "<listener>/<chain>" for every filter chain in a generated bootstrap whose DownstreamTlsContext requires a client certificate but carries NO match_typed_subject_alt_names (issue #843).
require_client_certificate on its own proves only that SOME certificate this trust bundle signs was presented — any mesh workload, and anything else the bundle happens to sign. The inbound HCM then stamps that certificate's URI SAN into XFCC with SANITIZE_SET, and RBAC/ext_authz decisions key on it, so an unpinned inbound socket silently weakens every XFCC-derived rule.
`envoy --mode validate` ACCEPTS an unpinned context (the same fail-open direction #832 found on the upstream side), so this has to be a config-shape assertion over the generated bytes rather than something the validate below can catch. It runs on the exact bytes handed to Envoy.
Scope is structural, never an allow-list: a chain is checked precisely when it requires a client certificate. The edge's downstream contexts do NOT — external callers have no mesh identity — so they are out of scope automatically, and a NEW mTLS-terminating chain is in scope the moment it sets the field.
func UnpinnedMeshClusters ¶
UnpinnedMeshClusters returns the names of every upstream TLS context in a generated bootstrap that carries NO match_typed_subject_alt_names — i.e. every cluster whose handshake would prove trust-domain membership and nothing else, so any mesh workload satisfies it (issue #832).
It is the config-shape half of that issue's gate, and it runs over the exact bytes handed to `envoy --mode validate`: Envoy ACCEPTS an unpinned validation context, so this is a shape a passing validate can never catch. Nothing here is allow-listed by name — a cluster is checked precisely when it has an UpstreamTlsContext, so the passthrough, app, health, xds, spire_agent and waypoint-ingress clusters (no TLS at all) are out of scope automatically, and a NEW mesh cluster added to a builder is in scope the moment it grows one.
Each returned name is "<cluster>" for a plain transport_socket or "<cluster>/<match>" for a transport_socket_matches entry (the per-source mTLS shape, where the pin lives on every match INCLUDING the node-identity on_no_match one).
Types ¶
This section is empty.
Directories
¶
| Path | Synopsis |
|---|---|
|
Command generate-envoy-bootstrap emits representative Envoy bootstrap JSON files into --out for offline inspection or CI artifact storage.
|
Command generate-envoy-bootstrap emits representative Envoy bootstrap JSON files into --out for offline inspection or CI artifact storage. |