github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/pages/docs/guides/kuberenetes-deployment.mdx

203 lines
8.3 KiB
Markdown
Raw Blame History

---
layout: docs
page_title: Deploy Consul with Kubernetes
description: Deploy Consul on Kubernetes with the official Helm chart.
---
# Deploy Consul with Kubernetes
In this guide you will deploy a Consul datacenter with the official Helm chart.
You do not need to update any values in the Helm chart for a basic
installation. However, you can create a values file with parameters to allow
access to the Consul UI.
~> **Security Warning** This guide is not for production use. By default, the
chart will install an insecure configuration of Consul. Please refer to the
[Kubernetes documentation](https://www.consul.io/docs/platform/k8s)
to determine how you can secure Consul on Kubernetes in production.
Additionally, it is highly recommended to use a properly secured Kubernetes
cluster or make sure that you understand and enable the recommended security
features.
To complete this guide successfully, you should have an existing Kubernetes
cluster, and locally configured [Helm](https://helm.sh/docs/using_helm/) and
[kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). If you do not have an
existing Kubernetes cluster you can use the [Minikube with Consul guide](https://www.consul.io/docs/guides/minikube.html) to get started
with Consul on Kubernetes.
## Deploy Consul
You can deploy a complete Consul datacenter using the official Helm chart. By
default, the chart will install three Consul
servers and client on all Kubernetes nodes. You can review the
[Helm chart
values](https://www.consul.io/docs/platform/k8s/helm.html#configuration-values-)
to learn more about the default settings.
### Download the Helm Chart
First, you will need to clone the official Helm chart from HashiCorp's Github
repo.
```shell
$ git clone https://github.com/hashicorp/consul-helm.git
```
You do not need to update the Helm chart before deploying Consul, it comes with
reasonable defaults. Review the [Helm chart
documentation](https://www.consul.io/docs/platform/k8s/helm.html) to learn more
about the chart.
### Helm Install Consul
To deploy Consul you will need to be in the same directory as the chart.
```shell
$ cd consul-helm
```
Now, you can deploy Consul using `helm install`. This will deploy three servers
and agents on all Kubernetes nodes. The process should be quick, less than 5
minutes.
```shell
$ helm install ./consul-helm
NAME: mollified-robin LAST DEPLOYED: Mon Feb 25 15:57:18 2019 NAMESPACE: default STATUS: DEPLOYED
NAME READY STATUS RESTARTS AGE
mollified-robin-consul-25r6z 0/1 ContainerCreating 0 0s
mollified-robin-consul-4p6hr 0/1 ContainerCreating 0 0s
mollified-robin-consul-n82j6 0/1 ContainerCreating 0 0s
mollified-robin-consul-server-0 0/1 Pending 0 0s
mollified-robin-consul-server-1 0/1 Pending 0 0s
mollified-robin-consul-server-2 0/1 Pending 0 0s
```
The output above has been reduced for readability. However, you can see that
there are three Consul servers and three Consul clients on this three node
Kubernetes cluster.
## Access Consul UI
To access the UI you will need to update the `ui` values in the Helm chart.
Alternatively, if you do not wish to upgrade your cluster, you can set up [port
forwarding](https://www.consul.io/docs/platform/k8s/run.html#viewing-the-consul-ui) with
`kubectl`.
### Create Values File
First, create a values file that can be passed on the command line when
upgrading.
```yaml
# values.yaml
global:
datacenter: hashidc1
syncCatalog:
enabled: true
ui:
service:
type: 'LoadBalancer'
server:
affinity: |
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchLabels:
app: {{ template "consul.name" . }}
release: "{{ .Release.Name }}"
component: server
topologyKey: kubernetes.io/hostname
```
This file renames your datacenter, enables catalog sync, sets up a load
balancer service for the UI, and enables [affinity](https://www.consul.io/docs/platform/k8s/helm.html#v-server-affinity) to allow only one
Consul pod per Kubernetes node.
The catalog sync parameters will allow you to see
the Kubernetes services in the Consul UI.
### Initiate Rolling Upgrade
Finally, initiate the
[upgrade](https://www.consul.io/docs/platform/k8s/run.html#upgrading-consul-on-kubernetes)
with `helm upgrade` and the `-f` flag that passes in your new values file. This
processes should also be quick, less than a minute.
```shell
$ helm upgrade consul -f values.yaml
```
You can now use `kubectl get services` to discover the external IP of your Consul UI.
```shell
$ kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
consul ExternalName <none> consul.service.consul <none> 11d
kubernetes ClusterIP 122.16.14.1 <none> 443/TCP 137d
mollified-robin-consul-dns ClusterIP 122.16.14.25 <none> 53/TCP,53/UDP 13d
mollified-robin-consul-server ClusterIP None <none> 8500/TCP 13d
mollified-robin-consul-ui LoadBalancer 122.16.31.395 36.276.67.195 80:32718/TCP 13d
```
Additionally, you can use `kubectl get pods` to view the new catalog sync
process. The [catalog sync](https://www.consul.io/docs/platform/k8s/helm.html#v-synccatalog) process will sync
Consul and Kubernetes services bidirectionally by
default.
```
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
mollified-robin-consul-d8mnp 1/1 Running 0 15d
mollified-robin-consul-p4m89 1/1 Running 0 15d
mollified-robin-consul-qclqc 1/1 Running 0 15d
mollified-robin-consul-server-0 1/1 Running 0 15d
mollified-robin-consul-server-1 1/1 Running 0 15d
mollified-robin-consul-server-2 1/1 Running 0 15d
mollified-robin-consul-sync-catalog-f75cd5846-wjfdk 1/1 Running 0 13d
```
The service should have `consul-ui` appended to the deployment name. Note, you
do not need to specify a port when accessing the dashboard.
## Access Consul
In addition to accessing Consul with the UI, you can manage Consul with the
HTTP API or by directly connecting to the pod with `kubectl`.
### Kubectl
To access the pod and data directory you can exec into the pod with `kubectl` to start a shell session.
```shell
$ kubectl exec -it mollified-robin-consul-server-0 /bin/sh
```
This will allow you to navigate the file system and run Consul CLI commands on
the pod. For example you can view the Consul members.
```shell
$ consul members
Node Address Status Type Build Protocol DC Segment
mollified-robin-consul-server-0 172.20.2.18:8301 alive server 1.4.2 2 hashidc1 <all>
mollified-robin-consul-server-1 172.20.0.21:8301 alive server 1.4.2 2 hashidc1 <all>
mollified-robin-consul-server-2 172.20.1.18:8301 alive server 1.4.2 2 hashidc1 <all>
gke-tier-2-cluster-default-pool-leri5 172.20.1.17:8301 alive client 1.4.2 2 hashidc1 <default>
gke-tier-2-cluster-default-pool-gnv4 172.20.2.17:8301 alive client 1.4.2 2 hashidc1 <default>
gke-tier-2-cluster-default-pool-zrr0 172.20.0.20:8301 alive client 1.4.2 2 hashidc1 <default>
```
### Consul HTTP API
You can use the Consul HTTP API by communicating to the local agent running on
the Kubernetes node. You can read the
[documentation](https://www.consul.io/docs/platform/k8s/run.html#accessing-the-consul-http-api)
if you are interested in learning more about using the Consul HTTP API with Kubernetes.
## Summary
In this guide, you deployed a Consul datacenter in Kubernetes using the
official Helm chart. You also configured access to the Consul UI. To learn more
about deploying applications that can use Consul's service discovery and
Connect, read the example in the [Minikube with Consul
guide](https://www.consul.io/docs/guides/minikube.html#step-2-deploy-custom-applications).
Reference in New Issue View Git Blame Copy Permalink