{"id":37202142,"url":"https://github.com/tiglabs/containerdns","last_synced_at":"2026-01-14T23:18:43.506Z","repository":{"id":41086416,"uuid":"89581682","full_name":"tiglabs/containerdns","owner":"tiglabs","description":"a fast DNS for Kubernetes clusters","archived":false,"fork":false,"pushed_at":"2019-10-26T09:48:16.000Z","size":31724,"stargazers_count":341,"open_issues_count":0,"forks_count":123,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-08-15T00:38:32.020Z","etag":null,"topics":["dns","docker","dpdk","etcd","jdos","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"C","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/tiglabs.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":"2017-04-27T09:41:30.000Z","updated_at":"2025-08-04T12:57:54.000Z","dependencies_parsed_at":"2022-09-08T05:11:53.732Z","dependency_job_id":null,"html_url":"https://github.com/tiglabs/containerdns","commit_stats":null,"previous_names":["ipdcode/skydns"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tiglabs/containerdns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiglabs%2Fcontainerdns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiglabs%2Fcontainerdns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiglabs%2Fcontainerdns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiglabs%2Fcontainerdns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiglabs","download_url":"https://codeload.github.com/tiglabs/containerdns/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiglabs%2Fcontainerdns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28437967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T22:37:52.437Z","status":"ssl_error","status_checked_at":"2026-01-14T22:37:31.496Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["dns","docker","dpdk","etcd","jdos","kubernetes"],"created_at":"2026-01-14T23:18:42.801Z","updated_at":"2026-01-14T23:18:43.476Z","avatar_url":"https://github.com/tiglabs.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ContainerDNS\n\n## Introduction\nContainerDNS works as an internal DNS server for a Kubernetes cluster. \n\n\n## Components\n* `containerdns`: the main service to offer DNS query.\n* `containerdns-kubeapi`: monitor the changes of k8s services, and record the change in the etcd. It offered the\n   original data for containerdns, meanwhille containerdns-kubeapi offers the RESTful api for users to maintain domain records.\n* `containerdns-apicmd`: it is a shell cmd for user to query\\update domain record, it is based on containerdns-kubeapi.\n* `etcd`: used to store DNS information, etcd v3 api is used.\n\nIt is based on the DNS library https://github.com/miekg/dns. \n\n\n## Feature:\n* fully-cached DNS records\n* backend ip automatic removed when it not avaliable\n* support multiple domain suffix \n* better performance and less jitter\n* load balancing - when a domain has multiple IPs, ContainerDNS chooses an active one randoml\n* session persistence - when a domain name is accessed multiple times from the same source, the same service IP is returned.\n\n## Design Architecture\n  ![image](https://github.com/tiglabs/containerdns/blob/master/images/ContainerDNS_design_architecture.png)\n\n## Setup / Install\n\nThen get and compile ContainerDNS:\n\n```shell\n    mkdir -p $GOPATH/src/github.com/tiglabs\n    cd $GOPATH/src/github.com/tiglabs\n    git clone https://github.com/tiglabs/containerdns\n    cd $GOPATH/src/github.com/tiglabs/containerdns\n    make\n```\n\n## Configuration\n\n### containerdns\n* `config-file`: read configs from the file, default \"/etc/containerdns/containerdns.conf\".\n\nthe config file like this:\n\n```shell\n    [Dns]\n    dns-domain = containerdns.local.\n    dns-addr   = 0.0.0.0:53\n    nameservers = \"\"\n    subDomainServers = \"\"\n    cacheSize   = 100000\n    ip-monitor-path = /containerdns/monitor/status/\n    \n    [Log]\n    log-dir    = /export/log/containerdns\n    log-level  = 2\n    log-to-stdio = true\n    \n    [Etcd]\n    etcd-servers = http://127.0.0.1:2379\n    etcd-certfile = \"\"\n    etcd-keyfile = \"\"\n    etcd-cafile = \"\"\n    \n    [Fun]\n    random-one = false\n    hone-one  = false\n    \n    [Stats]\n    \n    statsServer = 127.0.0.1:9600\n    statsServerAuthToken = @containerdns.com\n```\n\n### containerdns-kubeapi\n* `config-file`: read configs from the file, default \"/etc/containerdns/containerdns.conf\".\n\nthe config file like this:\n\n```shell\n    [General]\n    domain=containerdns.local\n    host = 192.168.169.41\n    etcd-server = http://127.0.0.1:2379\n    ip-monitor-path = /containerdns/monitor/status\n    log-dir    = /export/log/containerdns\n    log-level  = 2\n    log-to-stdio = false\n    \n    [Kube2DNS]\n    kube-enable = NO\n    \n    [DNSApi]\n    api-enable = YES\n    api-address = 127.0.0.1:9003\n    containerdns-auth  = 123456789\n    \n```\n\n### containerdns-scanner\n\n* `config-file`: read configs from the file, default \"/etc/containerdns/containerdns-scanner.conf\".\n\nthe config file like this:\n\n```shell\n    [General]\n    core = 0\n    enable-check = true\n    hostname = hostname1\n    log-dir = /export/log/containerdns\n    log-level = 100\n    heartbeat-interval = 30\n    [Check]\n    check-timeout = 2\n    check-interval = 10\n    scann-ports = 22, 80, 8080\n    enable-icmp = true\n    ping-timeout = 1000\n    ping-count = 2\n    [Etcd]\n    etcd-machine = http://127.0.0.1:2379\n    tls-key =\n    tls-pem =\n    ca-cert =\n    status-path = /containerdns/monitor/status\n    report-path = /containerdns/monitor/report\n    heart-path = /containerdns/monitor/heart\n    \n```\n\n### containerdns-schedule\n\n* `config-file`: read configs from the file, default \"/etc/containerdns/containerdns-schedule.conf\".\n\nthe config file like this:\n\n```shell\n    [General]\n    schedule-interval = 60\n    agent-downtime = 60\n    log-dir = /export/log/containerdns\n    log-level = 100\n    hostname = hostname1\n    force-lock-time = 1800\n    \n    [Etcd]\n    etcd-machine = http://127.0.0.1:2379\n    status-path = /containerdns/monitor/status\n    report-path = /containerdns/monitor/report\n    heart-path = /containerdns/monitor/heart\n    lock-path = /containerdns/monitor/lock\n```\n\n## Testing\n\n### containerdns-kubeapi\n```\n    we use curl to test the user api.\n```\n####  typeA\n```shell\n    % curl -H \"Content-Type:application/json;charset=UTF-8\"  -X POST -d '{\"type\":\"A\",\"ips\":[\"192.168.10.1\",\"192.168.10.2\",\"192.168.10.3\"]}'  http://127.0.0.1:9001/containerdns/api/cctv2?token=\"123456789\"      \n    OK\n```\n#### typeCname\n```shell\n    % curl -H \"Content-Type:application/json;charset=UTF-8\"   -X POST -d '{\"type\":\"cname\",\"alias\":\"tv1\"}' http://127.0.0.1:9001/containerdns/api/cctv2.containerdns.local?token=\"123456789\"  \n   OK\n```\n\n### containerdns\n\n####  typeA\n```\n    % nslookup qiyf-nginx-5.default.svc.containerdns.local 127.0.0.1\n    Server:         127.0.0.1\n    Address:        127.0.0.1#53\n\n    Name:   qiyf-nginx-5.default.svc.containerdns.local\n    Address: 192.168.19.113\n\n    if the domain have more than one ip, containerdns will return a radom one.\n\n    % nslookup cctv2.containerdns.local 127.0.0.1\n    Server:         127.0.0.1\n    Address:        127.0.0.1#53\n\n    Name:   cctv2.containerdns.local\n    Address: 192.168.10.3\n\n```\n####  typeCname\n```\n    % nslookup tv1.containerdns.local 127.0.0.1\n    Server:         127.0.0.1\n    Address:        127.0.0.1#53\n\n    tv1.containerdns.local    canonical name = cctv2.containerdns.local.\n    Name:   cctv2.containerdns.local\n    Address: 192.168.10.3\n```\n####  monitor\n```\n     If the domain may have multiple ips, then dns-scanner is used to monitor the ips behand the domain. \n     When the service is not reachable, dns-scanner will change the status of the ip. And the containerdns will monitor the ip status, \n     when it comes down, containerdns will choose a good one.\n     \n     cctv2.containerdns.local    ips[192.168.10.1,192.168.10.2,192.168.10.3]\n     \n    % nslookup cctv2.containerdns.local 127.0.0.1\n    Server:         127.0.0.1\n    Address:        127.0.0.1#53\n\n    Name:   cctv2.containerdns.local\n    Address: 192.168.10.3\n    \n    % etcdctl get /containerdns/monitor/status/192.168.10.3\n    {\"status\":\"DOWN\"}\n\n    % nslookup cctv2.containerdns.local 127.0.0.1\n    Server:         127.0.0.1\n    Address:        127.0.0.1#53\n\n    Name:   cctv2.containerdns.local\n    Address: 192.168.10.1\n    \n    we query the domain cctv2.containerdns.local form containerdns we get the ip 192.168.10.3, then we shut down the service, we query the domain again\n    we get the ip 192.168.10.1.\n```\n## Performance Test\n\n### Testing Conditions\n#### Physical hardware\n```\n    NIC: gigabit ethernet card\n    CPUs: 32\n    RAM: 32G\n    OS: CentOS-7.2\n```\n#### Testing Software\n```\n    queryperf\n```\n\n### Test result\n   ![image](https://github.com/tiglabs/containerdns/blob/master/images/DNS_performance.png)\n\n## DPDK-based Optimization\n\nImprove ContainerDNS throughput by leveraging the DPDK technology to reach nearly 10 million QPS, https://github.com/tiglabs/containerdns/kdns and the code is also production-ready. \n\n\n## Reference\n\nReference to cite when you use ContainerDNS in a paper or technical report: \"Haifeng Liu, Shugang Chen, Yongcheng Bao, Wanli Yang, and Yuan Chen, Wei Ding, Huasong Shan. A High Performance, Scalable DNS Service for Very Large Scale Container Cloud Platforms. In 19th International Middleware Conference Industry, December 10–14, 2018, Rennes, France. \"\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiglabs%2Fcontainerdns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiglabs%2Fcontainerdns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiglabs%2Fcontainerdns/lists"}