Envoy Data Plane API Python Dataclasses

Warnings

• breaking Envoy's xDS API v2 was deprecated in Envoy 1.17 and removed in Q1 2021. This library exclusively uses the v3 API definitions. Attempting to use v2 API concepts or older import paths will result in errors.
  Fix: Ensure all imports and configuration strictly adhere to the `v3` package structure (e.g., `envoy.config.listener.v3.listener`).
• gotcha This library provides Python *dataclass representations* of the Envoy Data Plane API. It is not a control plane implementation itself. Users are responsible for building their own control plane logic to generate, manage, and deliver this configuration to Envoy proxies.
  Fix: Understand that the library facilitates configuration generation; it does not handle gRPC xDS server implementation, state management, or pushing configuration to Envoy instances.
• gotcha The `envoyproxy/data-plane-api` GitHub repository, from which this library is derived, is a read-only mirror of the API definitions within the main `envoyproxy/envoy` repository. Updates to the Python library are dependent on its maintainers tracking and converting upstream changes.
  Fix: Monitor the `envoy-data-plane` PyPI and GitHub project for updates. If a specific API version is needed that isn't yet available, consider raising an issue with the maintainers.
• gotcha The library typically uses `betterproto` for dataclass generation, meaning the objects often include methods like `to_dict()` and `to_json_string()` for serialization. Be aware of these methods for converting dataclass objects into a format suitable for Envoy, rather than expecting direct `protobuf` message handling.
  Fix: Utilize the provided serialization methods (e.g., `to_dict()`, `to_json_string()`) on the dataclass instances to obtain the desired JSON or dictionary representation for Envoy configuration.

Install

• pip install envoy-data-plane Install stable release

Imports

• Listener

  from envoy.config.listener.v3.listener import Listener

  Imports follow the proto package structure, directly exposing dataclass representations of Envoy API types (e.g., Listener, Cluster, RouteConfiguration) from their respective v3 modules.
• RouteConfiguration

  from envoy.config.route.v3.route import RouteConfiguration

  Used for defining HTTP routing rules within Envoy.

Quickstart

This quickstart demonstrates how to construct a basic Envoy HTTP Listener configuration using the Python dataclasses provided by the `envoy-data-plane` library. It defines an HTTP connection manager filter and wraps it in a network filter chain, then attaches it to a listener bound to port 8080. The resulting configuration is then serialized to JSON.

from envoy.config.listener.v3.listener import Listener
from envoy.config.listener.v3.listener_components import Filter, FilterChain
from envoy.extensions.filters.network.http_connection_manager.v3.http_connection_manager import HttpConnectionManager

# Define a simple HTTP connection manager filter
http_filter = HttpConnectionManager(
    stat_prefix="ingress_http",
    route_specifier=HttpConnectionManager.RouteSpecifier(route_config_name="local_route")
)

# Define a network filter chain with the HTTP connection manager
filter_chain = FilterChain(
    filters=[
        Filter(
            name="envoy.filters.network.http_connection_manager",
            typed_config=http_filter.to_json_string()
        )
    ]
)

# Define an HTTP listener
listener = Listener(
    name="listener_0",
    address=Listener.Address(
        socket_address=Listener.Address.SocketAddress(
            address="0.0.0.0",
            port_value=8080
        )
    ),
    filter_chains=[filter_chain]
)

# Print the generated Envoy Listener configuration (usually serialized to YAML or JSON for Envoy)
import json
print(json.dumps(listener.to_dict(), indent=2))