aether.config.v1 — The CRD schemas. MeshConfig, HTTPFilter, EdgeConfig and EndpointPolicy are Kubernetes custom resources, but their .spec is not written in Go — it is these messages. common/apis/config/v1 wraps them with the deepcopy and JSON glue Kubernetes needs and adds no fields, so what is documented here is exactly what a manifest may contain.
Rendered by protoc from api/aether/config/v1/ when this site was built, so it
cannot drift from the compiled schema — there is no committed copy of this page.
Field constraints are carried as buf.validate options and are not shown here;
read the .proto for those.
EdgeConfigSpec is the .spec of the EdgeConfig custom resource (proposal 029):
Envoy edge-hardening + HTTP/3 settings for a set of edge Gateways, resolved via the
native Gateway API parametersRef chain (GatewayClass default + Gateway
infrastructure override, proto.Merge). Every field is OPTIONAL with a best-practice
compiled default — an empty EdgeConfig still hardens the edge. EXPLICIT presence so
proto.Merge distinguishes "unset (inherit)" from an explicit zero.
Field
Type
Label
Description
use_remote_address
google.protobuf.BoolValue
optional
use_remote_address: the edge trusts the immediate downstream connection address as the client and manages XFF from it (correct for an internet-facing edge; forgeable XFF otherwise). Default true.
xff_num_trusted_hops
google.protobuf.UInt32Value
optional
xff_num_trusted_hops: additional trusted proxy hops in front of the edge; feeds the HCM and the geoip filter. Default 0.
headers_with_underscores_action: how to treat request headers with underscores (header-smuggling defense). Default HEADERS_WITH_UNDERSCORES_ACTION_REJECT_REQUEST.
EndpointPolicySpec is the .spec of the EndpointPolicy custom resource — the
service-scoped way to declare Unix-domain-socket delivery (proposal 034 Phase 1b).
It attaches to a Service with the Gateway API policy-attachment shape (GEP-713
direct attachment), the same rails HTTPFilter rides.
The equivalent pod annotation (endpoint.aether.io/uds-socket) takes precedence:
this CR is the service-level default. A policy naming a volume the target's pods
do not carry degrades to TCP delivery, leaving the endpoint unpromoted — never a
blackhole. NOT exported cross-cluster (proposal 026): delivery is node-local.
target_ref names the Service this policy attaches to. Same-namespace by construction (PolicyTargetRef carries no namespace); the supported target is group "" (core), kind "Service". The name is matched against the mesh service key "<ns>/<svc>" (020 Part 1).
uds_socket
string
uds_socket is "<volume-name>/<socket-file>": the emptyDir volume declared by the target service's pods and the socket file the app creates inside it. The rules here are shape only — exactly one "/", no empty component, a sane upper bound. The authoritative check is the admission webhook, which runs the agent's own resolver (common/udspath) so the segment rules AND the 107-byte AF_UNIX sun_path budget are enforced at apply time. The budget leaves roughly 16 characters for this whole value under the default kubelet pods directory.
ExtAuthzRoute is the per-route external-authorization form (renders to Envoy's
ExtAuthzPerRoute). Attaching it ENABLES the (otherwise disabled) system ext_authz
filter for the targeted route/service.
context_extensions are passed to the authz service with every check for the targeted routes — the per-route policy parameters (e.g. {"policy": "payments-rw"}).
disable_request_body_buffering
bool
disable_request_body_buffering skips sending the request body to the authz service.
disabled
bool
disabled exempts the targeted route from a broader (service-wide) authz filter.
HTTPFilterSpec is the .spec of the HTTPFilter custom resource — the
proxy-extension escape hatch (proposal 025). An HTTPRoute/GRPCRoute rule references
it through a standard Gateway API ExtensionRef filter; aether attaches the named
Envoy HTTP filter to the route's typed_per_filter_config (and adds it to the HCM
chain default-disabled). The body is opaque Envoy config, validated fail-closed by
the aether-controller admission webhook (in-process proto-validate: @type resolve +
protoc-gen-validate), NOT by the CRD's OpenAPI schema. See docs/proposals/025.
Field
Type
Label
Description
filter
string
filter is the Envoy HTTP filter name (e.g. "envoy.filters.http.header_to_metadata"). It MUST be in aether's allow-list of filters the proxy build compiles in; the webhook rejects others.
typed_config
google.protobuf.Any
typed_config is the opaque Envoy filter config (the filter's typed_config Any). Carried verbatim into the route's typed_per_filter_config. The @type must resolve to a known Envoy message and pass its protoc-gen-validate constraints — enforced by the webhook, not here.
scope selects where the filter applies (proposal 025 M4 semantics): - ROUTE (default, incl. UNSPECIFIED): default-disabled in the HCM chain, enabled per route via ExtensionRef / targetRef typed_per_filter_config. - CHAIN: service-wide ALWAYS-ON — requires target_refs naming a Service; the filter is enabled at the service's capture vhost (vhost-level typed_per_filter_config), applying to ALL of that service's traffic. At most ONE chain-scope filter per service (webhook-enforced; the projector tie-breaks deterministically). Position in the chain is aether-owned (the extension anchor); a per-route ExtensionRef overrides it (Envoy most-specific-wins).
target_refs attaches this filter to Gateway API objects (policy attachment, GEP-713/-2648 direct) — proposal 025 M3. The supported kind is Service (core group): the filter then applies to EVERY route targeting that Service, for all its callers (object-wide), in addition to any per-route ExtensionRef. Targets are same-namespace as this HTTPFilter. A Service-attached filter is a class-1 payload that rides proposal 026's config channel to peer clusters.
ext_authz opts this route/service into the node-local authorization sidecar (proposal 027). TYPED-ONLY: the transport (target/timeout/failure mode) is system-owned on the chain entry — this form carries only what ExtAuthzPerRoute can: per-route policy parameters and toggles. Requires the sidecar to be enabled on the cluster (proxy.authzSidecar.enabled); the agent drops it otherwise (logged) so a stray policy cannot NACK the proxy.
rbac is the TYPED form of envoy.filters.http.rbac: LOCAL authorization — in-process allow/deny by verified peer identity (SPIFFE SAN on the inbound path; the aether.source metadata on egress) and path/method, with NO sidecar, no per-request RPC, and no failure mode (policy is config). mode AUDIT evaluates + counts (rbac.shadow_denied stats) without enforcing — dry-run a policy on live traffic, then flip to ENFORCE (identical rules by construction).
header_to_metadata is the TYPED form of envoy.filters.http.header_to_metadata (proposal 025 M4 typed promotion): the one allow-listed filter Gateway API cannot express (it powers subset routing). Mutually exclusive with filter/typed_config — set exactly one authoring form; aether renders the Envoy proto internally.
HeaderToMetadata promotes the common header_to_metadata use to typed config: each
rule copies a request header's value into dynamic metadata when present.
INBOUND (proposal 027 M3): destination-side enforcement — the filter is enabled on the TARGET service's own pods' INBOUND listeners, where the caller's verified SPIFFE identity (XFCC) is available. Requires a Service targetRef and (v1) the extAuthz form. NOT propagated cross-cluster: the enforcement point is co-located with the service's pods, so the owning cluster's config is authoritative by construction.
MeshConfigSpec is the .spec of the MeshConfig custom resource — the proxy
data-plane observability override. It is also what the controller projects into
the ConfigMap the agent mounts, and is validated with protovalidate.
Aether is one system: enabling OTEL or SPIRE, the OTLP collector endpoint, and
the mesh domain are system-wide settings inherited by every component
(registrar, agent, proxy) from the aether chart — they are NOT in this message.
MeshConfigSpec only lets the proxy data plane override its own access-log /
tracing / metrics policy; unset fields inherit the aether config. The typed
MeshConfig CRD wrapper (TypeMeta/ObjectMeta/Spec/Status) is hand-written in
meshconfig_types.go. See docs/proposals/015_mesh-config.md.
ProxyTelemetry overrides the proxy data plane's observability policy. Every
field is optional: when unset, the proxy inherits the aether system config
(OTEL enable + collector endpoint, control-plane trace sample rate).
Field
Type
Label
Description
access_logs_enabled
bool
optional
Attach the OTel access logger to every HCM (proposal 014). Unset inherits the aether default (off).
access_log_success_sample_rate
uint32
optional
Percent (0-100) of successful requests logged; failures are always logged. Unset defaults to 100.
tracing_enabled
bool
optional
Generate/propagate W3C trace context and export proxy request spans. Unset inherits the aether default (off).
trace_sample_rate
double
optional
Fraction (0.0-1.0) of requests traced by the proxy. Unset inherits the aether control-plane trace sample rate.
emit_stats_pod
bool
optional
Emit per-pod labels (source_pod/destination_pod) on the aether_stats request counter (raises cardinality). Unset inherits the aether default (off).
SecretProvider selects the backend that resolves an edge downstream-TLS
certificate reference (a Gateway listener's certificateRefs entry) to
certificate material. The edge registers a Provider implementation per value;
new backends are added here and implemented in agent/internal/edge/secret. See
docs/proposals/003_edge-proxy.md.
Name
Number
Description
SECRET_PROVIDER_UNSPECIFIED
0
Defaults to the kubernetes provider.
SECRET_PROVIDER_KUBERNETES
1
A kubernetes.io/tls Secret read via the Kubernetes API.
SECRET_PROVIDER_AWS_SECRETS_MANAGER
2
AWS Secrets Manager (reserved; not implemented yet).