{"id":13453210,"url":"https://github.com/skynetservices/skydns1","last_synced_at":"2025-03-24T01:31:14.585Z","repository":{"id":11098758,"uuid":"13450948","full_name":"skynetservices/skydns1","owner":"skynetservices","description":"DNS for skynet or any other service discovery","archived":false,"fork":false,"pushed_at":"2017-07-08T06:19:14.000Z","size":1569,"stargazers_count":528,"open_issues_count":5,"forks_count":54,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-11-14T09:34:45.691Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skynetservices.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}},"created_at":"2013-10-09T18:51:04.000Z","updated_at":"2024-05-29T16:33:51.000Z","dependencies_parsed_at":"2022-09-23T18:01:04.418Z","dependency_job_id":null,"html_url":"https://github.com/skynetservices/skydns1","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/skynetservices%2Fskydns1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetservices%2Fskydns1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetservices%2Fskydns1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skynetservices%2Fskydns1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skynetservices","download_url":"https://codeload.github.com/skynetservices/skydns1/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245194204,"owners_count":20575724,"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":[],"created_at":"2024-07-31T08:00:34.822Z","updated_at":"2025-03-24T01:31:14.102Z","avatar_url":"https://github.com/skynetservices.png","language":"Go","funding_links":[],"categories":["Go","Service Discovery \u0026 Registry"],"sub_categories":[],"readme":"#SkyDNS2\n\nThis is an heads up that this version of SkyDNS is going to be replaced by\n[SkyDNS2](https://github.com/skynetservices/skydns) which is backed by etcd.\n\n*This* version will then be available under \u003chttp://github.com/skynetservices/skydns1\u003e.\n\nThings are different in version 2, so please try it and report back any problems, success\nstories or whatever. You can report issues here or in the skydns2 repository.\n\nWe expect this change to take place somewhere mid May 2014, unless issues pop up.\n\n#SkyDNS [![Build Status](https://travis-ci.org/skynetservices/skydns1.png)](https://travis-ci.org/skynetservices/skydns1)\n*Version 0.2.0*\n\nSkyDNS is a distributed service for announcement and discovery of services. It\nleverages Raft for high-availability and consensus, and utilizes DNS queries\nto discover available services. This is done by leveraging SRV records in DNS,\nwith special meaning given to subdomains, priorities and weights.\n\nSkyDNS will also act as a forwarding DNS proxy, so that you can set your SkyDNS\ninstance as the primary DNS service in /etc/resolv.conf and SkyDNS will forward\nand proxy requests for which it is not authoritative.\n\nBesides serving SRV records, which include *all* the information you need to\nconnect to your service, SkyDNS will also return A records. This is useful if\nyou already know what port a particular service is using, and you just want a\nlist of IP addresses with known running instances.\n\n[Announcement Blog Post](http://blog.gopheracademy.com/skydns)\n\n##Setup / Install\n\nCompile SkyDNS, and execute it\n\n`go get -d -v ./... \u0026\u0026 go build -v ./...`\n\n`./skydns`\n\nWhich takes the following flags\n- -domain - This is the domain requests are anchored to and should be appended to all requests (Defaults to: skydns.local)\n- -http - This is the HTTP ip:port to listen on for API request (Defaults to: 127.0.0.1:8080)\n- -dns - This is the ip:port to listen on for DNS requests (Defaults to: 127.0.0.1:53)\n- -data - Directory that Raft logs will be stored in (Defaults to: ./data)\n- -join - When running a cluster of SkyDNS servers as recommended, you'll need to supply followers with where the other members can be found, this can be any member or a comma separated list of members. It does not have to be the leader. Any non-leader you join will redirect you to the leader automatically.\n- -discover - This flag can be used in place of explicitly supplying cluster members via the -join flag. It performs a DNS lookup using the hosts DNS server for NS records associated with the -domain flag to find the SkyDNS instances.\n- -metricsToStdErr - When this flag is set to true, metrics will be periodically written to standard error\n- -graphiteServer - When this flag is set to a Graphite Server URL:PORT, metrics will be posted to a graphite server\n- -stathatUser - When this flag is set to a valid StatHat user, metrics will be posted to that user's StatHat account periodically\n- -secret - When this variable is set, the HTTP api will require an authorization header that matches the secret passed to skydns when it starts\n- -nameserver - Nameserver address to forward (non-local) queries to e.g. \"8.8.8.8:53,8.8.4.4:53\", in other words an IP:PORT, where multiple nameservers maybe listed separated by a comma \"`,`\". If this list is empty (\"\"),\nSkyDNS will parse /etc/resolv.conf and will use the nameservers listed there.\n- -tlskey - The path to the secret key to unlock your ssl cert.\n- -tlspem - The path to the X509 certificate that will secure skydns.\n\n##API\n### Service Announcements\nYou announce your service by submitting JSON over HTTP to SkyDNS with information about your service.\nThis information will then be available for queries either via DNS or HTTP.\n\nWhen providing information you will need to fill out the following values. Note you are free to use\nwhatever you like, so take the following list as a guide only.\n\n* Name - The name of your service, e.g., \"rails\", \"web\" or anything else you like\n* Version - A version string, note the dots in this string are translated to hyphens when\n    querying via the DNS\n* Environment - Can be something as \"production\" or \"testing\"\n* Region - Where do these hosts live, e.g. \"east\", \"west\" or even \"test\"\n* Host, Port and TTL - Denote the actuals hosts and how long (TTL) this information is valid.\n\nWhen queried SkyDNS will return records containing these elements in the following\norder:\n\n    \u003cuuid\u003e.\u003chost\u003e.\u003cregion\u003e.\u003cversion\u003e.\u003cservice\u003e.\u003cenvironment\u003e.skydns.local\n\nWhere `\u003cuuid\u003e` is the identifier used when registering this host and service. And also\nnote the `\u003cservice\u003e` corresponds with the Name given above.\n\nNote some of these elements may contain a wildcard or be left out completely,\nsee the section named \"Wildcards\" below for more information.\n\n#### Without Shared Secret\n`curl -X PUT -L http://localhost:8080/skydns/services/1001 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"Test\",\"Host\":\"web1.site.com\",\"Port\":9000,\"TTL\":10}'`\n\n#### With Shared Secret\nYou have the ability to use a shared secret with SkyDns. To take advantage of the shared secret you would start skydns with the -secret=\u003csecretString\u003e flag.\n`curl -X PUT -H \"Authorization mysupersecretsharedsecret\" -L http://localhost:8080/skydns/services/1001 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"Test\",\"Host\":\"web1.site.com\",\"Port\":9000,\"TTL\":10}'`\n\nIf unsuccessful you should receive an HTTP status code of: **401 Unauthorized**\n\n#### Starting with TLS\nIf you supply the flags --tls-key and --tls-pem Skydns will assume your http interface should be tls. To start with tls  it should look something like this.\n\n```bash\ngo run main.go --tls-key=/path/to/secret.key --tls-pem=/path/to/cert.pem\n\n```\n\n#### Result\n\nIf successful you should receive an HTTP status code of: **201 Created**\n\nIf a service with this UUID already exists you will receive back an HTTP status\ncode of: **409 Conflict**\n\nSkyDNS will now have an entry for your service that will live for the number\nof seconds supplied in your TTL (10 seconds in our example), unless you send a\nheartbeat to update the TTL.\n\nNote that instead of a hostname you can also use an IP address (IPv4 or IPV6),\nin that case SkyDNS will make up an hostname that is used in the SRV record\n(defaults to UUID.skydns.local) and adds the IP adress as an A or AAAAA record\nin the additional section for this hostname.\n\n### Heartbeat / Keep alive\nSkyDNS requires that services submit an HTTP request to update their TTL within\nthe TTL they last supplied. If the service fails to do so within this timeframe\nSkyDNS will expire the service automatically. This will allow for nodes to fail\nand DNS to reflect this quickly.\n\nYou can update your TTL by sending an HTTP request to SkyDNS with an updated\nTTL, it can be the same as before to allow it to live for another 10s, or it can\nbe adjusted to a shorter or longer duration.\n\n`curl -X PATCH -L http://localhost:8080/skydns/services/1001 -d '{\"TTL\":10}'`\n\n### Service Removal\nIf you wish to remove your service from SkyDNS for any reason without waiting for the TTL to expire, you simply send an HTTP DELETE.\n\n`curl -X DELETE -L http://localhost:8080/skydns/services/1001`\n\n### Retrieve Service Info via API\nCurrently you may only retrieve a service's info by UUID of the service, in the\nfuture we may implement querying of the services similar to the DNS interface.\n\n`curl -X GET -L http://localhost:8080/skydns/services/1001`\n\n### Call backs\nRegistering a call back is similar to registering a service. A service that\nregisters a call back will receive an HTTP request. Every time something changes\nin the service: the callback is executed, currently they are called when the\nservice is deleted.\n\n`curl -X PUT -L http://localhost:8080/skydns/callbacks/1001 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"Test\",\"Host\":\"web1.site.com\",Reply:\"web2.example.nl\",\"Port\":5441}'`\n\nThis will result in the call back being sent to `web2.example.nl` on port 5441. The\ncallback itself will be a HTTP DELETE:\n\n`curl -X DELETE -L http://web2.example.nl:5441/skydns/callbacks/1001 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"Test\",\"Host\":\"web1.site.com\"}'`\n\n##Discovery (DNS)\nYou can find services by querying SkyDNS via any DNS client or utility. It uses a known domain syntax with wildcards to find matching services.\n\nPriorities and Weights are based on the requested Region, as well as how many nodes are available matching the current request in the given region.\n\n###Domain Format\nThe domain syntax when querying follows a pattern where the right\nmost positions are more generic, than the subdomains to their left:\n*\\\u003cuuid\\\u003e.\\\u003chost\\\u003e.\\\u003cregion\\\u003e.\\\u003cversion\\\u003e.\\\u003cservice\\\u003e.\\\u003cenvironment\\\u003e.skydns.local*.\nThis allows for you to supply only the positions you care about:\n\n- authservice.production.skydns.local - For instance would return all services with the name AuthService in the production environment, regardless of the Version, Region, or Host\n- 1-0-0.authservice.production.skydns.local - Is the same as above but restricting it to only version 1.0.0\n- east.1-0-0.authservice.production.skydns.local - Would add the restriction that the services must be running in the East region\n\n#### Wildcards\n\nIn addition to only needing to specify as much of the domain as required for the granularity level you're looking for, you may also supply the wildcard `*` in any of the positions.\n\n- east.*.*.production.skydns.local - Would return all services in the East region, that are a part of the production environment.\n\n###Examples\n\nLet's take a look at some results. First we need to add a few services so we have services to query against.\n\n\t// Service 1001 (East Region)\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1001 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"East\",\"Host\":\"web1.site.com\",\"Port\":80,\"TTL\":4000}'\n\n\t// Service 1002 (East Region)\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1002 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"East\",\"Host\":\"web2.site.com\",\"Port\":8080,\"TTL\":4000}'\n\n\t// Service 1003 (West Region)\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1003 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"West\",\"Host\":\"web3.site.com\",\"Port\":80,\"TTL\":4000}'\n\n\t// Service 1004 (West Region)\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1004 -d '{\"Name\":\"TestService\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"West\",\"Host\":\"web4.site.com\",\"Port\":80,\"TTL\":4000}'\n\nNow we can try some of our example DNS lookups:\n#####All services in the Production Environment\n`dig @localhost production.skydns.local SRV`\n\n\t;; QUESTION SECTION:\n\t;production.skydns.local.\t\t\tIN\tSRV\n\n\t;; ANSWER SECTION:\n\tproduction.skydns.local.\t\t629\t\tIN\tSRV\t10 20 80   web1.site.com.\n\tproduction.skydns.local.\t\t3979\tIN\tSRV\t10 20 8080 web2.site.com.\n\tproduction.skydns.local.\t\t3629\tIN\tSRV\t10 20 9000 server24.\n\tproduction.skydns.local.\t\t3985\tIN\tSRV\t10 20 80   web3.site.com.\n\tproduction.skydns.local.\t\t3990\tIN\tSRV\t10 20 80   web4.site.com.\n\n#####All TestService instances in Production Environment\n`dig @localhost testservice.production.skydns.local SRV`\n\n\t;; QUESTION SECTION:\n\t;testservice.production.skydns.local.\t\tIN\tSRV\n\n\t;; ANSWER SECTION:\n\ttestservice.production.skydns.local.\t615\t\tIN\tSRV\t10 20 80   web1.site.com.\n\ttestservice.production.skydns.local.\t3966\tIN\tSRV\t10 20 8080 web2.site.com.\n\ttestservice.production.skydns.local.\t3615\tIN\tSRV\t10 20 9000 server24.\n\ttestservice.production.skydns.local.\t3972\tIN\tSRV\t10 20 80   web3.site.com.\n\ttestservice.production.skydns.local.\t3976\tIN\tSRV\t10 20 80   web4.site.com.\n\n#####All TestService v1.0.0 Instances in Production Environment\n`dig @localhost 1-0-0.testservice.production.skydns.local SRV`\n\n\t;; QUESTION SECTION:\n\t;1-0-0.testservice.production.skydns.local.\tIN\tSRV\n\n\t;; ANSWER SECTION:\n\t1-0-0.testservice.production.skydns.local. 600  IN\tSRV\t10 20 80   web1.site.com.\n\t1-0-0.testservice.production.skydns.local. 3950 IN\tSRV\t10 20 8080 web2.site.com.\n\t1-0-0.testservice.production.skydns.local. 3600 IN\tSRV\t10 20 9000 server24.\n\t1-0-0.testservice.production.skydns.local. 3956 IN\tSRV\t10 20 80   web3.site.com.\n\t1-0-0.testservice.production.skydns.local. 3961 IN\tSRV\t10 20 80   web4.site.com.\n\n#####All TestService Instances at any version, within the East region\n`dig @localhost east.*.testservice.production.skydns.local SRV`\n\nThis is where we've changed things up a bit, notice we used the \"*\" wildcard for\nversion so we get any version, and because we've supplied an explicit region\nthat we're looking for we get that as the highest DNS priority, with the weight\nbeing distributed evenly, then all of our West instances still show up for\nfail-over, but with a higher Priority.\n\n\t;; QUESTION SECTION:\n\t;east.*.testservice.production.skydns.local. IN\tSRV\n\n\t;; ANSWER SECTION:\n\teast.*.testservice.production.skydns.local. 531  IN SRV\t10 50 80   web1.site.com.\n\teast.*.testservice.production.skydns.local. 3881 IN SRV\t10 50 8080 web2.site.com.\n\teast.*.testservice.production.skydns.local. 3531 IN SRV\t20 33 9000 server24.\n\teast.*.testservice.production.skydns.local. 3887 IN SRV\t20 33 80   web3.site.com.\n\teast.*.testservice.production.skydns.local. 3892 IN SRV\t20 33 80   web4.site.com.\n\n\n####A Records\nTo return A records, simply run a normal DNS query for a service matching the above patterns.\n\nLet's add some web servers to SkyDNS:\n\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1011 -d '{\"Name\":\"rails\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"East\",\"Host\":\"127.0.0.10\",\"Port\":80,\"TTL\":400000}'\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1012 -d '{\"Name\":\"rails\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"East\",\"Host\":\"127.0.0.11\",\"Port\":80,\"TTL\":400000}'\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1013 -d '{\"Name\":\"rails\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"West\",\"Host\":\"127.0.0.12\",\"Port\":80,\"TTL\":400000}'\n\tcurl -X PUT -L http://localhost:8080/skydns/services/1014 -d '{\"Name\":\"rails\",\"Version\":\"1.0.0\",\"Environment\":\"Production\",\"Region\":\"West\",\"Host\":\"127.0.0.13\",\"Port\":80,\"TTL\":400000}'\n\nNow do a normal DNS query:\n`dig rails.production.skydns.local`\n\n\t;; QUESTION SECTION:\n\t;rails.production.skydns.local.\tIN\tA\n\n\t;; ANSWER SECTION:\n\trails.production.skydns.local. 399918 IN A\t127.0.0.10\n\trails.production.skydns.local. 399918 IN A\t127.0.0.11\n\trails.production.skydns.local. 399918 IN A\t127.0.0.12\n\trails.production.skydns.local. 399919 IN A\t127.0.0.13\n\nNow you have a list of all known IP Addresses registered running the `rails`\nservice name. Because we're returning A records and not SRV records, there\nare no ports listed, so this is only useful when you're querying for services\nrunning on ports known to you in advance. Notice, we didn't specify version or\nregion, but we could have.\n\n####DNS Forwarding\n\nBy specifying `-nameserver=\"8.8.8.8:53,8.8.4.4:53` on the `skydns` command line,\nyou create a DNS forwarding proxy. In this case it round robins between the two\nnameserver IPs mentioned on the command line.\n\nRequests for which SkyDNS isn't authoritative\nwill be forwarded and proxied back to the client. This means that you can set\nSkyDNS as the primary DNS server in `/etc/resolv.conf` and use it for both service\ndiscovery and normal DNS operations.\n\n*Please test this before relying on it in production, as there may be edge cases that don't work as planned.*\n\n####DNSSEC\n\nSkyDNS support signing DNS answers (also know as DNSSEC). To use it you need to\ncreate a DNSSEC keypair and use that in SkyDNS. For instance if the domain for\nSkyDNS is `skydns.local`:\n\n    dnssec-keygen skydns.local\n    Generating key pair............++++++ ...................................++++++\n    Kskydns.local.+005+49860\n\nThis creates two files both with the basename `Kskydns.local.+005.49860`, one of the\nextension `.key` (this holds the public key) and one with the extension `.private` which\nhold the private key. The basename of this file should be given to SkyDNS's -dnssec\noption: `-dnssec=Kskydns.local.+005+49860`\n\nIf you then query with `dig +dnssec` you will get signatures, keys and nsec records returned.\n\n## License\nThe MIT License (MIT)\n\nCopyright © 2014 The SkyDNS Authors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskynetservices%2Fskydns1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskynetservices%2Fskydns1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskynetservices%2Fskydns1/lists"}