HTTP connection manager

Attachment	Type URL (`@type`)	Per-route override	Build feature
Filter chain (`filters`, terminal)	`type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager`	Not applicable	None

What it does

The HTTP connection manager (HCM) turns the connection's byte stream into HTTP requests, runs each request through its http_filters chain, and routes it with an inline route_config or a route configuration fetched over RDS. It is a terminal filter: exactly one HCM or TCP proxy ends every filter chain, and nothing may follow it.

Minimal configuration

The fragment sits under filter_chains[].filters of a listener:

- name: http_gateway
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
    codec_type: AUTO
    http_filters:
      - name: envoy.filters.http.router
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
          start_child_span: false
    route_config:
      name: local_route
      virtual_hosts:
        - name: backend
          domains: ["*"]
          routes:
            - match: { prefix: "/" }
              route: { cluster: api }

Fields

Field	Type	Required	Default	Description
`codec_type`	enum	No	`AUTO`	`AUTO`, `HTTP1` or `HTTP2`. `HTTP3` is rejected.
`stat_prefix`	string	No	—	Accepted for Envoy compatibility but ignored; Arion logs a warning.
`http_filters`	list	Yes	—	The HTTP filter chain. Must be non-empty and end with the router, which cannot be disabled.
`route_config` / `rds`	oneof	Yes	—	Inline route configuration, or RDS (see below).
`request_timeout`	duration	No	unset	Overall timeout for a downstream request.
`access_log`	list	No	empty	File, stdout or stderr access loggers; see access logs.
`upgrade_configs`	list	No	empty	Enabled protocol upgrades. Only `websocket` is supported; `connect` is rejected.
`use_remote_address`	bool	No	`false`	Use the direct peer address instead of `x-forwarded-for` when determining the client address.
`xff_num_trusted_hops`	uint32	No	`0`	Number of trusted proxy hops counted from the right of `x-forwarded-for`.
`skip_xff_append`	bool	No	`false`	Do not append the client address to `x-forwarded-for`.
`generate_request_id`	bool	No	`true`	Generate `x-request-id` when absent.
`preserve_external_request_id`	bool	No	`false`	Keep an externally supplied `x-request-id` instead of replacing it.
`always_set_request_id_in_response`	bool	No	`false`	Echo `x-request-id` in the response even when the client did not send one.
`tracing`	object	No	unset	Trace sampling and exporter; see below.
`early_header_mutation_extensions`	list	No	empty	`header_mutation` extensions applied before routing.

Any other Envoy HCM field is unsupported: setting one makes Arion refuse to start, which is the compatibility promise.

Route specifier

route_config embeds a full route table (documented in the routes reference). rds subscribes to it over xDS instead; only the aggregated channel is supported:

rds:
  route_config_name: my_routes
  config_source:
    ads: {}

Tracing

tracing accepts client_sampling, random_sampling and overall_sampling (percentages, 0–100), verbose, max_path_tag_length, spawn_upstream_span, and a provider whose typed_config must be type.googleapis.com/envoy.config.trace.v3.OpenTelemetryConfig with a grpc_service and service_name. See tracing.

Ordering and interactions

Within a filter chain the HCM runs after network RBAC, rate limit and connection limit filters have admitted the connection. Its http_filters then run in list order per request, ending in the router; the response traverses filters that act on responses in reverse.