status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
This commit is contained in:
Luke Kysow 2019-09-06 11:33:13 +02:00
parent e11d07a685
commit 2a0d9ff882
No known key found for this signature in database
GPG Key ID: FA168D4DC3F04307
3 changed files with 187 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
website/source/docs/platform/k8s/dns.html.md
View File

@ -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 <<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
`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
`<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 {
errors
cache 30
proxy . <consul-dns service cluster ip>
}
+ consul {
+ errors
+ cache 30
+ 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

124
website/source/docs/platform/k8s/helm.html.md
View File

@ -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 <all>
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-0 10.60.0.187: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-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).

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

@ -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