EgressGateway

API Group: clrk.apoxy.dev/v1alpha1

Operations

List EgressGateway

GET/apis/clrk.apoxy.dev/v1alpha1/egressgateways

List EgressGateway

Response

200: OK

List EgressGateway

GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways

List EgressGateway

Response

200: OK

Create EgressGateway

POST/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways

create an EgressGateway

Request Body

Spec fields (EgressGatewaySpec):

Field	Type	Description
`defaultPolicy`	string	DefaultPolicy applies to traffic that matches no attached route. (required)
`dns`	EgressDNSSpec	DNS configures the Egress Gateway's DNS resolver. Defaults to LookupFamily=V4Preferred.
`listeners`	EgressListener[]	Listeners declare interception capabilities by protocol layer. Routes attach to a specific listener by name via parentRef.sectionName. (required)
`otlp`	OTLPLogsSinkSpec	OTLP configures L7 capture for this EgressGateway. The controller-manager always persists captured request/response pairs to its embedded ClickHouse and additionally re-exports them to OTLP.Endpoint when set. L7 capture is always on for HTTP and MITM-terminated TLS listeners; this field shapes the re-export destination and the body-capture bounds.
`requestTimeout`	Duration	RequestTimeout caps the duration of a single outbound request transiting this gateway. Applied to the catch-all HTTPRoute's Request and BackendRequest timeouts. Defaults to 5m when unset — chosen to cover AI-provider streaming completions (Anthropic / OpenAI SSE responses routinely run 30-60s; reasoning models can stream several minutes). Envoy Gateway's bare default of 15s 504's those mid-stream, so a generous clrk-side default keeps the AI-runtime case working out of the box. Operators wanting a tighter cap (e.g. test environments) can override; per-route overrides are not supported today — every flow through this EG shares the cap.
`upstreamTLS`	EgressUpstreamTLSSpec	UpstreamTLS adjusts how the EG-managed Envoy validates TLS when re-encrypting traffic to upstreams (the egress dial after MITM).

Response

200: OK
201: Created
202: Accepted

Delete All EgressGateway

DELETE/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways

Delete collection of EgressGateway

Response

200: OK

Get EgressGateway

GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways/{name}

Get the specified EgressGateway

Response

200: OK

Replace EgressGateway

PUT/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways/{name}

Replace the specified EgressGateway

Request Body

Spec fields (EgressGatewaySpec):

Field	Type	Description
`defaultPolicy`	string	DefaultPolicy applies to traffic that matches no attached route. (required)
`dns`	EgressDNSSpec	DNS configures the Egress Gateway's DNS resolver. Defaults to LookupFamily=V4Preferred.
`listeners`	EgressListener[]	Listeners declare interception capabilities by protocol layer. Routes attach to a specific listener by name via parentRef.sectionName. (required)
`otlp`	OTLPLogsSinkSpec	OTLP configures L7 capture for this EgressGateway. The controller-manager always persists captured request/response pairs to its embedded ClickHouse and additionally re-exports them to OTLP.Endpoint when set. L7 capture is always on for HTTP and MITM-terminated TLS listeners; this field shapes the re-export destination and the body-capture bounds.
`requestTimeout`	Duration	RequestTimeout caps the duration of a single outbound request transiting this gateway. Applied to the catch-all HTTPRoute's Request and BackendRequest timeouts. Defaults to 5m when unset — chosen to cover AI-provider streaming completions (Anthropic / OpenAI SSE responses routinely run 30-60s; reasoning models can stream several minutes). Envoy Gateway's bare default of 15s 504's those mid-stream, so a generous clrk-side default keeps the AI-runtime case working out of the box. Operators wanting a tighter cap (e.g. test environments) can override; per-route overrides are not supported today — every flow through this EG shares the cap.
`upstreamTLS`	EgressUpstreamTLSSpec	UpstreamTLS adjusts how the EG-managed Envoy validates TLS when re-encrypting traffic to upstreams (the egress dial after MITM).

Response

200: OK
201: Created

Update EgressGateway

PATCH/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways/{name}

Partially update the specified EgressGateway

Response

200: OK
201: Created

Delete EgressGateway

DELETE/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/egressgateways/{name}

delete an EgressGateway

Response

200: OK
202: Accepted

Schema Reference

EgressDNSSpec

Field	Type	Description
`lookupFamily`	string	LookupFamily selects which IP families the resolver considers when resolving upstream hostnames. Defaults to V4Preferred.

EgressListener

Field	Type	Description
`allowedRoutes`	AllowedRoutes	AllowedRoutes constrains which route kinds and namespaces may attach. Reuses the standard GW API AllowedRoutes type.
`name`	string	Name identifies this listener. Routes reference it via parentRef.sectionName (standard GW API field). (required)
`port`	integer (int32)	Port constrains interception to a single destination port. If unset, all ports are intercepted at this protocol layer.
`protocol`	string	Protocol selects the interception layer. (required)
`tls`	EgressListenerTLS	TLS configures TLS handling. Required when protocol=TLS, optional for HTTP (enables HTTPS MITM). Invalid for TCP/UDP.

EgressListenerTLS

Field	Type	Description
`caCertRef`	SecretObjectReference	CACertRef references a Secret with the CA cert+key for on-the-fly cert generation. Required when mode=Terminate.
`mode`	string	Mode controls TLS handling. Passthrough: SNI-route only, no termination. Terminate: MITM decrypt for L7 inspection, re-encrypt to upstream. (required)

OTLPLogsSinkSpec

Field	Type	Description
`captureBody`	BodyCaptureSpec	CaptureBody bounds the request/response body bytes captured by ext_proc and emitted as OTLP log records. Defaults: 64KiB per direction; capture application/json, application/x-ndjson, text/event-stream.
`endpoint`	string	Endpoint is the OTLP/HTTP base URL the controller-manager forwards captured signals to (e.g. "https://otel.example.com"). Empty disables the customer fan-out; signals are still kept in the embedded ClickHouse.
`headers`	object	Headers are added to every forwarded OTLP export — typically used to carry authentication tokens for the customer endpoint.

BodyCaptureSpec

Field	Type	Description
`includeContentTypes`	string[]	IncludeContentTypes limits body capture to these Content-Type prefixes. Empty means the default set (application/json, application/x-ndjson, text/event-stream).
`maxBytes`	integer (int32)	MaxBytes caps the captured body size per direction. Bodies larger than this are truncated; the log record carries a truncated marker.

EgressUpstreamTLSSpec

Field	Type	Description
`additionalTrustBundleSecretRef`	SecretObjectReference	AdditionalTrustBundleSecretRef references a Secret carrying one or more CA certificates (PEM, under any data key) that Envoy should trust in addition to the system bundle. Used for private upstreams whose certs aren't anchored in a public CA. All non-empty values in the Secret's `data` map are concatenated and appended to the system bundle inside the Envoy pod via an init container; the main Envoy container reads the merged bundle from the same well-known path it always has.
`hostAliases`	HostAlias[]	HostAliases programs the EG-managed Envoy Pod's spec.hostAliases. Each entry maps an IP to one or more hostnames; the kubelet writes them into the pod's /etc/hosts ahead of the cluster DNS lookup chain. Use this to point Envoy's dynamic_forward_proxy resolver at a specific IP for a given upstream hostname, e.g. an in-cluster stub pretending to be api.openai.com without globally hijacking the cluster's CoreDNS.