Proxy

API Group: core.apoxy.dev/v1alpha2

Operations

List Proxies

GET/apis/core.apoxy.dev/v1alpha2/proxies

List Proxy

Response

200: OK

Create Proxy

POST/apis/core.apoxy.dev/v1alpha2/proxies

Create a Proxy

Request Body

Spec fields (ProxySpec):

Field	Type	Description
`provider`	string	Provider is the infrastructure provider where the proxy will be deployed. One of `cloud`, `kubernetes` or `unmanaged`. Defaults to "cloud" provider.
`shutdown`	ShutdownConfig	Shutdown configuration for the proxy.
`telemetry`	ProxyTelementry	Telemetry configures telemetry for the Proxy.
`envoy`	EnvoyConfig	Envoy selects the Envoy binary that unmanaged replicas run. Not configurable for cloud proxies.

Response

200: OK
201: Created
202: Accepted

Delete All Proxies

DELETE/apis/core.apoxy.dev/v1alpha2/proxies

Delete collection of Proxy

Response

200: OK

Get Proxy

GET/apis/core.apoxy.dev/v1alpha2/proxies/{name}

Get the specified Proxy

Response

200: OK

Replace Proxy

PUT/apis/core.apoxy.dev/v1alpha2/proxies/{name}

Replace the specified Proxy

Request Body

Spec fields (ProxySpec):

Field	Type	Description
`provider`	string	Provider is the infrastructure provider where the proxy will be deployed. One of `cloud`, `kubernetes` or `unmanaged`. Defaults to "cloud" provider.
`shutdown`	ShutdownConfig	Shutdown configuration for the proxy.
`telemetry`	ProxyTelementry	Telemetry configures telemetry for the Proxy.
`envoy`	EnvoyConfig	Envoy selects the Envoy binary that unmanaged replicas run. Not configurable for cloud proxies.

Response

200: OK
201: Created

Update Proxy

PATCH/apis/core.apoxy.dev/v1alpha2/proxies/{name}

Partially update the specified Proxy

Response

200: OK
201: Created

Delete Proxy

DELETE/apis/core.apoxy.dev/v1alpha2/proxies/{name}

Delete a Proxy

Response

200: OK
202: Accepted

Schema Reference

ShutdownConfig

Field	Type	Description
`drainTimeout`	Duration	DrainTimeout is the amount of time to wait before terminating the proxy. Defaults to 30s.
`minimumDrainTime`	Duration	MinimumDrainTime is the minimum amount of time to wait before terminating the proxy. This is useful for ensuring downstream loadbalancers have enough time to pick up healthcheck status and drain the backend target. Can not be less than DrainTimeout. Defaults to 30s.

EnvoyConfig

Only for proxies with provider: unmanaged, where you run the data plane yourself. Apoxy picks the Envoy version for cloud proxies, and the API rejects this field on them.

Field	Type	Description
`version`	string	Envoy release tag, for example `v1.35.13`. Replicas download the matching release. When the backplane runs with contrib filters enabled, they download the contrib build.
`releaseURL`	string	Direct URL of a static Envoy binary for the replica architecture. Takes precedence over `version`.

$proxy.yamlYAML

apiVersion: core.apoxy.dev/v1alpha2
kind: Proxy
metadata:
  name: default
spec:
  provider: unmanaged
  shutdown:
    minimumDrainTime: 30s
    drainTimeout: 30s
  envoy:
    version: v1.35.13

Checksum verification

If a file with the same URL plus .sha256 is next to the binary, the download is checked against it. The first token of that file must be the hex SHA-256 digest, so sha256sum output works as is. A digest that does not match stops Envoy from starting. Without the .sha256 file the binary runs unverified and the replica logs a warning.

Precedence

Backplane flags --envoy_release_url and --envoy_version.
spec.envoy.releaseURL.
spec.envoy.version.
The Envoy version in the backplane image, currently v1.35.13.

A change to spec.envoy takes effect the next time a replica starts, for example on a rollout of the backplane Deployment. It does not change a running Envoy.

Apoxy static binaries

Apoxy publishes verified static builds, each with a .sha256 file next to it:

$terminalTXT

https://storage.googleapis.com/apoxy-public-artifacts/envoy/<version>/envoy-contrib-<version-without-v>-linux-<arch>

<arch> is x86_64 or aarch_64. For example:

$proxy.yamlYAML

spec:
  envoy:
    releaseURL: https://storage.googleapis.com/apoxy-public-artifacts/envoy/v1.35.13/envoy-contrib-1.35.13-linux-x86_64

ProxyTelementry

Field	Type	Description
`accessLogs`	ProxyAccessLogs	AccessLogs configures how access logs are handled. Note that access logs cannot be disabled.
`contentLogs`	ProxyContentLogs	ContentLogs configures how request and response body content are handled. Also refered to as Taps in Envoy. Disabled by default.
`otelCollectorConfig`	LocalObjectReference	Custom OpenTelemetry collector configuration. Only supported for unmanaged proxies. This must be a ConfigMap or a Secret in the same namespace as Backplane.
`thirdPartySinks`	ThirdPartySinks	For enabling third party integrations. This is only supported for cloud proxies.
`tracing`	ProxyTracing	Tracing configures how tracing is handled. Disabled by default.

ProxyAccessLogs

Field	Type	Description
`json`	object	If set, additional fields to add to the default Envoy access logs. Envoy command operators can be used as values for fields. Note that attempting to override default fields will not have any effect.

ProxyContentLogs

Field	Type	Description
`requestBodyEnabled`	boolean	Enable request body content logging. (required)
`responseBodyEnabled`	boolean	Enable response body content logging. (required)

LocalObjectReference

Field	Type	Description
`group`	string	Group is the API Group of the referenced object. (required)
`name`	string	Name is the name of the referenced object. (required)

ThirdPartySinks

Field	Type	Description
`axiomLogs`	APIKey	AxiomLogs is the API key for Axiom logs.
`axiomTraces`	APIKey	AxiomTraces is the API key for Axiom traces.
`datadogLogs`	APIKey	DatadogLogs is the API key for Datadog logs.
`datadogTraces`	APIKey	DatadogTraces is the API key for Datadog traces.
`openTelemetrySinks`	OpenTelemetrySink[]	OpenTelemetrySink is the OpenTelemetry sink.

APIKey

Field	Type	Description
`key`	string	Key is the API key.
`keyData`	string	KeyData is the base64 encoded API key.

ProxyTracing

Field	Type	Description
`enabled`	boolean	Enable tracing. (required)
`tags`	object	Additional tags to populate on the traces.