1--- 2layout: "docs" 3page_title: "Helm - Kubernetes" 4sidebar_current: "docs-platform-k8s-helm" 5description: |- 6 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. 7--- 8 9# Helm Chart 10 11The [Consul Helm chart](https://github.com/hashicorp/consul-helm) 12is the recommended way to install and configure Consul on Kubernetes. 13In addition to running Consul itself, the Helm chart is the primary 14method for installing and configuring Consul integrations with 15Kubernetes such as catalog syncing, Connect injection, and more. 16 17This page assumes general knowledge of [Helm](https://helm.sh/) and 18how to use it. Using Helm to install Consul will require that Helm is 19properly installed and configured with your Kubernetes cluster. 20 21-> **Important:** The Helm chart is new and 22may still change significantly over time. Please always run Helm with 23`--dry-run` before any install or upgrade to verify changes. 24 25## Using the Helm Chart 26 27To use the Helm chart, you must download or clone the 28[consul-helm GitHub repository](https://github.com/hashicorp/consul-helm) 29and run Helm against the directory. We plan to transition to using a real 30Helm repository soon. When running Helm, we highly recommend you always 31checkout a specific tagged release of the chart to avoid any 32instabilities from master. 33 34Prior to this, you must have Helm installed and configured both in your 35Kubernetes cluster and locally on your machine. The steps to do this are 36out of the scope of this document, please read the 37[Helm documentation](https://helm.sh/) for more information. 38 39Example chart usage: 40 41```sh 42# Clone the chart repo 43$ git clone https://github.com/hashicorp/consul-helm.git 44$ cd consul-helm 45 46# Checkout a tagged version 47$ git checkout v0.1.0 48 49# Run Helm 50$ helm install --dry-run ./ 51``` 52 53~> **Warning:** By default, the chart will install _everything_: a 54Consul server cluster, client agents on all nodes, feature components, etc. 55This provides a nice out-of-box experience for new users, but may not be 56appropriate for a production setup. Considering setting the `global.enabled` 57value to `false` and opt-in to the various components. 58 59## Configuration (Values) 60 61The chart is highly customizable using 62[Helm configuration values](https://docs.helm.sh/using_helm/#customizing-the-chart-before-installing). 63Each value has a sane default tuned for an optimal getting started experience 64with Consul. Before going into production, please review the parameters below 65and consider if they're appropriate for your deployment. 66 67* <a name="v-global" href="#v-global">`global`</a> - These values are global values that affect multiple components of the chart. 68 69 - <a name="v-global-enabled" href="#v-global-enabled">`enabled`</a> (`boolean: true`) - 70 The master enabled/disabled configuration. If this is true, most components 71 will be installed by default. If this is false, no components will be installed 72 by default and manually opt-in is required, such as by setting 73 <a href="#v-">`server.enabled`</a> to true. 74 75 76 - <a name="v-global-domain" href="#v-global-domain">`domain`</a> (`string: "consul"`) - 77 The domain Consul uses for DNS queries. This is used to configure agents both 78 for DNS listening but also to know what domain to join to join the cluster. 79 This should be consistent throughout the chart, but can be overridden 80 per-component as well. 81 82 - <a name="v-global-image" href="#v-global-image">`image`</a> (`string: "consul:latest"`) - 83 The name of the Docker image (including any tag) for the containers running 84 Consul agents. **This should be pinned to a specific version when running 85 in production.** Otherwise, other changes to the chart may inadvertently 86 upgrade your Consul version. 87 88 - <a name="v-global-imagek8s" href="#v-global-imagek8s">`imageK8S`</a> (`string: "hashicorp/consul-k8s:latest"`) - 89 The name of the Docker image (including any tag) for the 90 [consul-k8s](https://github.com/hashicorp/consul-k8s) binary. This is 91 used by components such as catalog sync. **This should be pinned to a specific 92 version when running in production.** Otherwise, other changes to the chart may 93 inadvertently upgrade the version. 94 95 - <a name="v-global-datacenter" href="#v-global-datacenter">`datacenter`</a> (`string: "dc1"`) - 96 The name of the datacenter that the agent cluster should register as. 97 This must not be changed once the cluster is bootstrapped and running, 98 since Consul doesn't yet support an automatic way to change this value. 99 100 101* <a name="v-server" href="#v-server">`server`</a> - Values that configure 102 running a Consul server cluster within Kubernetes. 103 104 - <a name="v-server-enabled" href="#v-server-enabled">`enabled`</a> (`boolean: global.enabled`) - 105 If true, the chart will install all the resources necessary for a Consul 106 server cluster. If you're running Consul externally and want agents within 107 Kubernetes to join that cluster, this should probably be false. 108 109 - <a name="v-server-image" href="#v-server-image">`image`</a> (`string: global.image`) - 110 The name of the Docker image (including any tag) for the containers running 111 Consul server agents. 112 113 - <a name="v-server-replicas" href="#v-server-replicas">`replicas`</a> (`integer: 3`) - 114 The number of server agents to run. This determines the fault tolerance 115 of the cluster. Please see the [deployment table](/docs/internals/consensus.html#deployment-table) 116 for more information. 117 118 - <a name="v-server-bootstrapexpect" href="#v-server-bootstrapexpect">`bootstrapExpect`</a> (`integer: 3`) - 119 For new clusters, this is the number of servers to wait for before 120 performing the initial leader election and bootstrap of the cluster. This 121 must be less than or equal to `server.replicas`. This value is only 122 used when bootstrapping new clusters, it has no effect during ongoing cluster 123 maintenance. 124 125 - <a name="v-server-connect" href="#v-server-connect">`connect`</a> (`boolean: true`) - 126 This will enable/disable [Connect](/docs/connect/index.html). Setting this 127 to true _will not_ automatically secure pod communication, this setting will 128 only enable usage of the feature. Consul will automatically initialize a new 129 CA and set of certificates. Additional Connect settings can be configured 130 by setting the `server.extraConfig` value. 131 132 - <a name="v-server-disruptionbudget" href="#v-server-disruptionbudget">`disruptionBudget`</a> - 133 This configures the 134 [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) 135 for the server cluster. 136 137 * <a name="v-server-disruptionbudget-enabled" href="#v-server-disruptionbudget-enabled">`enabled`</a> (`boolean: true`) - 138 This will enable/disable registering a PodDisruptionBudget for 139 the server cluster. If this is enabled, it will only register the 140 budget so long as the server cluster is enabled. 141 142 * <a name="v-server-disruptionbudget-maxunavailable" href="#v-server-disruptionbudget-maxunavailable">`maxUnavailable`</a> (`integer: null`) - 143 The maximum number of unavailable pods. By default, this will be automatically 144 computed based on the `server.replicas` value to be `(n/2)-1`. 145 146 - <a name="v-server-extraconfig" href="#v-server-extraconfig">`extraConfig`</a> (`string: "{}"`) - 147 A raw string of extra JSON or HCL configuration for Consul servers. This 148 will be saved as-is into a ConfigMap that is read by the Consul server agents. 149 This can be used to add additional configuration that isn't directly exposed 150 by the chart. 151 152 - <a name="v-server-extravolumes" href="#v-server-extravolumes">`extraVolumes`</a> (`array: []`) - 153 A list of extra volumes to mount for server agents. This is useful for bringing 154 in extra data that can be referenced by other configurations at a well known 155 path, such as TLS certificates or Gossip encryption keys. 156 The value of this should be a list of objects. Each object has the following 157 supports the following keys: 158 159 * <a name="v-server-extravolumes-type" href="#v-server-extravolumes-type">`type`</a> (`string: required`) - 160 Type of the volume, must be one of "configMap" or "secret". Case sensitive. 161 162 * <a name="v-server-extravolumes-name" href="#v-server-extravolumes-name">`name`</a> (`string: required`) - 163 Name of the configMap or secret to be mounted. This also controls the path 164 that it is mounted to. The volume will be mounted to `/config/userconfig/<name>`. 165 166 * <a name="v-server-extravolumes-load" href="#v-server-extravolumes-load">`load`</a> (`boolean: false`) - 167 If true, then the agent will be configured to automatically load HCL/JSON 168 configuration files from this volume with `-config-dir`. This defaults 169 to false. 170 171 - <a name="v-server-resources" href="#v-server-resources">`resources`</a> (`object: {}`) - 172 The resource requests (CPU, memory, etc.) for each of the server agents. 173 This should be an object mapping directly to a Kubernetes 174 [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#resourcerequirements-v1-core) object. If this isn't specified, then the pods 175 won't request any specific amount of resources. **Setting this is highly 176 recommended.** 177 178 - <a name="v-server-storage" href="#v-server-storage">`storage`</a> (`string: "10Gi"`) - 179 The amount of storage to request for the persistant volume backing the 180 Consul server data. 181 182 - <a name="v-server-updatepartition" href="#v-server-updatepartition">`updatePartition`</a> (`integer: 0`) - 183 This value is used to carefully control a rolling update of Consul server 184 agents. This value specifies the 185 [partition](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#partitions) 186 for performing a rolling update. Please read the linked Kubernetes 187 documentation for more information. 188 189* <a name="v-client" href="#v-client">`client`</a> - Values that configure 190 running a Consul client agent on Kubernetes nodes. 191 192 - <a name="v-client-enabled" href="#v-client-enabled">`enabled`</a> (`boolean: global.enabled`) - 193 If true, the chart will install all the resources necessary for a Consul 194 client on every Kubernetes node. This _does not_ require `server.enabled`, 195 since the agents can be configured to join an external cluster. 196 197 - <a name="v-client-image" href="#v-client-image">`image`</a> (`string: global.image`) - 198 The name of the Docker image (including any tag) for the containers running 199 Consul client agents. 200 201 - <a name="v-client-grpc" href="#v-client-grpc">`grpc`</a> (`boolean: false`) - 202 If true, agents will enable their GRPC listener on port 8502 and expose 203 it to the host. This will use slightly more resources, but is required for 204 [Connect](/docs/platform/k8s/connect.html). 205 206 - <a name="v-client-extraconfig" href="#v-client-extraconfig">`extraConfig`</a> (`string: "{}"`) - 207 A raw string of extra JSON or HCL configuration for Consul clients. This 208 will be saved as-is into a ConfigMap that is read by the Consul agents. 209 This can be used to add additional configuration that isn't directly exposed 210 by the chart. 211 212 - <a name="v-client-extravolumes" href="#v-client-extravolumes">`extraVolumes`</a> (`array: []`) - 213 A list of extra volumes to mount for client agents. This is useful for bringing 214 in extra data that can be referenced by other configurations at a well known 215 path, such as TLS certificates or Gossip encryption keys. 216 The value of this should be a list of objects. Each object has the following 217 supports the following keys: 218 219 * <a name="v-client-extravolumes-type" href="#v-client-extravolumes-type">`type`</a> (`string: required`) - 220 Type of the volume, must be one of "configMap" or "secret". Case sensitive. 221 222 * <a name="v-client-extravolumes-name" href="#v-client-extravolumes-name">`name`</a> (`string: required`) - 223 Name of the configMap or secret to be mounted. This also controls the path 224 that it is mounted to. The volume will be mounted to `/config/userconfig/<name>`. 225 226 * <a name="v-client-extravolumes-load" href="#v-client-extravolumes-load">`load`</a> (`boolean: false`) - 227 If true, then the agent will be configured to automatically load HCL/JSON 228 configuration files from this volume with `-config-dir`. This defaults 229 to false. 230 231 - <a name="v-client-join" href="#v-client-join">`join`</a> (`array<string>: null`) - 232 A list of values to specify to `-retry-join`. If this is `null` (default), 233 then the clients will attempt to automatically join the server cluster 234 running within Kubernetes. This means that with `server.enabled` set to true, 235 clients will automatically join that cluster. If `server.enabled` is not 236 true, then a value must be specified so the clients can join a valid cluster. 237 238 - <a name="v-client-resources" href="#v-client-resources">`resources`</a> (`object: {}`) - 239 The resource requests (CPU, memory, etc.) for each of the client agents. 240 This should be an object mapping directly to a Kubernetes 241 [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#resourcerequirements-v1-core) object. If this isn't specified, then the pods 242 won't request any specific amount of resources. 243 244* <a name="v-dns" href="#v-dns">`dns`</a> - Values that configure the Consul DNS service. 245 246 - <a name="v-dns-enabled" href="#v-dns-enabled">`enabled`</a> (`boolean: global.enabled`) - 247 If true, a `consul-dns` service will be created that exposes port 53 for 248 TCP and UDP to the running Consul agents (servers and clients). This can 249 then be used to [configure kube-dns](/docs/platform/k8s/dns.html). The Helm 250 chart _does not_ automatically configure kube-dns. 251 252* <a name="v-synccatalog" href="#v-synccatalog">`syncCatalog`</a> - Values that 253 configure running the [service sync](/docs/platform/k8s/service-sync.html) 254 process. 255 256 - <a name="v-synccatalog-enabled" href="#v-synccatalog-enabled">`enabled`</a> (`boolean: false`) - 257 If true, the chart will install all the resources necessary for the 258 catalog sync process to run. 259 260 - <a name="v-synccatalog-image" href="#v-synccatalog-image">`image`</a> (`string: global.imageK8S`) - 261 The name of the Docker image (including any tag) for 262 [consul-k8s](/docs/platform/k8s/index.html#quot-consul-k8s-quot-project) 263 to run the sync program. 264 265 - <a name="v-synccatalog-k8sprefix" href="#v-synccatalog-k8sprefix">`k8sPrefix`</a> (`string: ""`) - 266 A prefix to prepend to all services registered in Kubernetes from Consul. 267 This defaults to `""` where no prefix is prepended; Consul services are 268 synced with the same name to Kubernetes. 269 270 - <a name="v-synccatalog-toconsul" href="#v-synccatalog-toconsul">`toConsul`</a> (`boolean: true`) - 271 If true, will sync Kubernetes services to Consul. This can be disabled to 272 have a one-way sync. 273 274 - <a name="v-synccatalog-tok8s" href="#v-synccatalog-tok8s">`toK8S`</a> (`boolean: true`) - 275 If true, will sync Consul services to Kubernetes. This can be disabled to 276 have a one-way sync. 277 278* <a name="v-ui" href="#v-ui">`ui`</a> - Values that configure the Consul UI. 279 280 - <a name="v-ui-enabled" href="#v-ui-enabled">`enabled`</a> (`boolean: global.enabled`) - 281 If true, the UI will be enabled. This will only _enable_ the UI, it doesn't 282 automatically register any service for external access. The UI will only 283 be enabled on server agents. If `server.enabled` is false, then this setting 284 has no effect. To expose the UI in some way, you must configure 285 `ui.service`. 286 287 - <a name="v-ui-service" href="#v-ui-service">`service`</a> - 288 This configures the `Service` resource registered for the Consul UI. 289 290 * <a name="v-ui-service-enabled" href="#v-ui-service-enabled">`enabled`</a> (`boolean: true`) - 291 This will enable/disable registering a Kubernetes Service for the Consul UI. 292 This value only takes effect if `ui.enabled` is true and taking effect. 293 294 * <a name="v-ui-service-type" href="#v-ui-service-type">`type`</a> (`string: null`) - 295 The service type to register. This defaults to `null` which doesn't set 296 an explicit service type, which typically is defaulted to "ClusterIP" 297 by Kubernetes. The available service types are documented on 298 [the Kubernetes website](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). 299 300* <a name="v-connectinject" href="#v-connectinject">`connectInject`</a> - Values that 301 configure running the [Connect injector](/docs/platform/k8s/connect.html). 302 303 - <a name="v-connectinject-enabled" href="#v-connectinject-enabled">`enabled`</a> (`boolean: false`) - 304 If true, the chart will install all the resources necessary for the 305 Connect injector process to run. This will enable the injector but will 306 require pods to opt-in with an annotation by default. 307 308 - <a name="v-connectinject-imageConsul" href="#v-connectinject-imageConsul">`imageConsul`</a> (`string: global.image`) - 309 The name of the Docker image (including any tag) for Consul. This is used 310 for proxy service registration, Envoy configuration, etc. 311 312 - <a name="v-connectinject-imageEnvoy" href="#v-connectinject-imageEnvoy">`imageEnvoy`</a> (`string: ""`) - 313 The name of the Docker image (including any tag) for the Envoy sidecar. 314 `envoy` must be on the executable path within this image. This Envoy 315 version must be compatible with the Consul version used by the injector. 316 This defaults to letting the injector choose the Envoy image, which is 317 usually `envoy/envoy-alpine`. 318 319 - <a name="v-connectinject-default" href="#v-connectinject-default">`default`</a> (`boolean: false`) - 320 If true, the injector will inject the Connect sidecar into all pods by 321 default. Otherwise, pods must specify the 322 [injection annotation](/docs/platform/k8s/connect.html#consul-hashicorp-com-connect-inject) 323 to opt-in to Connect injection. If this is true, pods can use the same 324 annotation to explicitly opt-out of injection. 325 326 - <a name="v-connectinject-namespaceselector" href="#v-connectinject-namespaceselector">`namespaceSelector`</a> (`string: ""`) - 327 A [selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) 328 for restricting injection to only matching namespaces. By default 329 all namespaces except the system namespace will have injection enabled. 330 331 - <a name="v-connectinject-certs" href="#v-connectinject-certs">`certs`</a> - 332 The certs section configures how the webhook TLS certs are configured. 333 These are the TLS certs for the Kube apiserver communicating to the 334 webhook. By default, the injector will generate and manage its own certs, 335 but this requires the ability for the injector to update its own 336 `MutatingWebhookConfiguration`. In a production environment, custom certs 337 should probably be used. Configure the values below to enable this. 338 339 * <a name="v-connectinject-certs-secretname" href="#v-connectinject-certs-secretname">`secretName`</a> (`string: null`) - 340 secretName is the name of the Kubernetes secret that has the TLS certificate and 341 private key to serve the injector webhook. If this is null, then the 342 injector will default to its automatic management mode. 343 344 * <a name="v-connectinject-cabundle" href="#v-connectinject-cabundle">`caBundle`</a> (`string: ""`) - 345 The PEM-encoded CA public certificate bundle for the TLS certificate served by the 346 injector. This must be specified as a string and can't come from a 347 secret because it must be statically configured on the Kubernetes 348 `MutatingAdmissionWebhook` resource. This only needs to be specified 349 if `secretName` is not null. 350 351 * <a name="v-connectinject-certs-certname" href="#v-connectinject-certs-certname">`certName`</a> (`string: "tls.crt"`) - 352 The name of the certificate file within the `secretName` secret. 353 354 * <a name="v-connectinject-certs-keynamkeyname" href="#v-connectinject-certs-keyname">`keyName`</a> (`string: "tls.key"`) - 355 The name of the private key for the certificate file within the 356 `secretName` secret. 357