Update Consul DNS on kube docs

- fix instructions for CoreDNS (it updated)
- fix instructions for new component names
- recommend installing with the name 'consul'
- add disclaimer that catalog sync is not always required
- clean up example values.yaml files

website/source/docs/platform/k8s/dns.html.md

@@ -9,19 +9,48 @@ description: |-
 # Consul DNS on Kubernetes
 
 One of the primary query interfaces to Consul is the
-[DNS interface](/docs/agent/dns.html). The Consul DNS interface can be
+[DNS interface](/docs/agent/dns.html). Consul DNS can be configured in
-exposed for all pods in Kubernetes using a
+Kubernetes using a
-[stub-domain configuration](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configure-stub-domain-and-upstream-dns-servers).
+[stub-domain configuration](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configure-stub-domain-and-upstream-dns-servers)
+if using KubeDNS or a [proxy configuration](https://coredns.io/plugins/proxy/) if using CoreDNS.
 
-The stub-domain configuration must point to a static IP of a DNS resolver.
+Once configured, DNS requests in the form `{consul-service-name}.service.consul` will
-The [Helm chart](/docs/platform/k8s/helm.html) creates a `consul-dns` service
+resolve for services in Consul. This will work from all namespaces.
-by default that exports Consul DNS. The cluster IP of this service can be used
-to configure a stub-domain with kube-dns. While the `kube-dns` configuration
-lives in the `kube-system` namespace, the IP just has to be routable so the
-service can live in a different namespace.
 
+-> **Note:** If you want requests to just `{consul-service-name}` (without the `.service.consul`) to resolve, then you'll need
+to turn on [Consul to Kubernetes Service Sync](/docs/platform/k8s/service-sync.html#consul-to-kubernetes).
+
+## Consul DNS Cluster IP
+For configuring KubeDNS or CoreDNS you'll first need the `ClusterIP` of the Consul
+DNS service created by the [Helm chart](/docs/platform/k8s/helm.html).
+
+The name of the Consul DNS service will be `consul-consul-dns`. Use
+that name to get the `ClusterIP`:
+
+```bash
+$ kubectl get svc consul-consul-dns -o jsonpath='{.spec.clusterIP}'
+10.35.240.78%
 ```
-cat <<EOF | kubectl apply -f -
+
+-> *Note:* If you've installed Consul using a different helm release name than `consul`
+then the DNS service name will be `{release-name}-consul-dns`.
+
+For this installation the `ClusterIP` is `10.35.240.78`. 
+
+## KubeDNS
+If using KubeDNS, you need to create a `ConfigMap` that tells KubeDNS
+to use the Consul DNS service to resolve all domains ending with `.consul`:
+
+Export the Consul DNS IP as an environment variable:
+
+```bash
+export CONSUL_DNS_IP=10.35.240.78
+```
+
+And create the `ConfigMap`:
+
+```bash
+$ cat <<EOF | kubectl apply -f -
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -31,24 +60,53 @@ metadata:
   namespace: kube-system
 data:
   stubDomains: |
-    {"consul": ["$(kubectl get svc consul-dns -o jsonpath='{.spec.clusterIP}')"]}
+    {"consul": ["$CONSUL_DNS_IP"]}
 EOF
+Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
+configmap/kube-dns configured
+```
+
+Ensure that the `ConfigMap` was created successfully:
+
+```bash
+$ kubectl get configmap kube-dns -n kube-system -o yaml
+apiVersion: v1
+data:
+  stubDomains: |
+    {"consul": ["10.35.240.78"]}
+kind: ConfigMap
+...
 ```
 
 -> **Note:** The `stubDomain` can only point to a static IP. If the cluster IP
-of the `consul-dns` service changes, then it must be updated in the config map to 
+of the Consul DNS service changes, then it must be updated in the config map to 
 match the new service IP for this to continue
 working. This can happen if the service is deleted and recreated, such as
 in full cluster rebuilds.
 
+-> **Note:** If using a different zone than `.consul`, change the stub domain to
+that zone.
+
+Now skip ahead to the [Verifying DNS Works](#verifying-dns-works) section.
+
 ## CoreDNS Configuration
 
-If you are using CoreDNS instead of kube-dns in your Kubernetes cluster, you will
+If using CoreDNS instead of KubeDNS in your Kubernetes cluster, you will
 need to update your existing `coredns` ConfigMap in the `kube-system` namespace to
-include a proxy definition for `consul` that points to the cluster IP of the 
+include a `forward` definition for `consul` that points to the cluster IP of the
-`consul-dns` service.
+Consul DNS service.
 
+Edit the `ConfigMap`:
+
+```bash
+$ kubectl edit configmap coredns -n kube-system
 ```
+
+And add the `consul` block below the default `.:53` block and replace
+`<consul-dns-service-cluster-ip>` with the DNS Service's IP address you
+found previously.
+
+```diff
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -61,11 +119,11 @@ data:
     .:53 {
         <Existing CoreDNS definition>
     }
-    consul {
++   consul {
-      errors
++     errors
-      cache 30
++     cache 30
-      proxy . <consul-dns service cluster ip>
++     forward . <consul-dns-service-cluster-ip>
-    }
++   }
 ```
 
 -> **Note:** The consul proxy can only point to a static IP. If the cluster IP
@@ -73,6 +131,8 @@ of the `consul-dns` service changes, then it must be updated to the new IP to co
 working. This can happen if the service is deleted and recreated, such as
 in full cluster rebuilds.
 
+-> **Note:** If using a different zone than `.consul`, change the key accordingly.
+
 ## Verifying DNS Works
 
 To verify DNS works, run a simple job to query DNS. Save the following
@@ -102,7 +162,7 @@ Then query the pod name for the job and check the logs. You should see
 output similar to the following showing a successful DNS query. If you see
 any errors, then DNS is not configured properly.
 
-```
+```sh
 $ kubectl get pods --show-all | grep dns
 dns-lkgzl         0/1       Completed   0          6m
 

website/source/docs/platform/k8s/helm.html.md

@@ -33,30 +33,60 @@ require additional manual configuration.
 
 ## Using the Helm Chart
 
-To use the Helm chart, you must download or clone the
+To install Consul using the Helm chart you must first install Helm onto
-[consul-helm GitHub repository](https://github.com/hashicorp/consul-helm)
+your Kubernetes cluster. See the
-and run Helm against the directory. We plan to transition to using a real
+[Helm Install Guide](https://helm.sh/docs/using_helm/#installing-helm) for more information.
-Helm repository soon. When running Helm, we highly recommend you always
-checkout a specific tagged release of the chart to avoid any
-instabilities from master.
 
-Prior to this, you must have Helm installed and configured both in your
+Once Helm is installed, determine the latest version of the Consul Helm chart
-Kubernetes cluster and locally on your machine. The steps to do this are
+by visiting [https://github.com/hashicorp/consul-helm/releases](https://github.com/hashicorp/consul-helm/releases).
-out of the scope of this document, please read the
-[Helm documentation](https://helm.sh/) for more information.
 
-Example chart usage:
+Clone the chart at that version, for example if the latest version is
+`v0.8.1` you would run:
+
+```bash
+$ git clone --single-branch --branch v0.8.1 https://github.com/hashicorp/consul-helm.git
+Cloning into 'consul-helm'...
+...
+You are in 'detached HEAD' state...
+```
+
+Ensure you've checked out the correct version with `helm inspect`:
+
+```bash
+$ helm inspect chart ./consul-helm
+apiVersion: v1
+description: Install and configure Consul on Kubernetes.
+home: https://www.consul.io
+name: consul
+sources:
+- https://github.com/hashicorp/consul
+- https://github.com/hashicorp/consul-helm
+- https://github.com/hashicorp/consul-k8s
+version: 0.8.1
+```
+
+Now you're ready to install Consul! To install Consul with the default
+configuration run:
 
 ```sh
-# Clone the chart repo
+$ helm install --name consul ./consul-helm
-$ git clone https://github.com/hashicorp/consul-helm.git
+NAME:   consul
-$ cd consul-helm
+...
+Your release is named consul. To learn more about the release, try:
 
-# Checkout the most recently tagged version
+  $ helm status consul
-$ git checkout $(git describe --abbrev=0 --tags)
+  $ helm get consul
+```
 
-# Run Helm
+If you want to customize the installation,
-$ helm install --dry-run ./
+create a `values.yaml` file to override the default settings.
+You can learn what settings are available by running `helm inspect values ./consul-helm`
+or by reading the below [Configuration](#configuration-values) section.
+
+Once you've created your `values.yaml` file, run `helm install` with the `-f` flag:
+
+```bash
+$ helm install --name consul -f ./values.yaml ./consul-helm
 ```
 
 ~> **Warning:** By default, the chart will install _everything_: a
@@ -413,13 +443,13 @@ Add the `--wait` option to your `helm install` command. This will force Helm to
 to become ready before it applies the license to your Consul cluster.
 
 ```bash
-$ helm install --wait .
+$ helm install --wait --name consul -f ./values.yaml ./consul-helm
 ```
 
 Once the cluster is up, you can verify the nodes are running Consul Enterprise.
 
 ```bash
-$ kubectl port-forward service/consul-server 8500 &
+$ kubectl port-forward service/consul-consul-server 8500 &
 $ consul license get
 License is valid
 License ID: 1931d1f4-bdfd-6881-f3f5-19349374841f
@@ -436,54 +466,38 @@ Licensed Features:
         Advanced Network Federation
 $ consul members
 Node                                       Address           Status  Type    Build      Protocol  DC   Segment
-consul-server-0                            10.60.0.187:8301  alive   server  1.4.3+ent  2         dc1  <all>
+consul-consul-server-0                     10.60.0.187:8301  alive   server  1.4.3+ent  2         dc1  <all>
-consul-server-1                            10.60.1.229:8301  alive   server  1.4.3+ent  2         dc1  <all>
+consul-consul-server-1                     10.60.1.229:8301  alive   server  1.4.3+ent  2         dc1  <all>
-consul-server-2                            10.60.2.197:8301  alive   server  1.4.3+ent  2         dc1  <all>
+consul-consul-server-2                     10.60.2.197:8301  alive   server  1.4.3+ent  2         dc1  <all>
 ```
 
 ## Helm Chart Examples
 
-The below values.yaml can be used to set up a single server Consul cluster with a LoadBalancer to allow external access to the UI and API.
+The below `values.yaml` can be used to set up a single server Consul cluster with a `LoadBalancer` to allow external access to the UI and API.
 
-```
+```yaml
 global:
   enabled: true
-  image: "consul:1.4.2"
-  domain: consul
-  datacenter: dc1
 
 server:
-  enabled: true
   replicas: 1
   bootstrapExpect: 1
-  storage: 10Gi
-
-client:
-  enabled: true
-
-dns:
-  enabled: true
 
 ui:
-  enabled: true
   service:
-    enabled: true
     type: LoadBalancer
 ```
 
-The below values.yaml can be used to set up a three server Consul Enterprise cluster with 100GB of storage and automatic Connect injection for annotated pods in the "my-app" namespace.
+The below `values.yaml` can be used to set up a three server Consul Enterprise cluster with 100GB of storage and automatic Connect injection for annotated pods in the "my-app" namespace.
 
 Note, this would require a secret that contains the enterprise license key.
 
-```
+```yaml
 global:
-  enabled: true
-  domain: consul
   image: "hashicorp/consul-enterprise:1.4.2-ent"
   datacenter: dc1
 
 server:
-  enabled: true
   replicas: 3
   bootstrapExpect: 3
   enterpriseLicense:
@@ -491,36 +505,18 @@ server:
     secretKey: "key"
   storage: 100Gi
   connect: true
-  affinity: |
-    podAntiAffinity:
-      requiredDuringSchedulingIgnoredDuringExecution:
-        - labelSelector:
-          matchLabels:
-            app: {{ template "consul.name" . }}
-            release: "{{ .Release.Name }}"
-            component: server
-        topologyKey: kubernetes.io/hostname
 
 client:
-  enabled: true
   grpc: true
 
-dns:
-  enabled: true
-
-ui:
-  enabled: true
-  service:
-    enabled: true
-    type: NodePort
-
 connectInject:
   enabled: true
   default: false
   namespaceSelector: "my-app"
-
 ```
 
 ## Customizing the Helm Chart
 
-Consul within Kubernetes is highly configurable and the Helm chart contains dozens of the most commonly used configuration options. If you need to extend the Helm chart with additional options, we recommend using a third-party tool, such as [kustomize](https://github.com/kubernetes-sigs/kustomize) or [ship](https://github.com/replicatedhq/ship).
+Consul within Kubernetes is highly configurable and the Helm chart contains dozens
+of the most commonly used configuration options.
+If you need to extend the Helm chart with additional options, we recommend using a third-party tool, such as [kustomize](https://github.com/kubernetes-sigs/kustomize) or [ship](https://github.com/replicatedhq/ship).

website/source/docs/platform/k8s/service-sync.html.md

@@ -53,7 +53,26 @@ syncCatalog:
 
 This will enable services to sync _in both directions_. You can also choose
 to only sync Kubernetes services to Consul or vice versa by disabling a direction.
-See the [Helm configuration](/docs/platform/k8s/helm.html#configuration-values-)
+
+To only enable syncing Consul services to Kubernetes use the config:
+
+```yaml
+syncCatalog:
+  enabled: true
+  toConsul: false
+  toK8S: true
+```
+
+To only enable syncing Kubernetes services to Consul use:
+
+```yaml
+syncCatalog:
+  enabled: true
+  toConsul: true
+  toK8S: false
+```
+
+See the [Helm configuration](/docs/platform/k8s/helm.html#v-synccatalog)
 for more information.
 
 -> **Before installing,** please read the introduction paragraphs for the
@@ -67,7 +86,9 @@ sync to understand how the syncing works.
 The sync process must authenticate to both Kubernetes and Consul to read
 and write services.
 
-For Kubernetes, a valid kubeconfig file must be provided with cluster
+If running `consul-k8s` using the Helm chart then this authentication is handled for you.
+
+If running `consul-k8s` outside of Kubernetes, a valid kubeconfig file must be provided with cluster
 and authentication information. The sync process will look into the default locations
 for both in-cluster and out-of-cluster authentication. If `kubectl` works,
 then the sync program should work.
@@ -240,22 +261,36 @@ metadata:
 ## Consul to Kubernetes
 
 This syncs Consul services into first-class Kubernetes services.
-Each Consul service is synced to an
+An [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname)
-[ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname)
+`Service` is created for each Consul service. The "external name" will be
-service in Kubernetes. The external name is configured to be the Consul
+the Consul DNS name.
-DNS entry.
 
-This enables external services to be discovered using native Kubernetes
+For example, given a Consul service `foo`, a Kubernetes Service will be created
-tooling. This can be used to ease software migration into or out of Kubernetes,
+as follows:
-across platforms, to and from hosted services, and more.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: foo
+  ...
+spec:
+  externalName: foo.service.consul
+  type: ExternalName
+```
+
+With Consul To Kubernetes syncing enabled, DNS requests of the form `{consul-service-name}`
+will be serviced by Consul DNS. From a different namespace than where Consul
+is deployed, the DNS request would need to be `{consul-service-name}.{consul-namespace}`.
+
+-> **Note:** Consul to Kubernetes syncing **isn't required** if you've enabled [Consul DNS on Kubernetes](/docs/platform/k8s/dns.html)
+*and* all you need to do is address services in the form `{consul-service-name}.service.consul`, i.e. you don't need Kubernetes `Service` objects created.
 
 -> **Requires Consul DNS via CoreDNS in Kubernetes:** This feature requires that
 [Consul DNS](/docs/platform/k8s/dns.html) is configured within Kubernetes.
 Additionally, **[CoreDNS](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#config-coredns)
 is required (instead of kube-dns)** to resolve an
 issue with resolving `externalName` services pointing to custom domains.
-In the future we hope to remove this requirement by syncing the instance
-addresses directly into service endpoints.
 
 ### Sync Enable/Disable