diff --git a/website/source/docs/platform/k8s/helm.html.md b/website/source/docs/platform/k8s/helm.html.md index 2ff14f83cc..82d2500865 100644 --- a/website/source/docs/platform/k8s/helm.html.md +++ b/website/source/docs/platform/k8s/helm.html.md @@ -16,25 +16,51 @@ 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. -* `global` - These global values affect multiple components of the chart. +* `global`- Holds values that affect + multiple components of the chart. - * `enabled` (`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 `server.enabled` to true. + * `enabled` (`boolean: true`) - The master enabled/disabled setting. If true, servers, clients, Consul DNS and the Consul UI will be enabled. Each component can override this default via its component-specific "enabled" config. If false, no components will be installed by default and per-component opt-in is required, such as by setting `server.enabled` to true. - * `domain` (`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 the cluster. This should be consistent throughout the chart, but can be overridden per-component as well. + * `domain` (`string: "consul"`) - The domain Consul will answer DNS queries for (see [-domain](/docs/agent/options.html#_domain)) and the domain services synced from Consul into Kubernetes will have, e.g. `service-name.service.consul`. - * `image` (`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. + * `image` (`string: "consul:"`) - The name (and tag) of the Consul Docker image for clients and servers. This can be overridden per component. This should be pinned to a specific version tag, otherwise you may inadvertently upgrade your Consul version. - * `imageK8S` (`string: "hashicorp/consul-k8s:latest"`) - The name of the Docker image (including any tag) for the [consul-k8s](https://github.com/hashicorp/consul-k8s) binary. This is used by components such as catalog sync. **This should be pinned to a specific version when running in production.** Otherwise, other changes to the chart may inadvertently upgrade the version. + Examples: - * `datacenter` (`string: "dc1"`) - The name of the datacenter that the agent cluster should register as. This may not be changed once the cluster is bootstrapped and running, since Consul doesn't yet support an automatic way to change this value. + ```yaml + # Consul 1.5.0 + image: "consul:1.5.0" + # Consul Enterprise 1.5.0 + image: "hashicorp/consul-enterprise:1.5.0-ent" + ``` - * `enablePodSecurityPolicies` (`boolean: false`) - - This flag controls whether [`PodSecurityPolicies`](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) are created - for the Consul components that this chart creates. + * `imageK8S` (`string: "hashicorp/consul-k8s:"`) - The name (and tag) of the [consul-k8s](https://github.com/hashicorp/consul-k8s) Docker image that is used for functionality such the catalog sync. This can be overridden per component. - * `bootstrapACLs` (`boolean: false`) - This flag controls - whether the Helm chart automatically enables ACLs within the Consul cluster. This requires both Consul servers and clients to be run within - Kubernetes. Requires Consul v1.5+ and consul-k8s v0.8.0+. + Note: support for the catalog sync's liveness and readiness probes was added to consul-k8s 0.6.0. If using an older consul-k8s version, you may need to remove these checks to make sync work. If using mesh gateways and bootstrapACLs then must be >= 0.9.0. + + * `datacenter` (`string: "dc1"`) - The name of the datacenter that the agents should register as. This can't be changed once the Consul cluster is up and running since Consul doesn't support an automatic way to change this value currently: [https://github.com/hashicorp/consul/issues/1858](https://github.com/hashicorp/consul/issues/1858). + + * `enablePodSecurityPolicies` (`boolean: false`) - + Controls whether pod security policies are created for the Consul components created by this chart. See [https://kubernetes.io/docs/concepts/policy/pod-security-policy/](https://kubernetes.io/docs/concepts/policy/pod-security-policy/). + + * `gossipEncryption` - + Configures which Kubernetes secret to retrieve Consul's gossip encryption key from (see [-encrypt](/docs/agent/options.html#_encrypt)). If secretName or secretKey are not set, gossip encryption will not be enabled. The secret must be in the same namespace that Consul is installed into. + + The secret can be created by running: + + ```bash + $ kubectl create secret generic consul-gossip-encryption-key --from-literal=key=$(consul keygen) + # To reference, use: + # gossipEncryption: + # secretName: consul-gossip-encryption-key + # secretKey: key + ``` + + * `secretName` (`string: ""`) - The name of the Kubernetes secret that holds the gossip encryption key. The secret must be in the same namespace that Consul is installed into. + + * `secretKey` (`string: ""`) - The key within the Kubernetes secret that holds the gossip encryption key. + +* `bootstrapACLs` (`boolean: false`) - Automatically create and assign ACL tokens within the Consul cluster. This requires servers to be running inside Kubernetes. Additionally requires Consul >= 1.4 and consul-k8s >= 0.8.0. * `server` - Values that configure running a Consul server within Kubernetes. @@ -148,7 +174,7 @@ and consider if they're appropriate for your deployment. * `join` (`array: null`) - A list of valid [`-retry-join` values](/docs/agent/options.html#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. - * `grpc` (`boolean: false`) - If true, agents will enable their GRPC listener on port 8502 and expose it to the host. This will use slightly more resources, but is required for [Connect](/docs/platform/k8s/connect.html). + * `grpc` (`boolean: true`) - If true, agents will enable their GRPC listener on port 8502 and expose it to the host. This will use slightly more resources, but is required for [Connect](/docs/platform/k8s/connect.html). * `resources` (`string: null`) - The resource requests (CPU, memory, etc.) for each of the client agents. This should be a multi-line string 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. diff --git a/website/source/docs/platform/k8s/index.html.md b/website/source/docs/platform/k8s/index.html.md index 21e4f0599f..003ca22991 100644 --- a/website/source/docs/platform/k8s/index.html.md +++ b/website/source/docs/platform/k8s/index.html.md @@ -10,7 +10,7 @@ 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. +Kubernetes, run Consul Connect Service Mesh, and more. This section documents the official integrations between Consul and Kubernetes. ## Use Cases @@ -26,19 +26,19 @@ 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) +**Consul Connect Service Mesh:** +Consul can automatically inject the [Consul 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. +**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 registered in Consul, and for external services +to use Consul service discovery to discover and connect to Kubernetes services. + **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. @@ -68,4 +68,4 @@ Guides Documentation - [Installing Consul](/docs/platform/k8s/run.html) covers how to install Consul using the Helm chart. - - [Helm Chart Reference](/docs/platform/k8s/run.html) describes the different options for configuring the Helm chart. + - [Helm Chart Reference](/docs/platform/k8s/helm.html) describes the different options for configuring the Helm chart. diff --git a/website/source/docs/platform/k8s/run.html.md b/website/source/docs/platform/k8s/run.html.md index c2b3ab04e3..8497c0f821 100644 --- a/website/source/docs/platform/k8s/run.html.md +++ b/website/source/docs/platform/k8s/run.html.md @@ -15,7 +15,10 @@ 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. If you would like to get hands-on experience testing Consul on Kubernetes, try the step-by-step beginner tutorial with an accompanying video in the [Minikube with Consul guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs) +down to the [architecture](/docs/platform/k8s/run.html#architecture) section. +If you would like to get hands-on experience testing Consul on Kubernetes, +try the step-by-step beginner tutorial with an accompanying video in the +[Minikube with Consul guide](https://learn.hashicorp.com/consul/getting-started-k8s/minikube?utm_source=consul.io&utm_medium=docs) ## Helm Chart Installation @@ -93,7 +96,7 @@ NAME: hashicorp -> If using Helm 2, run: `helm install --name hashicorp ./consul-helm` -_That's it._ The Helm chart does everything to setup a recommended +_That's it._ The Helm chart does everything to set up 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.