{"id":2493,"library":"envoy-data-plane","title":"Envoy Data Plane API Python Dataclasses","description":"The `envoy-data-plane` library provides Python dataclasses that represent the Envoy Data-Plane API. It is designed to be a helper for generating Envoy configuration using Python scripts, offering benefits like IDE autocompletion and basic validation for custom Envoy control planes. The library is a conversion of the official `envoyproxy/data-plane-api` definitions into Python dataclasses, typically leveraging a tool like `betterproto`.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/cetanu/envoy_data_plane","tags":["envoy","data-plane","api","xds","configuration","dataclasses","networking","proxy"],"install":[{"cmd":"pip install envoy-data-plane","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"Imports follow the proto package structure, directly exposing dataclass representations of Envoy API types (e.g., Listener, Cluster, RouteConfiguration) from their respective v3 modules.","symbol":"Listener","correct":"from envoy.config.listener.v3.listener import Listener"},{"note":"Used for defining HTTP routing rules within Envoy.","symbol":"RouteConfiguration","correct":"from envoy.config.route.v3.route import RouteConfiguration"}],"quickstart":{"code":"from envoy.config.listener.v3.listener import Listener\nfrom envoy.config.listener.v3.listener_components import Filter, FilterChain\nfrom envoy.extensions.filters.network.http_connection_manager.v3.http_connection_manager import HttpConnectionManager\n\n# Define a simple HTTP connection manager filter\nhttp_filter = HttpConnectionManager(\n    stat_prefix=\"ingress_http\",\n    route_specifier=HttpConnectionManager.RouteSpecifier(route_config_name=\"local_route\")\n)\n\n# Define a network filter chain with the HTTP connection manager\nfilter_chain = FilterChain(\n    filters=[\n        Filter(\n            name=\"envoy.filters.network.http_connection_manager\",\n            typed_config=http_filter.to_json_string()\n        )\n    ]\n)\n\n# Define an HTTP listener\nlistener = Listener(\n    name=\"listener_0\",\n    address=Listener.Address(\n        socket_address=Listener.Address.SocketAddress(\n            address=\"0.0.0.0\",\n            port_value=8080\n        )\n    ),\n    filter_chains=[filter_chain]\n)\n\n# Print the generated Envoy Listener configuration (usually serialized to YAML or JSON for Envoy)\nimport json\nprint(json.dumps(listener.to_dict(), indent=2))\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure all imports and configuration strictly adhere to the `v3` package structure (e.g., `envoy.config.listener.v3.listener`).","message":"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.","severity":"breaking","affected_versions":"<= 1.x (of Envoy data plane API)"},{"fix":"Understand that the library facilitates configuration generation; it does not handle gRPC xDS server implementation, state management, or pushing configuration to Envoy instances.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}