github.com/outbrain/consul@v1.4.5/website/source/docs/guides/kuberenetes-deployment.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Deploy Consul with Kubernetes" 4 sidebar_current: "docs-guides-kuberntes" 5 description: |- 6 Deploy Consul on Kubernetes with the official Helm chart. 7 --- 8 9 # Deploy Consul with Kubernetes 10 11 In this guide you will deploy a Consul datacenter with the official Helm chart. 12 You do not need to update any values in the Helm chart for a basic 13 installation. However, you can create a values file with parameters to allow 14 access to the Consul UI. 15 16 ~> **Security Warning** This guide is not for production use. By default, the 17 chart will install an insecure configuration of Consul. Please refer to the 18 [Kubernetes documentation](https://www.consul.io/docs/platform/k8s/index.html) 19 to determine how you can secure Consul on Kubernetes in production. 20 Additionally, it is highly recommended to use a properly secured Kubernetes 21 cluster or make sure that you understand and enable the recommended security 22 features. 23 24 To complete this guide successfully, you should have an existing Kubernetes 25 cluster, and locally configured [Helm](https://helm.sh/docs/using_helm/) and 26 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). If you do not have an 27 existing Kubernetes cluster you can use the [Minikube with Consul guide](https://www.consul.io/docs/guides/minikube.html) to get started 28 with Consul on Kubernetes. 29 30 ## Deploy Consul 31 32 You can deploy a complete Consul datacenter using the official Helm chart. By 33 default, the chart will install three Consul 34 servers and client on all Kubernetes nodes. You can review the 35 [Helm chart 36 values](https://www.consul.io/docs/platform/k8s/helm.html#configuration-values-) 37 to learn more about the default settings. 38 39 ### Download the Helm Chart 40 41 First, you will need to clone the official Helm chart from HashiCorp's Github 42 repo. 43 44 ```sh 45 $ git clone https://github.com/hashicorp/consul-helm.git 46 ``` 47 48 You do not need to update the Helm chart before deploying Consul, it comes with 49 reasonable defaults. Review the [Helm chart 50 documentation](https://www.consul.io/docs/platform/k8s/helm.html) to learn more 51 about the chart. 52 53 ### Helm Install Consul 54 55 To deploy Consul you will need to be in the same directory as the chart. 56 57 ```sh 58 $ cd consul-helm 59 ``` 60 61 Now, you can deploy Consul using `helm install`. This will deploy three servers 62 and agents on all Kubernetes nodes. The process should be quick, less than 5 63 minutes. 64 65 ```sh 66 $ helm install ./consul-helm 67 68 NAME: mollified-robin LAST DEPLOYED: Mon Feb 25 15:57:18 2019 NAMESPACE: default STATUS: DEPLOYED 69 NAME READY STATUS RESTARTS AGE 70 mollified-robin-consul-25r6z 0/1 ContainerCreating 0 0s 71 mollified-robin-consul-4p6hr 0/1 ContainerCreating 0 0s 72 mollified-robin-consul-n82j6 0/1 ContainerCreating 0 0s 73 mollified-robin-consul-server-0 0/1 Pending 0 0s 74 mollified-robin-consul-server-1 0/1 Pending 0 0s 75 mollified-robin-consul-server-2 0/1 Pending 0 0s 76 ``` 77 78 The output above has been reduced for readability. However, you can see that 79 there are three Consul servers and three Consul clients on this three node 80 Kubernetes cluster. 81 82 ## Access Consul UI 83 84 To access the UI you will need to update the `ui` values in the Helm chart. 85 Alternatively, if you do not wish to upgrade your cluster, you can set up [port 86 forwarding] 87 (https://www.consul.io/docs/platform/k8s/run.html#viewing-the-consul-ui) with 88 `kubectl`. 89 90 ### Create Values File 91 92 First, create a values file that can be passed on the command line when 93 upgrading. 94 95 ```yaml 96 # values.yaml 97 global: 98 datacenter: hashidc1 99 syncCatalog: 100 enabled: true 101 ui: 102 service: 103 type: "LoadBalancer" 104 server: 105 affinity: | 106 podAntiAffinity: 107 requiredDuringSchedulingIgnoredDuringExecution: 108 - labelSelector: 109 matchLabels: 110 app: {{ template "consul.name" . }} 111 release: "{{ .Release.Name }}" 112 component: server 113 topologyKey: kubernetes.io/hostname 114 ``` 115 116 This file renames your datacenter, enables catalog sync, sets up a load 117 balancer service for the UI, and enables [affinity](https://www.consul.io/docs/platform/k8s/helm.html#v-server-affinity) to allow only one 118 Consul pod per Kubernetes node. 119 The catalog sync parameters will allow you to see 120 the Kubernetes services in the Consul UI. 121 122 ### Initiate Rolling Upgrade 123 124 Finally, initiate the 125 [upgrade](https://www.consul.io/docs/platform/k8s/run.html#upgrading-consul-on-kubernetes) 126 with `helm upgrade` and the `-f` flag that passes in your new values file. This 127 processes should also be quick, less than a minute. 128 129 ```sh 130 $ helm upgrade consul -f values.yaml 131 ``` 132 133 You can now use `kubectl get services` to discover the external IP of your Consul UI. 134 135 ```sh 136 $ kubectl get services 137 NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE 138 consul ExternalName <none> consul.service.consul <none> 11d 139 kubernetes ClusterIP 122.16.14.1 <none> 443/TCP 137d 140 mollified-robin-consul-dns ClusterIP 122.16.14.25 <none> 53/TCP,53/UDP 13d 141 mollified-robin-consul-server ClusterIP None <none> 8500/TCP 13d 142 mollified-robin-consul-ui LoadBalancer 122.16.31.395 36.276.67.195 80:32718/TCP 13d 143 ``` 144 145 Additionally, you can use `kubectl get pods` to view the new catalog sync 146 process. The [catalog sync](https://www.consul.io/docs/platform/k8s/helm.html#v-synccatalog) process will sync 147 Consul and Kubernetes services bidirectionally by 148 default. 149 150 ``` 151 $ kubectl get pods 152 NAME READY STATUS RESTARTS AGE 153 mollified-robin-consul-d8mnp 1/1 Running 0 15d 154 mollified-robin-consul-p4m89 1/1 Running 0 15d 155 mollified-robin-consul-qclqc 1/1 Running 0 15d 156 mollified-robin-consul-server-0 1/1 Running 0 15d 157 mollified-robin-consul-server-1 1/1 Running 0 15d 158 mollified-robin-consul-server-2 1/1 Running 0 15d 159 mollified-robin-consul-sync-catalog-f75cd5846-wjfdk 1/1 Running 0 13d 160 ``` 161 162 The service should have `consul-ui` appended to the deployment name. Note, you 163 do not need to specify a port when accessing the dashboard. 164 165 ## Access Consul 166 167 In addition to accessing Consul with the UI, you can manage Consul with the 168 HTTP API or by directly connecting to the pod with `kubectl`. 169 170 ### Kubectl 171 172 To access the pod and data directory you can exec into the pod with `kubectl` to start a shell session. 173 174 ```sh 175 $ kubectl exec -it mollified-robin-consul-server-0 /bin/sh 176 ``` 177 178 This will allow you to navigate the file system and run Consul CLI commands on 179 the pod. For example you can view the Consul members. 180 181 ```sh 182 $ consul members 183 Node Address Status Type Build Protocol DC Segment 184 mollified-robin-consul-server-0 172.20.2.18:8301 alive server 1.4.2 2 hashidc1 <all> 185 mollified-robin-consul-server-1 172.20.0.21:8301 alive server 1.4.2 2 hashidc1 <all> 186 mollified-robin-consul-server-2 172.20.1.18:8301 alive server 1.4.2 2 hashidc1 <all> 187 gke-tier-2-cluster-default-pool-leri5 172.20.1.17:8301 alive client 1.4.2 2 hashidc1 <default> 188 gke-tier-2-cluster-default-pool-gnv4 172.20.2.17:8301 alive client 1.4.2 2 hashidc1 <default> 189 gke-tier-2-cluster-default-pool-zrr0 172.20.0.20:8301 alive client 1.4.2 2 hashidc1 <default> 190 ``` 191 192 ### Consul HTTP API 193 194 You can use the Consul HTTP API by communicating to the local agent running on 195 the Kubernetes node. You can read the 196 [documentation](https://www.consul.io/docs/platform/k8s/run.html#accessing-the-consul-http-api) 197 if you are interested in learning more about using the Consul HTTP API with Kubernetes. 198 199 ## Summary 200 201 In this guide, you deployed a Consul datacenter in Kubernetes using the 202 official Helm chart. You also configured access to the Consul UI. To learn more 203 about deploying applications that can use Consul's service discovery and 204 Connect, read the example in the [Minikube with Consul 205 guide](https://www.consul.io/docs/guides/minikube.html#step-2-deploy-custom-applications). 206