diff --git a/website/source/docs/platform/k8s/dns.html.md b/website/source/docs/platform/k8s/dns.html.md index 1754d87fff..b2ff643db5 100644 --- a/website/source/docs/platform/k8s/dns.html.md +++ b/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 -exposed for all pods in Kubernetes using a -[stub-domain configuration](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configure-stub-domain-and-upstream-dns-servers). +[DNS interface](/docs/agent/dns.html). Consul DNS can be configured in +Kubernetes using a +[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. -The [Helm chart](/docs/platform/k8s/helm.html) creates a `consul-dns` service -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. +Once configured, DNS requests in the form `{consul-service-name}.service.consul` will +resolve for services in Consul. This will work from all namespaces. +-> **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 < *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 < **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 -`consul-dns` service. +include a `forward` definition for `consul` that points to the cluster IP of the +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 +`` with the DNS Service's IP address you +found previously. + +```diff apiVersion: v1 kind: ConfigMap metadata: @@ -61,11 +119,11 @@ data: .:53 { } - consul { - errors - cache 30 - proxy . - } ++ consul { ++ errors ++ cache 30 ++ forward . ++ } ``` -> **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 diff --git a/website/source/docs/platform/k8s/helm.html.md b/website/source/docs/platform/k8s/helm.html.md index 1e83959429..3a461bc0ca 100644 --- a/website/source/docs/platform/k8s/helm.html.md +++ b/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 -[consul-helm GitHub repository](https://github.com/hashicorp/consul-helm) -and run Helm against the directory. We plan to transition to using a real -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. +To install Consul using the Helm chart you must first install Helm onto +your Kubernetes cluster. See the +[Helm Install Guide](https://helm.sh/docs/using_helm/#installing-helm) for more information. -Prior to this, you must have Helm installed and configured both in your -Kubernetes cluster and locally on your machine. The steps to do this are -out of the scope of this document, please read the -[Helm documentation](https://helm.sh/) for more information. +Once Helm is installed, determine the latest version of the Consul Helm chart +by visiting [https://github.com/hashicorp/consul-helm/releases](https://github.com/hashicorp/consul-helm/releases). -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 -$ git clone https://github.com/hashicorp/consul-helm.git -$ cd consul-helm +$ helm install --name consul ./consul-helm +NAME: consul +... +Your release is named consul. To learn more about the release, try: -# Checkout the most recently tagged version -$ git checkout $(git describe --abbrev=0 --tags) + $ helm status consul + $ helm get consul +``` -# Run Helm -$ helm install --dry-run ./ +If you want to customize the installation, +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 -consul-server-1 10.60.1.229:8301 alive server 1.4.3+ent 2 dc1 -consul-server-2 10.60.2.197:8301 alive server 1.4.3+ent 2 dc1 +consul-consul-server-0 10.60.0.187:8301 alive server 1.4.3+ent 2 dc1 +consul-consul-server-1 10.60.1.229:8301 alive server 1.4.3+ent 2 dc1 +consul-consul-server-2 10.60.2.197:8301 alive server 1.4.3+ent 2 dc1 ``` ## 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). diff --git a/website/source/docs/platform/k8s/service-sync.html.md b/website/source/docs/platform/k8s/service-sync.html.md index 523a1ba698..f0340ded8a 100644 --- a/website/source/docs/platform/k8s/service-sync.html.md +++ b/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 -[ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) -service in Kubernetes. The external name is configured to be the Consul -DNS entry. +An [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) +`Service` is created for each Consul service. The "external name" will be +the Consul DNS name. -This enables external services to be discovered using native Kubernetes -tooling. This can be used to ease software migration into or out of Kubernetes, -across platforms, to and from hosted services, and more. +For example, given a Consul service `foo`, a Kubernetes Service will be created +as follows: + +```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