Envoy · Schema

Envoy Listener

A listener configuration defines a network address and port where Envoy accepts connections, along with filter chains that process those connections through a pipeline of network and HTTP filters.

Cloud-NativeLoad BalancingProxyService Mesh

Properties

Name	Type	Description
name	string	Unique name for the listener.
address	object	The address the listener listens on for new connections.
filter_chains	array	Filter chains to process connections received by the listener.
listener_filters	array	Filters applied at the listener level before filter chain matching.
traffic_direction	string	Specifies the intended direction of traffic for the listener.
per_connection_buffer_limit_bytes	integer	Soft limit on read and write buffer size per connection.
bind_to_port	boolean	Whether the listener should bind to the port. Used for virtual listeners.
enable_reuse_port	boolean	Whether to use SO_REUSEPORT for the listener socket.
tcp_backlog_size	integer	The maximum length of the TCP pending connections queue.
transparent	boolean	Whether the listener should use transparent mode.
freebind	boolean	Whether to set IP_FREEBIND socket option.
access_log	array	Access log configuration for the listener.
connection_balance_config	object	Balances connections across worker threads.
metadata	object	Metadata for the listener.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.envoyproxy.io/schemas/listener",
  "title": "Envoy Listener",
  "description": "A listener configuration defines a network address and port where Envoy accepts connections, along with filter chains that process those connections through a pipeline of network and HTTP filters.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Unique name for the listener."
    },
    "address": {
      "type": "object",
      "description": "The address the listener listens on for new connections.",
      "properties": {
        "socket_address": {
          "type": "object",
          "properties": {
            "protocol": {
              "type": "string",
              "enum": ["TCP", "UDP"],
              "default": "TCP"
            },
            "address": {
              "type": "string",
              "description": "IP address or hostname to bind to."
            },
            "port_value": {
              "type": "integer",
              "description": "Port number to bind to.",
              "minimum": 0,
              "maximum": 65535
            }
          },
          "required": ["address", "port_value"]
        },
        "pipe": {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "Unix domain socket path."
            },
            "mode": {
              "type": "integer"
            }
          }
        }
      }
    },
    "filter_chains": {
      "type": "array",
      "description": "Filter chains to process connections received by the listener.",
      "items": {
        "type": "object",
        "properties": {
          "filter_chain_match": {
            "type": "object",
            "description": "Match criteria for selecting this filter chain.",
            "properties": {
              "destination_port": {
                "type": "integer"
              },
              "prefix_ranges": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "address_prefix": { "type": "string" },
                    "prefix_len": { "type": "integer" }
                  }
                }
              },
              "server_names": {
                "type": "array",
                "description": "SNI domains to match.",
                "items": { "type": "string" }
              },
              "transport_protocol": {
                "type": "string",
                "description": "Transport protocol to match (e.g., 'tls', 'raw_buffer')."
              },
              "application_protocols": {
                "type": "array",
                "description": "ALPN protocols to match.",
                "items": { "type": "string" }
              }
            }
          },
          "filters": {
            "type": "array",
            "description": "Network filters in the chain.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Name of the filter (e.g., 'envoy.filters.network.http_connection_manager')."
                },
                "typed_config": {
                  "type": "object",
                  "description": "Filter-specific typed configuration."
                }
              },
              "required": ["name"]
            }
          },
          "transport_socket": {
            "type": "object",
            "description": "Transport socket for this filter chain (e.g., TLS).",
            "properties": {
              "name": {
                "type": "string"
              },
              "typed_config": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "listener_filters": {
      "type": "array",
      "description": "Filters applied at the listener level before filter chain matching.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the listener filter (e.g., 'envoy.filters.listener.tls_inspector')."
          },
          "typed_config": {
            "type": "object"
          }
        },
        "required": ["name"]
      }
    },
    "traffic_direction": {
      "type": "string",
      "description": "Specifies the intended direction of traffic for the listener.",
      "enum": ["UNSPECIFIED", "INBOUND", "OUTBOUND"]
    },
    "per_connection_buffer_limit_bytes": {
      "type": "integer",
      "description": "Soft limit on read and write buffer size per connection."
    },
    "bind_to_port": {
      "type": "boolean",
      "description": "Whether the listener should bind to the port. Used for virtual listeners.",
      "default": true
    },
    "enable_reuse_port": {
      "type": "boolean",
      "description": "Whether to use SO_REUSEPORT for the listener socket."
    },
    "tcp_backlog_size": {
      "type": "integer",
      "description": "The maximum length of the TCP pending connections queue."
    },
    "transparent": {
      "type": "boolean",
      "description": "Whether the listener should use transparent mode."
    },
    "freebind": {
      "type": "boolean",
      "description": "Whether to set IP_FREEBIND socket option."
    },
    "access_log": {
      "type": "array",
      "description": "Access log configuration for the listener.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "typed_config": {
            "type": "object"
          },
          "filter": {
            "type": "object"
          }
        }
      }
    },
    "connection_balance_config": {
      "type": "object",
      "description": "Balances connections across worker threads.",
      "properties": {
        "exact_balance": {
          "type": "object"
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Metadata for the listener.",
      "additionalProperties": true
    }
  },
  "required": ["name", "address", "filter_chains"]
}