{"id":5552,"library":"xds-protos","title":"xds-protos","description":"Package `xds-protos` is a collection of ProtoBuf generated Python files for xDS protos (or the data-plane-api). It provides Python bindings for the xDS (eXtensible Discovery Service) APIs, which enable dynamic configuration of proxies and load balancers, primarily used within the gRPC and Envoy ecosystems. The current version is 1.80.0, released on March 30, 2026, and it is actively maintained as part of the gRPC project, with frequent updates that often align with gRPC releases.","status":"active","version":"1.80.0","language":"en","source_language":"en","source_url":"https://github.com/grpc/grpc","tags":["protobuf","grpc","xds","envoy","data-plane-api","networking","service-mesh"],"install":[{"cmd":"pip install xds-protos","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required at runtime for the protobuf messages generated by this library.","package":"protobuf"}],"imports":[{"note":"Common xDS messages are typically found under `envoy.<config|service>.<category>.v3` subpackages.","symbol":"DiscoveryRequest","correct":"from envoy.service.discovery.v3 import discovery_pb2"},{"symbol":"Cluster","correct":"from envoy.config.cluster.v3 import cluster_pb2"},{"note":"Older versions of some xDS types (like TypedStruct) were under the `udpa` package and have since moved to `xds` as part of API generalization.","wrong":"from udpa.type.v1 import typed_struct_pb2","symbol":"TypedStruct","correct":"from xds.type.v3 import typed_struct_pb2"}],"quickstart":{"code":"from envoy.service.discovery.v3 import discovery_pb2\n\n# Create a simple DiscoveryRequest message\nrequest = discovery_pb2.DiscoveryRequest(\n    version_info='1.0.0',\n    node=None, # In a real scenario, this would be a Node message\n    resource_names=['my-cluster'],\n    type_url='type.googleapis.com/envoy.config.cluster.v3.Cluster',\n    response_nonce='some-nonce'\n)\n\nprint(f\"Created DiscoveryRequest: {request}\")\n\n# Accessing fields\nprint(f\"Requested resource names: {request.resource_names}\")","lang":"python","description":"Demonstrates importing a core xDS message (`DiscoveryRequest`) and instantiating it. This package provides the generated message classes for use in xDS clients or servers."},"warnings":[{"fix":"Update import statements to reflect the new `xds.*` package paths (e.g., `from xds.type.v3 import typed_struct_pb2`). Refer to the `cncf/xds` repository for current proto locations.","message":"Some xDS proto types, notably `TypedStruct`, have migrated from the `udpa.type.v1` package to `xds.type.v3`. This changes their Python import paths (e.g., from `udpa.type.v1.typed_struct_pb2` to `xds.type.v3.typed_struct_pb2`). Consumers of specific xDS types should verify their imports, especially when upgrading.","severity":"breaking","affected_versions":"<=1.x.x (exact range varies by specific proto migration)"},{"fix":"Review the official xDS API documentation (e.g., on `envoyproxy.io` or `cncf/xds` GitHub) for `work_in_progress` annotations on specific messages or fields if encountering unexpected changes or instability.","message":"The xDS APIs are constantly evolving, and some features, or even entire protos, are marked as 'work-in-progress'. These entities are subject to breaking changes without prior notice.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that both the xDS client and server are configured to use the same xDS transport protocol variant (either SotW or Delta) and the corresponding proto messages.","message":"xDS utilizes two primary transport protocols: State-of-the-World (SotW) and Delta xDS. These protocols use different request/response protos (`DiscoveryRequest`/`DiscoveryResponse` for SotW vs. `DeltaDiscoveryRequest`/`DeltaDiscoveryResponse` for Delta xDS) and are fundamentally incompatible. Mixing them will lead to failures.","severity":"gotcha","affected_versions":"All versions supporting both SotW and Delta xDS"},{"fix":"Regularly update `xds-protos` to align with the control plane's deployed xDS API version. Implement robust error handling for resource rejections and consider logging validation discrepancies for debugging.","message":"Protoc-Gen-Validate (PGV) annotations on xDS protos can evolve, making validation rules less strict over time without being considered a breaking API change. This can lead to situations where a control plane expects stricter validation than a client built with older protos, or vice-versa, causing resource rejection mismatches.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the `protobuf` runtime package version is compatible with the `protoc` version used to generate `xds-protos`. If encountering issues, try upgrading `protobuf` (e.g., `pip install --upgrade protobuf`).","message":"This package consists of generated Python protobuf code. It has a runtime dependency on the `protobuf` Python package. Incompatibilities can arise if the `xds-protos` package is generated with a `protoc` version that is significantly newer or older than the `protobuf` runtime library installed in the environment.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}