github.com/sl1pm4t/consul@v1.4.5-0.20190325224627-74c31c540f9c/website/source/docs/platform/k8s/dns.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Consul DNS - Kubernetes"
     4  sidebar_current: "docs-platform-k8s-dns"
     5  description: |-
     6    One of the primary query interfaces to Consul is the DNS interface. The Consul DNS interface can be exposed for all pods in Kubernetes using a stub-domain configuration.
     7  ---
     8  
     9  # Consul DNS on Kubernetes
    10  
    11  One of the primary query interfaces to Consul is the
    12  [DNS interface](/docs/agent/dns.html). The Consul DNS interface can be
    13  exposed for all pods in Kubernetes using a
    14  [stub-domain configuration](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configure-stub-domain-and-upstream-dns-servers).
    15  
    16  The stub-domain configuration must point to a static IP of a DNS resolver.
    17  The [Helm chart](/docs/platform/k8s/helm.html) creates a `consul-dns` service
    18  by default that exports Consul DNS. The cluster IP of this service can be used
    19  to configure a stub-domain with kube-dns. While the `kube-dns` configuration
    20  lives in the `kube-system` namepace, the IP just has to be routable so the
    21  service can live in a different namespace.
    22  
    23  ```
    24  cat <<EOF | kubectl apply -f -
    25  apiVersion: v1
    26  kind: ConfigMap
    27  metadata:
    28    labels:
    29      addonmanager.kubernetes.io/mode: EnsureExists
    30    name: kube-dns
    31    namespace: kube-system
    32  data:
    33    stubDomains: |
    34      {"consul": ["$(kubectl get svc consul-dns -o jsonpath='{.spec.clusterIP}')"]}
    35  EOF
    36  ```
    37  
    38  -> **Note:** The `stubDomain` can only point to a static IP. If the cluster IP
    39  of the `consul-dns` service changes, then it must be updated in the config map to 
    40  match the new service IP for this to continue
    41  working. This can happen if the service is deleted and recreated, such as
    42  in full cluster rebuilds.
    43  
    44  ## CoreDNS Configuration
    45  
    46  If you are using CoreDNS instead of kube-dns in your Kubernetes cluster, you will
    47  need to update your existing `coredns` ConfigMap in the `kube-system` namespace to
    48  include a proxy definition for `consul` that points to the cluster IP of the 
    49  `consul-dns` service.
    50  
    51  ```
    52  apiVersion: v1
    53  kind: ConfigMap
    54  metadata:
    55    labels:
    56      addonmanager.kubernetes.io/mode: EnsureExists
    57    name: coredns
    58    namespace: kube-system
    59  data:
    60    Corefile: |
    61      .:53 {
    62          <Existing CoreDNS definition>
    63      }
    64      consul {
    65        errors
    66        cache 30
    67        proxy . <consul-dns service cluster ip>
    68      }
    69  ```
    70  
    71  -> **Note:** The consul proxy can only point to a static IP. If the cluster IP
    72  of the `consul-dns` service changes, then it must be updated to the new IP to continue
    73  working. This can happen if the service is deleted and recreated, such as
    74  in full cluster rebuilds.
    75  
    76  ## Verifying DNS Works
    77  
    78  To verify DNS works, run a simple job to query DNS. Save the following
    79  job to the file `job.yaml` and run it:
    80  
    81  ```yaml
    82  apiVersion: batch/v1
    83  kind: Job
    84  metadata:
    85    name: dns
    86  spec:
    87    template:
    88      spec:
    89        containers:
    90        - name: dns
    91          image: anubhavmishra/tiny-tools
    92          command: ["dig",  "consul.service.consul"]
    93        restartPolicy: Never
    94    backoffLimit: 4
    95  ```
    96  
    97  ```sh
    98  $ kubectl apply -f job.yaml
    99  ```
   100  
   101  Then query the pod name for the job and check the logs. You should see
   102  output similar to the following showing a successful DNS query. If you see
   103  any errors, then DNS is not configured properly.
   104  
   105  ```
   106  $ kubectl get pods --show-all | grep dns
   107  dns-lkgzl         0/1       Completed   0          6m
   108  
   109  $ kubectl logs dns-lkgzl
   110  ; <<>> DiG 9.11.2-P1 <<>> consul.service.consul
   111  ;; global options: +cmd
   112  ;; Got answer:
   113  ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 4489
   114  ;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 4
   115  
   116  ;; OPT PSEUDOSECTION:
   117  ; EDNS: version: 0, flags:; udp: 4096
   118  ;; QUESTION SECTION:
   119  ;consul.service.consul.		IN	A
   120  
   121  ;; ANSWER SECTION:
   122  consul.service.consul.	0	IN	A	10.36.2.23
   123  consul.service.consul.	0	IN	A	10.36.4.12
   124  consul.service.consul.	0	IN	A	10.36.0.11
   125  
   126  ;; ADDITIONAL SECTION:
   127  consul.service.consul.	0	IN	TXT	"consul-network-segment="
   128  consul.service.consul.	0	IN	TXT	"consul-network-segment="
   129  consul.service.consul.	0	IN	TXT	"consul-network-segment="
   130  
   131  ;; Query time: 5 msec
   132  ;; SERVER: 10.39.240.10#53(10.39.240.10)
   133  ;; WHEN: Wed Sep 12 02:12:30 UTC 2018
   134  ;; MSG SIZE  rcvd: 206
   135  ```