xds-protos

1.80.0 · active · verified Mon Apr 13

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
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`).

Install

pip install xds-protos Install latest version

Imports

DiscoveryRequest
```
from envoy.service.discovery.v3 import discovery_pb2
```
Common xDS messages are typically found under `envoy.<config|service>.<category>.v3` subpackages.

Cluster

from envoy.config.cluster.v3 import cluster_pb2

TypedStruct
```
from xds.type.v3 import typed_struct_pb2
```
Older versions of some xDS types (like TypedStruct) were under the `udpa` package and have since moved to `xds` as part of API generalization.

Quickstart

Demonstrates importing a core xDS message (`DiscoveryRequest`) and instantiating it. This package provides the generated message classes for use in xDS clients or servers.

from envoy.service.discovery.v3 import discovery_pb2

# Create a simple DiscoveryRequest message
request = discovery_pb2.DiscoveryRequest(
    version_info='1.0.0',
    node=None, # In a real scenario, this would be a Node message
    resource_names=['my-cluster'],
    type_url='type.googleapis.com/envoy.config.cluster.v3.Cluster',
    response_nonce='some-nonce'
)

print(f"Created DiscoveryRequest: {request}")

# Accessing fields
print(f"Requested resource names: {request.resource_names}")

view raw JSON →