{"id":13750488,"url":"https://github.com/miekg/xds","last_synced_at":"2025-05-09T15:32:03.297Z","repository":{"id":141730547,"uuid":"234752757","full_name":"miekg/xds","owner":"miekg","description":"command line interface for Envoy xDS endpoint","archived":true,"fork":false,"pushed_at":"2020-07-27T13:44:17.000Z","size":15638,"stargazers_count":35,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-16T02:33:01.247Z","etag":null,"topics":["coredns","envoy","load-balancing","xds"],"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/miekg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-18T15:11:37.000Z","updated_at":"2023-11-18T11:54:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"5eaf820e-fdb6-4652-a53a-f2b625be2796","html_url":"https://github.com/miekg/xds","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miekg%2Fxds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miekg%2Fxds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miekg%2Fxds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miekg%2Fxds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miekg","download_url":"https://codeload.github.com/miekg/xds/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253275619,"owners_count":21882340,"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","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":["coredns","envoy","load-balancing","xds"],"created_at":"2024-08-03T08:00:36.674Z","updated_at":"2025-05-09T15:32:02.958Z","avatar_url":"https://github.com/miekg.png","language":"Go","funding_links":[],"categories":["Documentation"],"sub_categories":[],"readme":"# xds\n\nxDS is Envoy's discovery protocol. This repo contains xDS related utilities - included are:\n\n *  xds - management daemon that caches endpoints and clusters and hands them out using xDS and ADS.\n\n *  xdsctl - cli to manipulate and list details of endpoints and clusters.\n\nTLS is not implemented (yet). Note that this implements the v2 xDS API, Envoy works with this API\nas wel.\n\n\n`xdsctl` uses xDS to manipulate the cluster info stored. All other users that read\nfrom it must use ADS. Every 10 seconds `xds` will send out an update (if there are changes) to all\nconnected clients.\n\nTHIS IS A PROTOTYPE IMPLEMENTATION. It may get extended to actual production quality at some point.\n\n## Trying out\n\nBuild the server and clients:\n\n *  server: `go build`\n\n *  client: `cd cmd/xdsctl; go build`\n\n *  helloworld client and server: `cd helloworld/{client,server}; go build`\n\nStart the server with `xds` and then use the client to connect to it with `xdsctl -k -s\n127.0.0.1:18000 ls`. When starting up `xds` will read files `cluster.*.textpb` that contain clusters\nto use. This will continue during the runtime of the process; new clusters - if found - will be\nadded. Removal is not implemented.\n\nThe `envoy-bootstrap.yaml` can be used to point Envoy to the xds control plane - note this only\ngives envoy CDS/EDS responses (via ADS), so no listeners nor routes. Envoy can be downloaded from\n\u003chttps://tetrate.bintray.com/getenvoy/\u003e.\n\nCoreDNS (with the *traffic* plugin compiled in; see **traffic** branch in the coredns/coredns repo),\ncan be started with the Corefile specified to get DNS responses out of xds. CoreDNS can be found at\n\u003chttps://github.com/coredns/coredns\u003e\n\n## xds\n\n *  Adds clusters via a text protobuf on startup, after reading this in the version will be set to\n    v1 for those.\n\n *  When xds starts up, files adhering to this glob \"cluster.*.textpb\" will be parsed as\n    Cluster protocol buffer in text format. These define the set of clusters we know about.\n    Note: this is in effect the \"admin interface\", until we figure out how it should look. The\n    wildcard should match the name of cluster being defined in the protobuf.\n\n`cmd/xdsctl/xdsctl` is an CLI interface, it has extensive help built in.\n\nIn xds the following protocols have been implemented:\n\n* xDS - Envoy's configuration and discovery protocol (includes LDS, RDS, EDS and CDS).\n* LRS - load reporting.\n* HRS - health reporting.\n\nFor debugging add:\n\n~~~ sh\nexport RPC_GO_LOG_VERBOSITY_LEVEL=99\nexport GRPC_GO_LOG_SEVERITY_LEVEL=info\n~~~\n\nFor helping the xDS (gRPC) clients bootstrap set: `export GRPC_XDS_BOOTSTRAP=./boostrap.json`\n\n## Usage\n\nStart the management server, the servers and then the client:\n\n~~~\n% ./xds -debug\n~~~\n\nServers (these match the endpoints as defined in the `cluster.hellowold.textpb` file.\n\n~~~\n% ./helloworld/server/server -addr 127.0.1.1:50051 \u0026\n% ./helloworld/server/server -addr 127.0.0.1:50051 \u0026\n~~~\n\nAnd then query:\n\n~~~\n% ./helloworld/client/client -addr xds:///helloworld\n~~~\n\nNote you can specify a DNS server to use, but then the client will *also* do DNS looks up and you\nget a weird mix of grpclb and xDS behavior:\n\n~~~\n% ./helloworld/client/client -addr dns://127.0.0.1:1053/helloworld.lb.example.org:50501\n~~~\n\nGetting info out of the xds management server is done with xdsctl:\n\n~~~\n% ./cmd/xdsctl/xdsctl -s 127.0.0.1:18000 -k ls\nCLUSTER      VERSION   HEALTHCHECKS\nhelloworld   2         HTTP\nxds          2         TCP\n\n% ./cmd/xdsctl/xdsctl -s 127.0.0.1:18000 -k ls helloworld\nCLUSTER      ENDPOINT                          LOCALITY   HEALTH            WEIGHT/RATIO   LOAD/RATIO\nhelloworld   127.0.0.1:50051                   us         HEALTHY           2/0.33         18/0.46\nhelloworld   127.0.1.1:50051,127.0.2.1:50051   eu         HEALTHY,HEALTHY   4/0.67         21/0.54\n~~~\n\nWEIGHT are the weights as assigned to the clusters, RATIO is the relative weight for each endpoint\nin the cluster. LOAD shows the load if reported back to the management cluster. The load RATIO\nshould trail towards the weight RATIO if everything works well.\n\n## Load Reporting\n\nLoad reporting is supported via LRS. However to save the reporting load back into the cluster, we\nuse the metadata field of of the `*xdspb2.Cluster` where we store this value. This allows\n`xdscli` to extract it from the management server without adding new bits to the proto. This is\nnon-standard, but as this is internal to `xds` it should not matter much.\n\nLoad is report per *locality*, as - as per gRPC - only `total_successful_requests` is used. Load\nreports are recieved every 2 seconds.\n\n## Changing Cluster Weights\n\nChanging weights of clusters is implemented as a hack on top of the load reporting. This is\nimplemented by the metadata in the load reporting protobuf (`UpstreamEndpointStats.Metadata`).\n\n## TODO\n\n* version per cluster; right now the version if global; if any cluster changes, the version is\n  upped globaly.\n* canceling watches and a lot more of this stuff\n* tests!\n\n## Stuff Learned\n\n* gRPC must see `load_balancing_weight`, otherwise it will silently drop the endpoints\n* gRPC must have endpoints in different localities otherwise it will only use one? Need to check the\n  algo in grpc source code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiekg%2Fxds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiekg%2Fxds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiekg%2Fxds/lists"}