{"id":13750496,"url":"https://github.com/envoyproxy/xds-relay","last_synced_at":"2025-08-20T08:10:08.581Z","repository":{"id":42614943,"uuid":"241474847","full_name":"envoyproxy/xds-relay","owner":"envoyproxy","description":"Caching, aggregation, and relaying for xDS compliant clients and origin servers","archived":false,"fork":false,"pushed_at":"2022-12-17T01:43:07.000Z","size":2619,"stargazers_count":134,"open_issues_count":35,"forks_count":29,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-08-15T15:59:38.182Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/envoyproxy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-18T21:49:23.000Z","updated_at":"2025-06-30T08:50:54.000Z","dependencies_parsed_at":"2022-09-26T20:02:12.714Z","dependency_job_id":null,"html_url":"https://github.com/envoyproxy/xds-relay","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/envoyproxy/xds-relay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoyproxy%2Fxds-relay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoyproxy%2Fxds-relay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoyproxy%2Fxds-relay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoyproxy%2Fxds-relay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/envoyproxy","download_url":"https://codeload.github.com/envoyproxy/xds-relay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoyproxy%2Fxds-relay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271285506,"owners_count":24732923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T08:00:36.766Z","updated_at":"2025-08-20T08:10:08.554Z","avatar_url":"https://github.com/envoyproxy.png","language":"Go","funding_links":[],"categories":["Documentation"],"sub_categories":[],"readme":"# xds-relay\nCaching, aggregation, and relaying for xDS compliant clients and origin servers\n\n## Contact\n\n* [Slack](https://envoyproxy.slack.com/): Slack, to get invited go [here](https://envoyslack.cncf.io).\n  Please join the `#xds-relay` channel for communication regarding this project.\n\n## Contributing\n\nTo get started:\n\n* [Contributing guide](CONTRIBUTING.md)\n\n## Example\n\nIn this example we're going to run an instance of a management server that emits xDS data every 10 seconds which will be relayed by an instance of `xds-relay` to 2 instances of envoy.\n\nThe goal of this example is to have the envoy instances mapped to the same key in `xds-relay`, namely the cache key `staging_cds`.\n\n### Requirements\n\n- envoy present in the PATH (Go to https://www.getenvoy.io/ and follow the guide on how to install an envoy version)\n- [jq](https://stedolan.github.io/jq/)\n- [curl](https://curl.haxx.se/)\n\n### Steps\n\n#### Management Server\nFirst build the example management server:\n\n    make build-example-management-server\n    \nThis will produce a binary called `example-management-server` under the `bin` directory. This binary runs a simple management server based on `go-control-plane` `SnapshotCache`. It produces a batch of xDS data with a random version every 10 seconds.\n\nOpen a window on your terminal and simply run:\n\n    ./bin/example-management-server\n\n#### xds-relay instance\nNext step is to configure the `xds-relay` server. For that we need to provide 2 files: \n  - an aggregation rules file\n  - a bootstrap file\n  \nYou'll find one example of each file in the `example/config-files` directory, `aggregation-rules.yaml` and `xds-relay-bootstrap.yaml` respectively.\n\nYou're now ready to run `xds-relay` locally. Open another window in your terminal and run:\n\n    ./bin/xds-relay -a example/config-files/aggregation-rules.yaml -c example/config-files/xds-relay-bootstrap.yaml -m serve\n\n#### Two envoy instances\nAs a final step, it's time to connect 2 envoy clients to `xds-relay`. If you do not have envoy installed, you can use [getenvoy](https://www.getenvoy.io/install/envoy/) to install the binary for your OS. You're going to find 2 files named `envoy-bootstrap-1.yaml` and `envoy-bootstrap-2.yaml` that we're going to use to connect the envoy instances to `xds-relay`. Open 2 terminal windows and run:\n\n    envoy --base-id 0 -c example/config-files/envoy-bootstrap-1.yaml # on the first window\n    envoy --base-id 1 -c example/config-files/envoy-bootstrap-2.yaml # on the second window\n\nAnd voilà! You should be seeing logs flowing in both the terminal window where you're running `xds-relay` and on each of the envoy ones. \n\n### How to validate that `xds-relay` is working?\n\nWe expose the contents of the cache in `xds-relay` via an endpoint, so we can use that to verify what are the contents of the cache for the keys being requested by the two envoy clients:\n\n    curl -s 0:6070/cache/staging_cds | jq '(.Cache[0].Resp.Resources.Clusters | map({\"name\": .name})) as $resp_clusters | (.Cache[0].Requests | map({\"version_info\": .version_info, \"node.id\": .node.id, \"node.cluster\": .node.cluster})) as $reqs | {\"response\": {\"version\": .Cache[0].Resp.VersionInfo, \"clusters\": $resp_clusters}, \"requests\": $reqs}'\n\nSample result:\n\n``` shellsession\n❯ curl -s 0:6070/cache/staging_cds | jq '(.Cache[0].Resp.Resources.Clusters | map({\"name\": .name})) as $resp_clusters | (.Cache[0].Requests | map({\"version_info\": .version_info, \"node.id\": .node.id, \"node.cluster\": .node.cluster})) as $reqs | {\"response\": {\"version\": .Cache[0].Resp.VersionInfo, \"clusters\": $resp_clusters}, \"requests\": $reqs}'\n{\n  \"response\": {\n    \"version\": \"v66936\",\n    \"clusters\": [\n      {\n        \"name\": \"cluster-v66936-0\"\n      },\n      {\n        \"name\": \"cluster-v66936-1\"\n      },\n      {\n        \"name\": \"cluster-v66936-2\"\n      }\n    ],\n    \"requests\": [\n      {\n        \"version_info\": \"v66936\",\n        \"node.id\": \"envoy-client-1\",\n        \"node.cluster\": \"staging\"\n      },\n      {\n        \"version_info\": \"v66936\",\n        \"node.id\": \"envoy-client-2\",\n        \"node.cluster\": \"staging\"\n      }\n    ]\n  }\n}\n```\n\nEnvoy also exposes an endpoint that lets us investigate what's the current state of the configuration data. If we focus solely on the dynamic cluster information being relayed by `xds-relay`, we can use curl to inspect the envoys by running: \n\n    curl -s 0:19000/config_dump | jq '.configs | (.[1].dynamic_active_clusters | map({\"version\": .version_info, \"cluster\": .cluster.name})) as $clusters | {\"clusters\": $clusters}'\n\nSample result:\n\n``` shellsession\n❯ curl -s 0:19000/config_dump | jq '.configs | (.[1].dynamic_active_clusters | map({\"version\": .version_info, \"cluster\": .cluster.name})) as $clusters | {\"clusters\": $clusters}'\n{\n  \"clusters\": [\n    {\n      \"version\": \"v56870\",\n      \"cluster\": \"cluster-v56870-0\"\n    },\n    {\n      \"version\": \"v56870\",\n      \"cluster\": \"cluster-v56870-1\"\n    },\n    {\n      \"version\": \"v56870\",\n      \"cluster\": \"cluster-v56870-2\"\n    }\n  ]\n}\n```\n\nThis is a gif of a tmux session demonstrating this example:\n\n![demo](example/xds-relay-demo.gif)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvoyproxy%2Fxds-relay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenvoyproxy%2Fxds-relay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvoyproxy%2Fxds-relay/lists"}