consul/website/content/docs/k8s/installation/install.mdx

348 lines
14 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
layout: docs
page_title: Install Consul on Kubernetes from the Helm Chart
description: >-
This topic describes how to install Consul on Kubernetes using the official Consul Helm chart.
---
# Install Consul on Kubernetes from the Helm Chart
This topic describes how to install Consul on Kubernetes using the official Consul Helm chart. For instruction on how to install Consul on Kubernetes using the Consul K8s CLI, refer to [Installing the Consul K8s CLI](/docs/k8s/installation/install-cli).
## Introduction
We recommend using the Consul Helm chart to install Consul on Kubernetes for multi-cluster installations that involve cross-partition or cross datacenter communication. The Helm chart installs and configures all necessary components to run Consul. The configuration enables you to run a server cluster, a client cluster, or both.
Consul can run directly on Kubernetes in server or client mode so that you can leverage Consul functionality if your workloads are fully deployed to Kubernetes. For heterogeneous workloads, Consul agents can join a server running inside or outside of Kubernetes. Refer to the [architecture section](/docs/k8s/architecture) to learn more about the general architecture of Consul on Kubernetes.
The Helm chart exposes several useful configurations and automatically sets up complex resources, but it does not automatically operate Consul. You must still become familiar with how to monitor, backup, and upgrade the Consul cluster.
The Helm chart has no required configuration, so it installs a Consul cluster with default configurations. We strongly recommend that you [learn about the configuration options](/docs/k8s/helm#configuration-values) prior to going to production.
-> **Security warning**: By default, Helm installs Consul with security configurations disabled so that the out-of-box experience is optimized for new users. We strongly recommend using a properly-secured Kubernetes cluster or making sure that you understand and enable [Consuls security features](/docs/security) before going into production. Some security features are not supported in the Helm chart and require additional manual configuration.
Refer to the [architecture](/docs/k8s/installation/install#architecture) section to learn more about the general architecture of Consul on Kubernetes.
For a hands-on experience with Consul as a service mesh
for Kubernetes, follow the [Getting Started with Consul service
mesh](https://learn.hashicorp.com/tutorials/consul/service-mesh-deploy?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
## Requirements
- Helm version 3.2+. Visit the [Helm website](https://helm.sh/docs/intro/install/) to download the latest version.
## Install Consul
1. Add the HashiCorp Helm Repository:
```shell-session
$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories
```
1. Verify that you have access to the consul chart:
```shell-session
$ helm search repo hashicorp/consul
NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/consul 0.39.0 1.11.1 Official HashiCorp Consul Chart
```
1. Prior to installing via Helm, ensure that the `consul` Kubernetes namespace does not exist, as installing on a dedicated namespace
is recommended.
```shell-session
$ kubectl get namespace
NAME STATUS AGE
default Active 18h
kube-node-lease Active 18h
kube-public Active 18h
kube-system Active 18h
```
1. Install Consul on Kubernetes using Helm. The Helm chart does everything to set up a recommended Consul-on-Kubernetes deployment. After installation, a Consul cluster will be formed, a leader will be elected, and every node will have a running Consul agent.
1. To install the latest version of Consul on Kubernetes, issue the following command to install Consul with the default configuration using Helm. You could also install Consul on a dedicated namespace of your choosing by modifying the value of the `-n` flag for the Helm install.
```shell-session
$ helm install consul hashicorp/consul --set global.name=consul --create-namespace --namespace consul
```
1. To install a specific version of Consul on Kubernetes, issue the following command with `--version` flag to install the specified version with the default configuration using Helm.
```shell-session
$ export VERSION=0.43.0
$ helm install consul hashicorp/consul --set global.name=consul --version ${VERSION} --create-namespace --namespace consul
```
## Custom installation
If you want to customize your installation,
create a `config.yaml` file to override the default settings.
You can learn what settings are available by running `helm inspect values hashicorp/consul`
or by reading the [Helm Chart Reference](/docs/k8s/helm).
### Minimal `config.yaml` for Consul service mesh
The minimal settings to enable [Consul Service Mesh]((/docs/k8s/connect)) would be captured in the following `config.yaml` config file:
<CodeBlockConfig filename="config.yaml">
```yaml
global:
name: consul
connectInject:
enabled: true
controller:
enabled: true
```
</CodeBlockConfig>
Once you've created your `config.yaml` file, run `helm install` with the `--values` flag:
```shell-session
$ helm install consul hashicorp/consul --create-namespace --namespace consul --values config.yaml
NAME: consul
...
```
### Enable the Consul CNI plugin
By default, Consul generates a `connect-inject init` container as part of the Kubernetes pod startup process when Consul is in [transparent proxy mode](/docs/connect/transparent-proxy). The container configures traffic redirection in the service mesh through the sidecar proxy. To configure redirection, the container requires elevated `CAP_NET_ADMIN` privileges, which may not be compatible with security policies in your organization.
Instead, you can enable the Consul container network interface (CNI) plugin to perform traffic redirection. Because the plugin is executed by the Kubernetes kubelet, the plugin already has the elevated privileges necessary to configure the network.
Add the following configuration to your `config.yaml` file to enable the Consul CNI plugin:
<CodeTabs tabs={[ "Reference configuration","GKE configuration" ]}>
<CodeBlockConfig filename="config.yaml">
```yaml
global:
name: consul
connectInject:
enabled: true
cni:
enabled: true
logLevel: info
cniBinDir: "/opt/cni/bin"
cniNetDir: "/etc/cni/net.d"
```
</CodeBlockConfig>
<CodeBlockConfig filename="config.yaml">
```yaml
global:
name: consul
connectInject:
enabled: true
cni:
enabled: true
logLevel: info
cniBinDir: "/home/kubernetes/bin"
cniNetDir: "/etc/cni/net.d"
```
</CodeBlockConfig>
</CodeTabs>
The following table describes the available CNI plugin options:
| Option | Description | Default |
| --- | --- | --- |
| `cni.enabled` | Boolean value that enables or disables the CNI plugin. If `true`, the plugin is responsible for redirecting traffic in the service mesh. If `false`, redirection is handled by the `connect-inject init` container. | `false` |
| `cni.logLevel` | String value that specifies the log level for the installer and plugin. You can specify the following values: `info`, `debug`, `error`. | `info` |
| `cni.cniBinDir` | String value that specifies the location on the Kubernetes node where the CNI plugin is installed. | `/opt/cni/bin` |
| `cni.cniNetDir` | String value that specifies the location on the Kubernetes node for storing the CNI configuration. | `/etc/cni/net.d` |
### Enable Consul service mesh on select namespaces
By default, Consul Service Mesh is enabled on almost all namespaces (with the exception of `kube-system` and `local-path-storage`) within a Kubernetes cluster. You can restrict this to a subset of namespaces by specifying a `namespaceSelector` that matches a label attached to each namespace denoting whether to enable Consul service mesh. In order to default to enabling service mesh on select namespaces by label, the `connectInject.default` value must be set to `true`.
<CodeBlockConfig filename="config.yaml">
```yaml
global:
name: consul
connectInject:
enabled: true
default: true
namespaceSelector: |
matchLabels:
connect-inject : enabled
controller:
enabled: true
```
</CodeBlockConfig>
Label the namespace(s), where you would like to enable Consul Service Mesh.
```shell-session
$ kubectl create ns foo
$ kubectl label namespace foo connect-inject=enabled
```
Next, run `helm install` with the `--values` flag:
```shell-session
$ helm install consul hashicorp/consul --create-namespace --namespace consul --values config.yaml
NAME: consul
...
```
### Update your Consul on Kubernetes configuration
If you've already installed Consul and want to make changes, you'll need to run
`helm upgrade`. See [Upgrading](/docs/k8s/upgrade) for more details.
## Usage
You can view the Consul UI and access the Consul HTTP API after installation.
### 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 `LoadBalancer` Service by default so you must
use `kubectl port-forward` to visit the UI.
#### TLS Disabled
If running with TLS disabled, the Consul UI will be accessible via http on port 8500:
```shell-session
$ kubectl port-forward service/consul-server --namespace consul 8500:8500
...
```
Once the port is forwarded navigate to [http://localhost:8500](http://localhost:8500).
#### TLS Enabled
If running with TLS enabled, the Consul UI will be accessible via https on port 8501:
```shell-session
$ kubectl port-forward service/consul-server --namespace consul 8501:8501
...
```
Once the port is forwarded navigate to [https://localhost:8501](https://localhost:8501).
~> You'll need to click through an SSL warning from your browser because the
Consul certificate authority is self-signed and not in the browser's trust store.
#### ACLs Enabled
If ACLs are enabled, you will need to input an ACL token into the UI in order
to see all resources and make modifications.
To retrieve the bootstrap token that has full permissions, run:
```shell-session
$ kubectl get secrets/consul-bootstrap-acl-token --template='{{.data.token | base64decode }}'
e7924dd1-dc3f-f644-da54-81a73ba0a178%
```
Then paste the token into the UI under the ACLs tab (without the `%`).
~> NOTE: If using multi-cluster federation, your kubectl context must be in the primary datacenter
to retrieve the bootstrap token since secondary datacenters use a separate token
with less permissions.
#### Exposing the UI via a service
If you want to expose the UI via a Kubernetes Service, configure
the [`ui.service` chart values](/docs/k8s/helm#v-ui-service).
This service will allow requests to the Consul servers so it should
not be open to the world.
### 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-docs/agent).
For Consul installed via the Helm chart, a client agent is installed on
each Kubernetes node. This is explained in the [architecture](/docs/k8s/installation/install#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. In addition to pods, anything
with a pod template can also access the downward API and can therefore also
access Consul: StatefulSets, Deployments, Jobs, etc.
```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
```
An example `Deployment` is also shown below to show how the host IP can
be accessed from nested pod specifications:
<CodeBlockConfig highlight="18-28">
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: consul-example-deployment
spec:
replicas: 1
selector:
matchLabels:
app: consul-example
template:
metadata:
labels:
app: 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
```
</CodeBlockConfig>
## Next Steps
If you are still considering a move to Kubernetes, or to Consul on Kubernetes specifically, our [Migrate to Microservices with Consul Service Mesh on Kubernetes](https://learn.hashicorp.com/collections/consul/microservices?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
collection uses an example application written by a fictional company to illustrate why and how organizations can
migrate from monolith to microservices using Consul service mesh on Kubernetes. The case study in this collection
should provide information valuable for understanding how to develop services that leverage Consul during any stage
of your microservices journey.