feat: add and fix orion-xds examples

[hanshal101]

Fixes #8
Closes #8

Description

This PR adds the README.md file which contains a detailed information about how to run and test the orion-xds examples.

[kmesh-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[gemini-code-assist]

Summary of Changes

Hello @hanshal101, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've added a comprehensive README.md file to the orion-xds/examples directory. This new documentation aims to significantly improve the user experience by providing detailed instructions on how to set up, run, and test the various orion-xds examples, which demonstrate the library's service discovery and configuration capabilities using a gRPC and async Rust client-server model.

Highlights

• Enhanced Documentation: Introduced a new README.md file within orion-xds/examples to provide a complete guide for running and testing the examples.
• Setup Instructions: Included clear prerequisites for the Rust environment and steps to build dependencies.
• Client-Server Walkthrough: Detailed instructions for running the primary XDS server and client examples, explaining their respective functionalities in resource management and subscription.
• Known Client Limitation: Documented a current issue where the client fails to decode Listener configurations due to an unsupported field, along with sample logs and an explanation of its impact.
• Specialized Example Guide: Provided an overview and purpose for server_routes_and_loads.rs, highlighting its use cases for dynamic configuration updates, routing logic, and endpoint management.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive README.md for the orion-xds examples, which is a great addition for new users. The guide clearly explains how to set up the environment and run the client/server examples. I've provided a few minor suggestions to improve clarity and formatting in the documentation.

[hanshal101]

Hey @YaoZengzeng I was working on running these examples, where the client.rs, server.rs and server_routes_and_loads.rs worked perfectly fine. The main problem comes with the server_secret_rotation.rs. I see a problem here these are the logs from the server_secret_rotation.rs:

2025-08-07T11:07:16.653840Z  INFO server_secret_rotation: Server started
2025-08-07T11:07:16.653937Z  INFO orion_xds::xds::server: Server started 127.0.0.1:50051
2025-08-07T11:07:22.467277Z  INFO orion_xds::xds::server: AggregateServer::delta_aggregated_resources
2025-08-07T11:07:22.467319Z  INFO orion_xds::xds::server: 	client connected from: Some(127.0.0.1:32976)
2025-08-07T11:07:22.467578Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.467612Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.467620Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.cluster.v3.Cluster", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.467627Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.route.v3.RouteConfiguration", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.467634Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.listener.v3.Listener", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:26.654522Z  INFO server_secret_rotation: Adding downstream secret listener_beefcake_ca
2025-08-07T11:07:26.655487Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: None, type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "44906b0f-7a11-4bf1-9ec4-cac85e8beae8", error_detail: None }
2025-08-07T11:07:41.655389Z  INFO server_secret_rotation: Adding upstream secret beefcake_ca
2025-08-07T11:07:41.656169Z  INFO orion_xds::xds::server: Sever : Got item DeltaDiscoveryRequest { node: None, type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "df14e27a-01ec-4c15-8f3f-caf120597a79", error_detail: None }
2025-08-07T11:07:56.656354Z  INFO orion_xds::xds::server: 	client disconnected
2025-08-07T11:07:56.657304Z  INFO orion_xds::xds::server: Sever side closed
2025-08-07T11:08:00.659138Z  INFO orion_xds::xds::server: AggregateServer::delta_aggregated_resources
2025-08-07T11:08:00.659191Z  INFO orion_xds::xds::server: 	client connected from: Some(127.0.0.1:32976)

And these are the logs from client.rs

2025-08-07T11:07:22.465612Z  INFO orion_xds: Starting xDS client: http://127.0.0.1:50051/
2025-08-07T11:07:22.466437Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.466528Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.466561Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.cluster.v3.Cluster", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.466582Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.route.v3.RouteConfiguration", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.466603Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.listener.v3.Listener", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:07:22.467851Z  INFO orion_xds::xds::client: xDS stream established
2025-08-07T11:07:26.655007Z  INFO orion_xds::xds::client: received config resources from xDS type_url="type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret" size=1
2025-08-07T11:07:26.655261Z  INFO orion_xds::xds::client: sending subsequent discovery request DeltaDiscoveryRequest { node: None, type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "44906b0f-7a11-4bf1-9ec4-cac85e8beae8", error_detail: None }
2025-08-07T11:07:41.655859Z  INFO orion_xds::xds::client: received config resources from xDS type_url="type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret" size=1
2025-08-07T11:07:41.656012Z  INFO orion_xds::xds::client: sending subsequent discovery request DeltaDiscoveryRequest { node: None, type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "df14e27a-01ec-4c15-8f3f-caf120597a79", error_detail: None }
2025-08-07T11:07:56.656968Z  WARN orion_xds::xds::client: xDS client error: UnknownResourceType("empty payload received"), retrying in 4s
2025-08-07T11:07:56.657033Z  WARN orion_xds::xds::client: outbound discovery request stream has ended!
2025-08-07T11:08:00.658215Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {"beefcake_ca": "", "listener_beefcake_ca": ""}, response_nonce: "", error_detail: None }
2025-08-07T11:08:00.658284Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:08:00.658306Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.cluster.v3.Cluster", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:08:00.658325Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.route.v3.RouteConfiguration", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:08:00.658344Z  INFO orion_xds::xds::client: sending initial discovery request DeltaDiscoveryRequest { node: Some(Node { id: "node1", cluster: "", metadata: None, dynamic_parameters: {}, locality: None, user_agent_name: "", extensions: [], client_features: [], listening_addresses: [], user_agent_version_type: None }), type_url: "type.googleapis.com/envoy.config.listener.v3.Listener", resource_names_subscribe: [], resource_names_unsubscribe: [], resource_locators_subscribe: [], resource_locators_unsubscribe: [], initial_resource_versions: {}, response_nonce: "", error_detail: None }
2025-08-07T11:08:00.660061Z  WARN orion_xds::xds::client: xDS client error: "gRPC error (Internal error): Delta stream is unavailable"
2025-08-07T11:08:00.660086Z  WARN orion_xds::xds::client: xDS client interupted: gRPC error (Internal error): Delta stream is unavailable, retrying in 8s

Problem

What I identified is that the current implementation only allows one client to connect to Delta xDS, as delta_resources_rx is a tokio::sync::mpsc::Receiver and it’s wrapped in AtomicTake, which consumes it on the first use. Where any second connection will see .take() return None.
What's your take on this? My plan was to add the need for multi-consumer support using tokio::sync::broadcast::channel

I am a bit confused with this decision, let me know your thoughts on this!

[dawid-nowak]

@hanshal101 , these examples are only there for a demo PoC purposes... not for the production so feel free to make changes to make them work.

Not sure what the long term objective is but I see couple of options going forward.

1. Use go envoy control plane for running examples.
2. Implement a bespoke control plane in Rust ... which is sort of work in progress at the moment with other project Kubernor
3. Start figuring our how to use Orion with Istio.. I think that would be the most interesting from KMesh perspective?

Whichever way we go, we need to push some more changes and bug fixes... which hopefully arrive early next week and which should address some problems with running Orion in containerized environments.

[YaoZengzeng]

Not sure what the long term objective is but I see couple of options going forward.

1. Use go envoy control plane for running examples.
2. Implement a bespoke control plane in Rust ... which is sort of work in progress at the moment with other project Kubernor
3. Start figuring our how to use Orion with Istio.. I think that would be the most interesting from KMesh perspective?

Thanks for your advice @dawid-nowak :)

Actually these issues are the way to select best mantee for this LFX project, ref: kmesh-net/kmesh#1450

I hope we could find one that has background of rust, k8s and istio or the capability to learn new skills fast.

It would be great if you can submit more such issues (Not too complicated or difficult, but good for screening) 😄

[hanshal101]

Not sure what the long term objective is but I see couple of options going forward.

1. Use go envoy control plane for running examples.
2. Implement a bespoke control plane in Rust ... which is sort of work in progress at the moment with other project Kubernor
3. Start figuring our how to use Orion with Istio.. I think that would be the most interesting from KMesh perspective?

Thanks for your advice @dawid-nowak :)

Actually these issues are the way to select best mantee for this LFX project, ref: kmesh-net/kmesh#1450

I hope we could find one that has background of rust, k8s and istio or the capability to learn new skills fast.

It would be great if you can submit more such issues (Not too complicated or difficult, but good for screening) 😄

Yeah, I know finding such candidates with these skills might help the development of orion pretty smoothly. Also i have been working with Rust for quite some time, working on building a lot of eBPF Programs. Also worked as a Kubernetes Engineer in my previous company handling most of the production grade k8s cluster. Also have a strong hand on Golang too.