From 3aec38d592b85e38ce3d642eaa2337b0675db443 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 21 Jun 2021 13:00:17 -0400 Subject: [PATCH 1/4] contrib: add some docs for the DNS interface --- contributing/README.md | 1 + contributing/service-discovery/README.md | 5 +++++ contributing/service-discovery/dns.md | 28 ++++++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 contributing/service-discovery/README.md create mode 100644 contributing/service-discovery/dns.md diff --git a/contributing/README.md b/contributing/README.md index 0c61758d8f..d84e41824d 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -11,3 +11,4 @@ understanding, and contributing changes to, the Consul codebase. 2. [Configuration](./checklist-adding-config-fields.md) 3. [Streaming](./streaming) 4. [Network Areas](./network-areas) +5. [Service Discovery](./service-discovery) diff --git a/contributing/service-discovery/README.md b/contributing/service-discovery/README.md new file mode 100644 index 0000000000..50e8e2c0b0 --- /dev/null +++ b/contributing/service-discovery/README.md @@ -0,0 +1,5 @@ +# Service Discovery + +This section is still a work in progress. + +1. [DNS Interface](./dns.md) diff --git a/contributing/service-discovery/dns.md b/contributing/service-discovery/dns.md new file mode 100644 index 0000000000..599b9f2eea --- /dev/null +++ b/contributing/service-discovery/dns.md @@ -0,0 +1,28 @@ +# DNS Interface + +The DNS interface allows users to find the IP address and port of services, using DNS +queries. The DNS interface is in many ways similar to an HTTP API. The major difference is +in the DNS protocol. + +There are lots of guides to DNS, the following list is a short reference that should help you +understand the parts that are relevant to the DNS interface in Consul. Full details about +the DNS protocol can be found in the RFCs: [RFC 1035], [RFC 6891], [RFC 2782], and others. + +[RFC 1035]: https://tools.ietf.org/html/rfc1035 +[RFC 6891]: https://tools.ietf.org/html/rfc6891 +[RFC 2782]: https://tools.ietf.org/html/rfc2782 + +* [wikipedia: DNS message format](https://en.wikipedia.org/wiki/Domain_Name_System#DNS_message_format) + is a quick introduction to the format used for queries and replies +* [RFC 1035 Section 4.1.1](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1.1) + is a good reference for when to use specific response codes and what the different header + bits refer to. + + +## DNS Server + +The DNS interface is implemented as a DNS server using [miekg/dns] and the handlers for +requests are in `agent/dns.go`. + + +[miekg/dns]: https://github.com/miekg/dns From 0057b8df490c95a5a84fcd8e6b774da26ba96e45 Mon Sep 17 00:00:00 2001 From: Dhia Ayachi Date: Tue, 22 Jun 2021 13:28:07 -0400 Subject: [PATCH 2/4] add matrix for dns type vs kind --- contributing/service-discovery/dns-matrix.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 contributing/service-discovery/dns-matrix.md diff --git a/contributing/service-discovery/dns-matrix.md b/contributing/service-discovery/dns-matrix.md new file mode 100644 index 0000000000..33b32a4d84 --- /dev/null +++ b/contributing/service-discovery/dns-matrix.md @@ -0,0 +1,12 @@ +| | service | connect (enterprise) | ingress (enterprise) | node | query | addr | +|----------------|-------------------------|-------------------------|-------------------------|------------------------|-----------------|------------------------------| +| TypeSOA | Supported | Supported | Supported | Supported | Supported | Supported | +| TypeNS | Supported | Supported | Supported | Supported | Supported | Supported | +| TypeAXFR | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | +| TypeA/TypeAAAA | Supported | Supported | Supported | Supported | | Supported | +| TypeANY | Supported (return A) | Supported (return A) | Supported (return A) | Supported | | Supported (return A) | +| TypeCNAME | Supported (node cname) | Supported (node cname) | Supported (node cname) | Supported (node cname) | | return empty with A as extra | +| TypeOPT | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | | return empty with A as extra | +| TypePTR | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | | return empty with A as extra | +| TypeSRV | Supported (service SRV) | Supported (service SRV) | Supported (service SRV) | No error but empty | | return empty with A as extra | +| TypeTXT | Answer A record (????) | Answer A record (????) | Answer A record (????) | Supported | | return empty with A as extra | \ No newline at end of file From 111cbe0ffa99a21b8f7ca0df1883162a7c42ebdf Mon Sep 17 00:00:00 2001 From: Dhia Ayachi Date: Wed, 23 Jun 2021 09:34:34 -0400 Subject: [PATCH 3/4] merge dns table with current dns page --- contributing/service-discovery/dns-matrix.md | 12 ------------ contributing/service-discovery/dns.md | 14 ++++++++++++++ 2 files changed, 14 insertions(+), 12 deletions(-) delete mode 100644 contributing/service-discovery/dns-matrix.md diff --git a/contributing/service-discovery/dns-matrix.md b/contributing/service-discovery/dns-matrix.md deleted file mode 100644 index 33b32a4d84..0000000000 --- a/contributing/service-discovery/dns-matrix.md +++ /dev/null @@ -1,12 +0,0 @@ -| | service | connect (enterprise) | ingress (enterprise) | node | query | addr | -|----------------|-------------------------|-------------------------|-------------------------|------------------------|-----------------|------------------------------| -| TypeSOA | Supported | Supported | Supported | Supported | Supported | Supported | -| TypeNS | Supported | Supported | Supported | Supported | Supported | Supported | -| TypeAXFR | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | -| TypeA/TypeAAAA | Supported | Supported | Supported | Supported | | Supported | -| TypeANY | Supported (return A) | Supported (return A) | Supported (return A) | Supported | | Supported (return A) | -| TypeCNAME | Supported (node cname) | Supported (node cname) | Supported (node cname) | Supported (node cname) | | return empty with A as extra | -| TypeOPT | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | | return empty with A as extra | -| TypePTR | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | | return empty with A as extra | -| TypeSRV | Supported (service SRV) | Supported (service SRV) | Supported (service SRV) | No error but empty | | return empty with A as extra | -| TypeTXT | Answer A record (????) | Answer A record (????) | Answer A record (????) | Supported | | return empty with A as extra | \ No newline at end of file diff --git a/contributing/service-discovery/dns.md b/contributing/service-discovery/dns.md index 599b9f2eea..cfc9566e33 100644 --- a/contributing/service-discovery/dns.md +++ b/contributing/service-discovery/dns.md @@ -24,5 +24,19 @@ the DNS protocol can be found in the RFCs: [RFC 1035], [RFC 6891], [RFC 2782], a The DNS interface is implemented as a DNS server using [miekg/dns] and the handlers for requests are in `agent/dns.go`. +The following table describe the current DNS behaviour depending on the dns query kind (node, service...), and the query type (A/AAAA, SRV...) + +| | service | connect (enterprise) | ingress (enterprise) | node | query | addr | +|----------------|-------------------------|-------------------------|-------------------------|------------------------|-----------------|------------------------------| +| TypeSOA | Supported | Supported | Supported | Supported | Supported | Supported | +| TypeNS | Supported | Supported | Supported | Supported | Supported | Supported | +| TypeAXFR | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | +| TypeA/TypeAAAA | Supported | Supported | Supported | Supported | | Supported | +| TypeANY | Supported (return A) | Supported (return A) | Supported (return A) | Supported | | Supported (return A) | +| TypeCNAME | Supported (node cname) | Supported (node cname) | Supported (node cname) | Supported (node cname) | | return empty with A as extra | +| TypeOPT | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | | return empty with A as extra | +| TypePTR | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | | return empty with A as extra | +| TypeSRV | Supported (service SRV) | Supported (service SRV) | Supported (service SRV) | No error but empty | | return empty with A as extra | +| TypeTXT | Answer A record (????) | Answer A record (????) | Answer A record (????) | Supported | | return empty with A as extra | [miekg/dns]: https://github.com/miekg/dns From e000c0a039caa92e26f064863c56d2497e0a18f6 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Wed, 23 Jun 2021 12:29:02 -0400 Subject: [PATCH 4/4] contrib: Update DNS table description --- contributing/service-discovery/dns.md | 37 ++++++++++++++++----------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/contributing/service-discovery/dns.md b/contributing/service-discovery/dns.md index cfc9566e33..357ecc57dc 100644 --- a/contributing/service-discovery/dns.md +++ b/contributing/service-discovery/dns.md @@ -24,19 +24,26 @@ the DNS protocol can be found in the RFCs: [RFC 1035], [RFC 6891], [RFC 2782], a The DNS interface is implemented as a DNS server using [miekg/dns] and the handlers for requests are in `agent/dns.go`. -The following table describe the current DNS behaviour depending on the dns query kind (node, service...), and the query type (A/AAAA, SRV...) - -| | service | connect (enterprise) | ingress (enterprise) | node | query | addr | -|----------------|-------------------------|-------------------------|-------------------------|------------------------|-----------------|------------------------------| -| TypeSOA | Supported | Supported | Supported | Supported | Supported | Supported | -| TypeNS | Supported | Supported | Supported | Supported | Supported | Supported | -| TypeAXFR | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | -| TypeA/TypeAAAA | Supported | Supported | Supported | Supported | | Supported | -| TypeANY | Supported (return A) | Supported (return A) | Supported (return A) | Supported | | Supported (return A) | -| TypeCNAME | Supported (node cname) | Supported (node cname) | Supported (node cname) | Supported (node cname) | | return empty with A as extra | -| TypeOPT | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | | return empty with A as extra | -| TypePTR | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | | return empty with A as extra | -| TypeSRV | Supported (service SRV) | Supported (service SRV) | Supported (service SRV) | No error but empty | | return empty with A as extra | -| TypeTXT | Answer A record (????) | Answer A record (????) | Answer A record (????) | Supported | | return empty with A as extra | - [miekg/dns]: https://github.com/miekg/dns + +## DNS Queries and Records + +The DNS interface handles queries where OPCODE=0 (standard query). The following table describe the current +DNS behaviour for different record types and domain names. The Domain names (along the +top) are always in the form `..`, where `domain` is +generally documented as `consul` but can be set using the `domain` or `alt_domain` config +fields. The `prefix` is an identifier (service name, node name, prepared query name, etc). + +| Type | service | connect | ingress | node | query | addr | +|---------|-------------------------|-------------------------|-------------------------|------------------------|-----------------|------------------------------| +| SOA | Supported | Supported | Supported | Supported | Supported | Supported | +| NS | Supported | Supported | Supported | Supported | Supported | Supported | +| AXFR | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | Not Implemented | +| A/AAAA | Supported | Supported | Supported | Supported | | Supported | +| ANY | Supported (return A) | Supported (return A) | Supported (return A) | Supported | | Supported (return A) | +| CNAME | Supported (node cname) | Supported (node cname) | Supported (node cname) | Supported (node cname) | | return empty with A as extra | +| OPT | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | Supported (node OPT) | | return empty with A as extra | +| PTR | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | Supported (node PTR) | | return empty with A as extra | +| SRV | Supported (service SRV) | Supported (service SRV) | Supported (service SRV) | No error but empty | | return empty with A as extra | +| TXT | Answer A record (????) | Answer A record (????) | Answer A record (????) | Supported | | return empty with A as extra | +