Initial Helm Chart/K8S Docs (#4653)
* website: initial Kubernetes section with Helm information * website: extraConfig for clients * website: add more helm fields * website: document extraVolumes * website: document Consul DNS * website: fix typos and show example of downward API
This commit is contained in:
parent
5ecf9823d2
commit
b69342f0c1
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Consul DNS - Kubernetes"
|
||||
sidebar_current: "docs-platform-k8s-dns"
|
||||
description: |-
|
||||
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.
|
||||
---
|
||||
|
||||
# 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).
|
||||
|
||||
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` namepace, the IP just has to be routable so the
|
||||
service can live in a different namespace.
|
||||
|
||||
```
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
labels:
|
||||
addonmanager.kubernetes.io/mode: EnsureExists
|
||||
name: kube-dns
|
||||
namespace: kube-system
|
||||
data:
|
||||
stubDomains: |
|
||||
{"consul": ["$(kubectl get svc consul-dns -o jsonpath='{.spec.clusterIP}')"]}
|
||||
EOF
|
||||
```
|
||||
|
||||
-> **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 to continue
|
||||
working. This can happen if the service is deleted and recreated, such as
|
||||
in full cluster rebuilds.
|
||||
|
||||
## Verifying DNS Works
|
||||
|
||||
To verify DNS works, run a simple job to query DNS. Save the following
|
||||
job to the file `job.yaml` and run it:
|
||||
|
||||
```yaml
|
||||
apiVersion: batch/v1
|
||||
kind: Job
|
||||
metadata:
|
||||
name: dns
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: dns
|
||||
image: anubhavmishra/tiny-tools
|
||||
command: ["dig", "consul.service.consul"]
|
||||
restartPolicy: Never
|
||||
backoffLimit: 4
|
||||
```
|
||||
|
||||
```sh
|
||||
$ kubectl apply -f job.yaml
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
$ kubectl get pods --show-all | grep dns
|
||||
dns-lkgzl 0/1 Completed 0 6m
|
||||
|
||||
$ kubectl logs dns-lkgzl
|
||||
; <<>> DiG 9.11.2-P1 <<>> consul.service.consul
|
||||
;; global options: +cmd
|
||||
;; Got answer:
|
||||
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 4489
|
||||
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 4
|
||||
|
||||
;; OPT PSEUDOSECTION:
|
||||
; EDNS: version: 0, flags:; udp: 4096
|
||||
;; QUESTION SECTION:
|
||||
;consul.service.consul. IN A
|
||||
|
||||
;; ANSWER SECTION:
|
||||
consul.service.consul. 0 IN A 10.36.2.23
|
||||
consul.service.consul. 0 IN A 10.36.4.12
|
||||
consul.service.consul. 0 IN A 10.36.0.11
|
||||
|
||||
;; ADDITIONAL SECTION:
|
||||
consul.service.consul. 0 IN TXT "consul-network-segment="
|
||||
consul.service.consul. 0 IN TXT "consul-network-segment="
|
||||
consul.service.consul. 0 IN TXT "consul-network-segment="
|
||||
|
||||
;; Query time: 5 msec
|
||||
;; SERVER: 10.39.240.10#53(10.39.240.10)
|
||||
;; WHEN: Wed Sep 12 02:12:30 UTC 2018
|
||||
;; MSG SIZE rcvd: 206
|
||||
```
|
|
@ -0,0 +1,261 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Helm - Kubernetes"
|
||||
sidebar_current: "docs-platform-k8s-helm"
|
||||
description: |-
|
||||
The Consul Helm chart is the recommended way to install and configure Consul on Kubernetes. In addition to running Consul itself, the Helm chart is the primary method for installing and configuring Consul integrations with Kubernetes such as catalog syncing, Connect injection, and more.
|
||||
---
|
||||
|
||||
# Helm Chart
|
||||
|
||||
The [Consul Helm chart](https://github.com/hashicorp/consul-helm)
|
||||
is the recommended way to install and configure Consul on Kubernetes.
|
||||
In addition to running Consul itself, the Helm chart is the primary
|
||||
method for installing and configuring Consul integrations with
|
||||
Kubernetes such as catalog syncing, Connect injection, and more.
|
||||
|
||||
This page assumes general knowledge of [Helm](https://helm.sh/) and
|
||||
how to use it. Using Helm to install Consul will require that Helm is
|
||||
properly installed and configured with your Kubernetes cluster.
|
||||
|
||||
-> **Important:** The Helm chart is new and
|
||||
may still change significantly over time. Please always run Helm with
|
||||
`--dry-run` before any install or upgrade to verify changes.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
Example chart usage:
|
||||
|
||||
```sh
|
||||
# Clone the chart repo
|
||||
$ git clone https://github.com/hashicorp/consul-helm.git
|
||||
$ cd consul-helm
|
||||
|
||||
# Checkout a tagged version
|
||||
$ git checkout v0.1.0
|
||||
|
||||
# Run Helm
|
||||
$ helm install --dry-run ./
|
||||
```
|
||||
|
||||
~> **Warning:** By default, the chart will install _everything_: a
|
||||
Consul server cluster, client agents on all nodes, feature components, etc.
|
||||
This provides a nice out-of-box experience for new users, but may not be
|
||||
appropriate for a production setup. Considering setting the `global.enabled`
|
||||
value to `false` and opt-in to the various components.
|
||||
|
||||
## Configuration (Values)
|
||||
|
||||
The chart is highly customizable using
|
||||
[Helm configuration values](https://docs.helm.sh/using_helm/#customizing-the-chart-before-installing).
|
||||
Each value has a sane default tuned for an optimal getting started experience
|
||||
with Consul. Before going into production, please review the parameters below
|
||||
and consider if they're appropriate for your deployment.
|
||||
|
||||
* <a name="v-global" href="#v-global">`global`</a> - These values are global values that affect multiple components of the chart.
|
||||
|
||||
- <a name="v-global-enabled" href="#v-global-enabled">`enabled`</a> (`boolean: true`) -
|
||||
The master enabled/disabled configuration. If this is true, most components
|
||||
will be installed by default. If this is false, no components will be installed
|
||||
by default and manually opt-in is required, such as by setting
|
||||
<a href="#v-">`server.enabled`</a> to true.
|
||||
|
||||
|
||||
- <a name="v-global-domain" href="#v-global-domain">`domain`</a> (`string: "consul"`) -
|
||||
The domain Consul uses for DNS queries. This is used to configure agents both
|
||||
for DNS listening but also to know what domain to join to join the cluster.
|
||||
This should be consistent throughout the chart, but can be overridden
|
||||
per-component as well.
|
||||
|
||||
- <a name="v-global-image" href="#v-global-image">`image`</a> (`string: "consul:latest"`) -
|
||||
The name of the Docker image (including any tag) for the containers running
|
||||
Consul agents. **This should be pinned to a specific version when running
|
||||
in production.** Otherwise, other changes to the chart may inadvertently
|
||||
upgrade your Consul version.
|
||||
|
||||
- <a name="v-global-datacenter" href="#v-global-datacenter">`datacenter`</a> (`string: "dc1"`) -
|
||||
The name of the datacenter that the agent cluster should register as.
|
||||
This must not be changed once the cluster is bootstrapped and running,
|
||||
since Consul doesn't yet support an automatic way to change this value.
|
||||
|
||||
|
||||
* <a name="v-server" href="#v-server">`server`</a> - Values that configure
|
||||
running a Consul server cluster within Kubernetes.
|
||||
|
||||
- <a name="v-server-enabled" href="#v-server-enabled">`enabled`</a> (`boolean: global.enabled`) -
|
||||
If true, the chart will install all the resources necessary for a Consul
|
||||
server cluster. If you're running Consul externally and want agents within
|
||||
Kubernetes to join that cluster, this should probably be false.
|
||||
|
||||
- <a name="v-server-image" href="#v-server-image">`image`</a> (`string: global.image`) -
|
||||
The name of the Docker image (including any tag) for the containers running
|
||||
Consul server agents.
|
||||
|
||||
- <a name="v-server-replicas" href="#v-server-replicas">`replicas`</a> (`integer: 3`) -
|
||||
The number of server agents to run. This determines the fault tolerance
|
||||
of the cluster. Please see the [deployment table](/docs/internals/consensus.html#deployment-table)
|
||||
for more information.
|
||||
|
||||
- <a name="v-server-bootstrapexpect" href="#v-server-bootstrapexpect">`bootstrapExpect`</a> (`integer: 3`) -
|
||||
For new clusters, this is the number of servers to wait for before
|
||||
performing the initial leader election and bootstrap of the cluster. This
|
||||
must be less than or equal to `server.replicas`. This value is only
|
||||
used when bootstrapping new clusters, it has no effect during ongoing cluster
|
||||
maintenance.
|
||||
|
||||
- <a name="v-server-connect" href="#v-server-connect">`connect`</a> (`boolean: true`) -
|
||||
This will enable/disable [Connect](/docs/connect/index.html). Setting this
|
||||
to true _will not_ automatically secure pod communication, this setting will
|
||||
only enable usage of the feature. Consul will automatically initialize a new
|
||||
CA and set of certificates. Additional Connect settings can be configured
|
||||
by setting the `server.extraConfig` value.
|
||||
|
||||
- <a name="v-server-disruptionbudget" href="#v-server-disruptionbudget">`disruptionBudget`</a> -
|
||||
This configures the
|
||||
[PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/)
|
||||
for the server cluster.
|
||||
|
||||
* <a name="v-server-disruptionbudget-enabled" href="#v-server-disruptionbudget-enabled">`enabled`</a> (`boolean: true`) -
|
||||
This will enable/disable registering a PodDisruptionBudget for
|
||||
the server cluster. If this is enabled, it will only register the
|
||||
budget so long as the server cluster is enabled.
|
||||
|
||||
* <a name="v-server-disruptionbudget-maxunavailable" href="#v-server-disruptionbudget-maxunavailable">`maxUnavailable`</a> (`integer: null`) -
|
||||
The maximum number of unavailable pods. By default, this will be automatically
|
||||
computed based on the `server.replicas` value to be `(n/2)-1`.
|
||||
|
||||
- <a name="v-server-extraconfig" href="#v-server-extraconfig">`extraConfig`</a> (`string: "{}"`) -
|
||||
A raw string of extra JSON or HCL configuration for Consul servers. This
|
||||
will be saved as-is into a ConfigMap that is read by the Consul server agents.
|
||||
This can be used to add additional configuration that isn't directly exposed
|
||||
by the chart.
|
||||
|
||||
- <a name="v-server-extravolumes" href="#v-server-extravolumes">`extraVolumes`</a> (`array: []`) -
|
||||
A list of extra volumes to mount for server agents. This is useful for bringing
|
||||
in extra data that can be referenced by other configurations at a well known
|
||||
path, such as TLS certificates or Gossip encryption keys.
|
||||
The value of this should be a list of objects. Each object has the following
|
||||
supports the following keys:
|
||||
|
||||
* <a name="v-server-extravolumes-type" href="#v-server-extravolumes-type">`type`</a> (`string: required`) -
|
||||
Type of the volume, must be one of "configMap" or "secret". Case sensitive.
|
||||
|
||||
* <a name="v-server-extravolumes-name" href="#v-server-extravolumes-name">`name`</a> (`string: required`) -
|
||||
Name of the configMap or secret to be mounted. This also controls the path
|
||||
that it is mounted to. The volume will be mounted to `/config/userconfig/<name>`.
|
||||
|
||||
* <a name="v-server-extravolumes-load" href="#v-server-extravolumes-load">`load`</a> (`boolean: false`) -
|
||||
If true, then the agent will be configured to automatically load HCL/JSON
|
||||
configuration files from this volume with `-config-dir`. This defaults
|
||||
to false.
|
||||
|
||||
- <a name="v-server-resources" href="#v-server-resources">`resources`</a> (`object: {}`) -
|
||||
The resource requests (CPU, memory, etc.) for each of the server agents.
|
||||
This should be an object mapping directly to a Kubernetes
|
||||
[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#resourcerequirements-v1-core) object. If this isn't specified, then the pods
|
||||
won't request any specific amount of resources. **Setting this is highly
|
||||
recommended.**
|
||||
|
||||
- <a name="v-server-storage" href="#v-server-storage">`storage`</a> (`string: "10Gi"`) -
|
||||
The amount of storage to request for the persistant volume backing the
|
||||
Consul server data.
|
||||
|
||||
- <a name="v-server-updatepartition" href="#v-server-updatepartition">`updatePartition`</a> (`integer: 0`) -
|
||||
This value is used to carefully control a rolling update of Consul server
|
||||
agents. This value specifies the
|
||||
[partition](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#partitions)
|
||||
for performing a rolling update. Please read the linked Kubernetes
|
||||
documentation for more information.
|
||||
|
||||
* <a name="v-client" href="#v-client">`client`</a> - Values that configure
|
||||
running a Consul client agent on Kubernetes nodes.
|
||||
|
||||
- <a name="v-client-enabled" href="#v-client-enabled">`enabled`</a> (`boolean: global.enabled`) -
|
||||
If true, the chart will install all the resources necessary for a Consul
|
||||
client on every Kubernetes node. This _does not_ require `server.enabled`,
|
||||
since the agents can be configured to join an external cluster.
|
||||
|
||||
- <a name="v-client-image" href="#v-client-image">`image`</a> (`string: global.image`) -
|
||||
The name of the Docker image (including any tag) for the containers running
|
||||
Consul client agents.
|
||||
|
||||
- <a name="v-client-extraconfig" href="#v-client-extraconfig">`extraConfig`</a> (`string: "{}"`) -
|
||||
A raw string of extra JSON or HCL configuration for Consul clients. This
|
||||
will be saved as-is into a ConfigMap that is read by the Consul agents.
|
||||
This can be used to add additional configuration that isn't directly exposed
|
||||
by the chart.
|
||||
|
||||
- <a name="v-client-extravolumes" href="#v-client-extravolumes">`extraVolumes`</a> (`array: []`) -
|
||||
A list of extra volumes to mount for client agents. This is useful for bringing
|
||||
in extra data that can be referenced by other configurations at a well known
|
||||
path, such as TLS certificates or Gossip encryption keys.
|
||||
The value of this should be a list of objects. Each object has the following
|
||||
supports the following keys:
|
||||
|
||||
* <a name="v-client-extravolumes-type" href="#v-client-extravolumes-type">`type`</a> (`string: required`) -
|
||||
Type of the volume, must be one of "configMap" or "secret". Case sensitive.
|
||||
|
||||
* <a name="v-client-extravolumes-name" href="#v-client-extravolumes-name">`name`</a> (`string: required`) -
|
||||
Name of the configMap or secret to be mounted. This also controls the path
|
||||
that it is mounted to. The volume will be mounted to `/config/userconfig/<name>`.
|
||||
|
||||
* <a name="v-client-extravolumes-load" href="#v-client-extravolumes-load">`load`</a> (`boolean: false`) -
|
||||
If true, then the agent will be configured to automatically load HCL/JSON
|
||||
configuration files from this volume with `-config-dir`. This defaults
|
||||
to false.
|
||||
|
||||
- <a name="v-client-join" href="#v-client-join">`join`</a> (`array<string>: null`) -
|
||||
A list of values to specify to `-retry-join`. If this is `null` (default),
|
||||
then the clients will attempt to automatically join the server cluster
|
||||
running within Kubernetes. This means that with `server.enabled` set to true,
|
||||
clients will automatically join that cluster. If `server.enabled` is not
|
||||
true, then a value must be specified so the clients can join a valid cluster.
|
||||
|
||||
- <a name="v-client-resources" href="#v-client-resources">`resources`</a> (`object: {}`) -
|
||||
The resource requests (CPU, memory, etc.) for each of the client agents.
|
||||
This should be an object mapping directly to a Kubernetes
|
||||
[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#resourcerequirements-v1-core) object. If this isn't specified, then the pods
|
||||
won't request any specific amount of resources.
|
||||
|
||||
* <a name="v-dns" href="#v-dns">`dns`</a> - Values that configure the Consul DNS service.
|
||||
|
||||
- <a name="v-dns-enabled" href="#v-dns-enabled">`enabled`</a> (`boolean: global.enabled`) -
|
||||
If true, a `consul-dns` service will be created that exposes port 53 for
|
||||
TCP and UDP to the running Consul agents (servers and clients). This can
|
||||
then be used to [configure kube-dns](/docs/platform/k8s/dns.html). The Helm
|
||||
chart _does not_ automatically configure kube-dns.
|
||||
|
||||
* <a name="v-ui" href="#v-ui">`ui`</a> - Values that configure the Consul UI.
|
||||
|
||||
- <a name="v-ui-enabled" href="#v-ui-enabled">`enabled`</a> (`boolean: global.enabled`) -
|
||||
If true, the UI will be enabled. This will only _enable_ the UI, it doesn't
|
||||
automatically register any service for external access. The UI will only
|
||||
be enabled on server agents. If `server.enabled` is false, then this setting
|
||||
has no effect. To expose the UI in some way, you must configure
|
||||
`ui.service`.
|
||||
|
||||
- <a name="v-ui-service" href="#v-ui-service">`service`</a> -
|
||||
This configures the `Service` resource registered for the Consul UI.
|
||||
|
||||
* <a name="v-ui-service-enabled" href="#v-ui-service-enabled">`enabled`</a> (`boolean: true`) -
|
||||
This will enable/disable registering a Kubernetes Service for the Consul UI.
|
||||
This value only takes effect if `ui.enabled` is true and taking effect.
|
||||
|
||||
* <a name="v-ui-service-type" href="#v-ui-service-type">`type`</a> (`string: null`) -
|
||||
The service type to register. This defaults to `null` which doesn't set
|
||||
an explicit service type, which typically is defaulted to "ClusterIP"
|
||||
by Kubernetes. The available service types are documented on
|
||||
[the Kubernetes website](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types).
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Kubernetes"
|
||||
sidebar_current: "docs-platform-k8s-index"
|
||||
description: |-
|
||||
Consul has many integrations with Kubernetes. You can deploy Consul to Kubernetes using the Helm Chart, sync services between Consul and Kubernetes, automatically secure Pod communication with Connect, and more. This section documents the official integrations between Consul and Kubernetes.
|
||||
---
|
||||
|
||||
# Kubernetes
|
||||
|
||||
Consul has many integrations with Kubernetes. You can deploy Consul
|
||||
to Kubernetes using the Helm Chart, sync services between Consul and
|
||||
Kubernetes, automatically secure Pod communication with Connect, and more.
|
||||
This section documents the official integrations between Consul and Kubernetes.
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Running a Consul server cluster:** The Consul server cluster can run directly
|
||||
on Kubernetes. This can be used by both nodes within Kubernetes as well as
|
||||
nodes external to Kubernetes, as long as they can communicate to the server
|
||||
nodes via the network.
|
||||
|
||||
**Running Consul clients:** Consul clients can run as pods on every node
|
||||
and expose the Consul API to running pods. This enables many Consul tools
|
||||
such as envconsul, consul-template, and more to work on Kubernetes since a
|
||||
local agent is available. This will also register each Kubernetes node with
|
||||
the Consul catalog for full visibility into your infrastructure
|
||||
|
||||
**Service sync to enable Kubernetes and non-Kubernetes services to communicate:**
|
||||
Consul can sync Kubernetes services with its own service registry. This allows
|
||||
Kubernetes services to use native Kubernetes service discovery to discover
|
||||
and connect to external services, and for external services to use Consul
|
||||
service discovery to discover and connect to Kubernetes services.
|
||||
|
||||
**Automatic encryption and authorization for pod network connections:**
|
||||
Consul can automatically inject the [Connect](/docs/connect/index.html)
|
||||
sidecar into pods so that they can accept and establish encrypted
|
||||
and authorized network connections via mutual TLS. And because Connect
|
||||
can run anywhere, pods can also communicate with external services (and
|
||||
vice versa) over a fully encrypted connection.
|
||||
|
||||
**And more!** Consul can run directly on Kubernetes, so in addition to the
|
||||
native integrations provided by Consul itself, any other tool built for
|
||||
Kubernetes can choose to leverage Consul.
|
|
@ -0,0 +1,274 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Running Consul - Kubernetes"
|
||||
sidebar_current: "docs-platform-k8s-run"
|
||||
description: |-
|
||||
Consul can run directly on Kubernetes, both in server or client mode. For pure-Kubernetes workloads, this enables Consul to also exist purely within Kubernetes. For heterogeneous workloads, Consul agents can join a server running inside or outside of Kubernetes.
|
||||
---
|
||||
|
||||
# Running Consul on Kubernetes
|
||||
|
||||
Consul can run directly on Kubernetes, both in server or client mode.
|
||||
For pure-Kubernetes workloads, this enables Consul to also exist purely
|
||||
within Kubernetes. For heterogeneous workloads, Consul agents can join
|
||||
a server running inside or outside of Kubernetes.
|
||||
|
||||
This page starts with a large how-to section for various specific tasks.
|
||||
To learn more about the general architecture of Consul on Kubernetes, scroll
|
||||
down to the [architecture](/docs/platform/k8s/run.html#architecture) section.
|
||||
|
||||
## Helm Chart
|
||||
|
||||
The recommended way to run Consul on Kubernetes is via the
|
||||
[Helm Chart](/docs/platform/k8s/helm.html). This will install and configure
|
||||
all the necessary components to run Consul. The configuration enables you
|
||||
to run just a server cluster, just a client cluster, or both. Using the Helm
|
||||
Chart, you can have a full Consul deployment up and running in seconds.
|
||||
|
||||
While the Helm Chart exposes dozens of useful configurations and automatically
|
||||
sets up complex resources, it **does not automatically operate Consul.**
|
||||
You are still reponsible for learning how to monitor, backup,
|
||||
upgrade, etc. the Consul cluster.
|
||||
|
||||
The Helm Chart has no required configuration and will install a Consul
|
||||
cluster with sane defaults out of the box. Prior to going to production,
|
||||
it is highly recommended that you
|
||||
[learn about the configuration options](/docs/platform/k8s/helm.html#configuration-values-).
|
||||
|
||||
## How-To
|
||||
|
||||
### Installing Consul
|
||||
|
||||
To install Consul, clone the consul-helm repository, checkout the latest release, and install
|
||||
Consul. You can run `helm install` with the `--dry-run` flag to see the
|
||||
resources it would configure. In a production environment, you should always
|
||||
use the `--dry-run` flag prior to making any changes to the Consul cluster
|
||||
via Helm.
|
||||
|
||||
```sh
|
||||
# Clone the chart repo
|
||||
$ git clone https://github.com/hashicorp/consul-helm.git
|
||||
$ cd consul-helm
|
||||
|
||||
# Checkout a tagged version
|
||||
$ git checkout v0.1.0
|
||||
|
||||
# Run Helm
|
||||
$ helm install --name consul ./
|
||||
...
|
||||
```
|
||||
|
||||
_That's it._ The Helm chart does everything to setup a recommended
|
||||
Consul-on-Kubernetes deployment.
|
||||
In a couple minutes, a Consul cluster will be formed and a leader
|
||||
elected and every node will have a running Consul agent.
|
||||
|
||||
The defaults will install both server and client agents. To install
|
||||
only one or the other, see the
|
||||
[chart configuration values](/docs/platform/k8s/helm.html#configuration-values-).
|
||||
|
||||
### Viewing the Consul UI
|
||||
|
||||
The Consul UI is enabled by default when using the Helm chart.
|
||||
For security reasons, it isn't exposed via a Service by default so you must
|
||||
use `kubectl port-forward` to visit the UI. Once the port is forwarded as
|
||||
shown below, navigate your browser to `http://localhost:8500`.
|
||||
|
||||
```
|
||||
$ kubectl port-forward consul-server-0 8500:8500
|
||||
...
|
||||
```
|
||||
|
||||
The UI can also be exposed via a Kubernetes Service. To do this, configure
|
||||
the [`ui.service` chart values](/docs/platform/k8s/helm.html#v-ui-service).
|
||||
|
||||
### Joining an Existing Consul Cluster
|
||||
|
||||
If you have a Consul cluster already running, you can configure your
|
||||
Kubernetes nodes to join this existing cluster.
|
||||
|
||||
```yaml
|
||||
global:
|
||||
enabled: false
|
||||
|
||||
client:
|
||||
enabled: true
|
||||
join:
|
||||
- "provider=my-cloud config=val ..."
|
||||
```
|
||||
|
||||
The `values.yaml` file to configure the Helm chart sets the proper
|
||||
configuration to join an existing cluster.
|
||||
|
||||
The `global.enabled` value first disables all chart components by default
|
||||
so that each component is opt-in. This allows us to _only_ setup the client
|
||||
agents. We then opt-in to the client agents by setting `client.enabled` to
|
||||
`true`.
|
||||
|
||||
Next, `client.join` is set to an array of valid
|
||||
[`-retry-join` values](/docs/agent/options.html#retry-join). In the
|
||||
example above, a fake [cloud auto-join](/docs/agent/cloud-auto-join.html)
|
||||
value is specified. This should be set to resolve to the proper addresses of
|
||||
your existing Consul cluster.
|
||||
|
||||
-> **Networking:** Note that for the Kubernetes nodes to join an existing
|
||||
cluster, the nodes (and specifically the agent pods) must be able to connect
|
||||
to all other server and client agents inside and _outside_ of Kubernetes.
|
||||
If this isn't possible, consider running the Kubernetes agents as a separate
|
||||
DC or adopting Enterprise for
|
||||
[network segments](/docs/enterprise/network-segments/index.html).
|
||||
|
||||
### Accessing the Consul HTTP API
|
||||
|
||||
The Consul HTTP API should be accessed by communicating to the local agent
|
||||
running on the same node. While technically any listening agent (client or
|
||||
server) can respond to the HTTP API, communicating with the local agent
|
||||
has important caching behavior, and allows you to use the simpler
|
||||
[`/agent` endpoints for services and checks](/api/agent.html).
|
||||
|
||||
For Consul installed via the Helm chart, a client agent is installed on
|
||||
each Kubernetes node. This is explained in the [architecture](/docs/platform/k8s/run.html#client-agents)
|
||||
section. To access the agent, you may use the
|
||||
[downward API](https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/).
|
||||
An example pod specification is shown below:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: consul-example
|
||||
spec:
|
||||
containers:
|
||||
- name: example
|
||||
image: "consul:latest"
|
||||
env:
|
||||
- name: HOST_IP
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: status.hostIP
|
||||
command:
|
||||
- "/bin/sh"
|
||||
- "-ec"
|
||||
- |
|
||||
export CONSUL_HTTP_ADDR="${HOST_IP}:8500"
|
||||
consul kv put hello world
|
||||
restartPolicy: Never
|
||||
```
|
||||
|
||||
### Upgrading Consul on Kubernetes
|
||||
|
||||
To upgrade Consul on Kubernetes, we follow the same pattern as
|
||||
[generally upgrading Consul](/docs/upgrading.html), except we can use
|
||||
the Helm chart to step through a rolling deploy. It is important to understand
|
||||
how to [generally upgrade Consul](/docs/upgrading.html) before reading this
|
||||
section.
|
||||
|
||||
Upgrading Consul on Kubernetes will follow the same pattern: each server
|
||||
will be updated one-by-one. After that is successful, the clients will
|
||||
be updated in batches.
|
||||
|
||||
#### Upgrading Consul Servers
|
||||
|
||||
To initiate the upgrade, change the `server.image` value to the
|
||||
desired Consul version. For illustrative purposes, the example below will
|
||||
use `consul:123.456`. Also set the `server.updatePartition` value
|
||||
_equal to the number of server replicas_:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
image: "consul:123.456"
|
||||
replicas: 3
|
||||
updatePartition: 3
|
||||
```
|
||||
|
||||
The `updatePartition` value controls how many instances of the server
|
||||
cluster are updated. Only instances with an index _greater than_ the
|
||||
`updatePartition` value are updated (zero-indexed). Therefore, by setting
|
||||
it equal to replicas, none should update yet.
|
||||
|
||||
Next, run the upgrade. You should run this with `--dry-run` first to verify
|
||||
the changes that will be sent to the Kubernetes cluster.
|
||||
|
||||
```
|
||||
$ helm upgrade consul ./
|
||||
...
|
||||
```
|
||||
|
||||
This should cause no changes (although the resource will be updated). If
|
||||
everything is stable, begin by decreasing the `updatePartition` value by one,
|
||||
and running `helm upgrade` again. This should cause the first Consul server
|
||||
to be stopped and restarted with the new image.
|
||||
|
||||
Wait until the Consul server cluster is healthy again (30s to a few minutes)
|
||||
then decrease `updatePartition` and upgrade again. Continue until
|
||||
`updatePartition` is `0`. At this point, you may remove the
|
||||
`updatePartition` configuration. Your server upgrade is complete.
|
||||
|
||||
#### Upgrading Consul Clients
|
||||
|
||||
With the servers upgraded, it is time to upgrade the clients. To upgrade
|
||||
the clients, set the `client.image` value to the desired Consul version.
|
||||
Then, run `helm upgrade`. This will upgrade the clients in batches, waiting
|
||||
until the clients come up healthy before continuing.
|
||||
|
||||
## Architecture
|
||||
|
||||
We recommend running Consul on Kubernetes with the same
|
||||
[general architecture](/docs/internals/architecture.html)
|
||||
as running it anywhere else. There are some benefits Kubernetes can provide
|
||||
that eases operating a Consul cluster and we document those below. The standard
|
||||
[production deployment guide](/docs/guides/deployment.html) is still an
|
||||
important read even if running Consul within Kubernetes.
|
||||
|
||||
Each section below will outline the different components of running Consul
|
||||
on Kubernetes and an overview of the resources that are used within the
|
||||
Kubernetes cluster.
|
||||
|
||||
### Server Agents
|
||||
|
||||
The server agents are run as a **StatefulSet**, using persistent volume
|
||||
claims to store the server state. This also ensures that the
|
||||
[node ID](/docs/agent/options.html#_node_id) is persisted so that servers
|
||||
can be rescheduled onto new IP addresses without causing issues. The server agents
|
||||
are configured with
|
||||
[anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity)
|
||||
rules so that they are placed on different nodes. A readiness probe is
|
||||
configured that marks the pod as ready only when it has established a leader.
|
||||
|
||||
A **Service** is registered to represent the servers and expose the various
|
||||
ports. The DNS address of this service is used to join the servers to each
|
||||
other without requiring any other access to the Kubernetes cluster. The
|
||||
service is configured to publish non-ready endpoints so that it can be used
|
||||
for joining during bootstrap and upgrades.
|
||||
|
||||
Additionally, a **PodDisruptionBudget** is configured so the Consul server
|
||||
cluster maintains quorum during voluntary operational events. The maximum
|
||||
unavailable is `(n/2)-1` where `n` is the number of server agents.
|
||||
|
||||
### Client Agents
|
||||
|
||||
The client agents are run as a **DaemonSet**. This places one agent
|
||||
(within its own pod) on each Kubernetes node.
|
||||
The clients expose the Consul HTTP API via a static port (default 8500)
|
||||
bound to the host port. This enables all other pods on the node to connect
|
||||
to the node-local agent using the host IP that can be retrieved via the
|
||||
Kubernetes downward API. See
|
||||
[accessing the Consul HTTP API](/docs/platform/k8s/run.html#accessing-the-consul-http-api)
|
||||
for an example.
|
||||
|
||||
There is a major limitation to this: there is no way to bind to a local-only
|
||||
host port. Therefore, any other node can connect to the agent. This should be
|
||||
considered for security. For a properly production-secured agent with TLS
|
||||
and ACLs, this is safe.
|
||||
|
||||
Some people prefer to run **Consul agent per pod** architectures, since this
|
||||
makes it easy to register the pod as a service easily. However, this turns
|
||||
a pod into a "node" in Consul and also causes an explosion of resource usage
|
||||
since every pod needs a Consul agent. We recommend instead running an
|
||||
agent (in a dedicated pod) per node, via the DaemonSet. This maintains the
|
||||
node equivalence in Consul. Service registration should be handled via the
|
||||
catalog syncing feature with Services rather than pods.
|
||||
|
||||
-> **Note:** Due to a limitation of anti-affinity rules with DaemonSets,
|
||||
a client-mode agent runs alongide server-mode agents in Kubernetes. This
|
||||
duplication wastes some resources, but otherwise functions perfectly fine.
|
|
@ -296,6 +296,21 @@
|
|||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-platform-k8s") %>>
|
||||
<a href="/docs/platform/k8s/index.html">Kubernetes</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-platform-k8s-run") %>>
|
||||
<a href="/docs/platform/k8s/run.html">Running Consul</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-platform-k8s-helm") %>>
|
||||
<a href="/docs/platform/k8s/helm.html">Helm Chart</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-platform-k8s-dns") %>>
|
||||
<a href="/docs/platform/k8s/dns.html">Consul DNS</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<hr>
|
||||
|
||||
<li<%= sidebar_current("docs-guides") %>>
|
||||
|
|
Loading…
Reference in New Issue