From 80031e792192cd3f2a87c1bd6c73fde05cf96837 Mon Sep 17 00:00:00 2001 From: Luke Kysow <1034429+lkysow@users.noreply.github.com> Date: Wed, 20 May 2020 13:43:06 -0700 Subject: [PATCH] Helm docs for k8s mesh gateways and federation --- website/pages/docs/k8s/helm.mdx | 148 +++++++++++++++++++++++++++++++- 1 file changed, 146 insertions(+), 2 deletions(-) diff --git a/website/pages/docs/k8s/helm.mdx b/website/pages/docs/k8s/helm.mdx index 7468135ef..6268dc11f 100644 --- a/website/pages/docs/k8s/helm.mdx +++ b/website/pages/docs/k8s/helm.mdx @@ -41,7 +41,7 @@ and consider if they're appropriate for your deployment. - `imageK8S` ((#v-global-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. - 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. + 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 global.acls.manageSystemACLs then must be >= 0.9.0. - `datacenter` ((#v-global-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 @@ -95,6 +95,41 @@ and consider if they're appropriate for your deployment. - `secretKey` ((#v-global-acls-bootstraptoken-secretkey)) (`string: null`) - The key of the Kubernetes secret. + - `createReplicationToken` ((#v-global-acls-createreplicationtoken)) (`boolean: false`) - If true, an ACL token will be created that can be used in secondary + datacenters for replication. This should only be set to true in the + primary datacenter since the replication token must be created from that + datacenter. + In secondary datacenters, the secret needs to be imported from the primary + datacenter and referenced via `global.acls.replicationToken`. + Requires consul-k8s >= 0.13.0. + + - `replicationToken` ((#v-global-acls-replicationtoken)) - replicationToken references a secret containing the replication ACL token. + This token will be used by secondary datacenters to perform ACL replication + and create ACL tokens and policies. + This value is ignored if `bootstrapToken` is also set. + Requires consul-k8s >= 0.13.0. + + - `secretName` ((#v-global-acls-replicationtoken-secretname)) (`string: null`) - The name of the Kubernetes secret. + + - `secretKey` ((#v-global-acls-replicationtoken-secretkey)) (`string: null`) - The key of the Kubernetes secret. + + - `federation` ((#v-global-federation)) - Configure federation. + + - `enabled` ((#v-global-federation-enabled)) (`boolean: false`) - **Experimental: Currently this is only available in Consul 1.8.0.** + If enabled, this datacenter will be federation-capable. Only federation + via mesh gateways is supported. + Mesh gateways and servers will be configured to allow federation. + Requires `global.tls.enabled`, `meshGateway.enabled` and `connectInject.enabled` + to be true. + + - `createFederationSecret` ((#v-global-federation-createfederationsecret)) (`boolean: false`) - If true, the chart will create a Kubernetes secret that can be imported + into secondary datacenters so they can federate with this datacenter. The + secret contains all the information secondary datacenters need to contact + and authenticate with this datacenter. This should only be set to true + in your primary datacenter. The secret name is + `-federation` (if setting `global.name`), otherwise + `-consul-federation`. Requires consul-k8s 0.15.0+. + - `tls` ((#v-global-tls)) - Enables TLS [encryption](https://learn.hashicorp.com/consul/security-networking/agent-encryption) across the cluster to verify authenticity of the Consul servers and clients. Requires Consul v1.4.1+ and consul-k8s v0.16.2+ - `enabled` ((#v-global-tls-enabled)) (`boolean: false`) - If true, the Helm chart will enable TLS for Consul @@ -730,9 +765,118 @@ and consider if they're appropriate for your deployment. } ``` +- `meshGateway` ((#v-meshgateway)) - Configure mesh gateways. + + - `enabled` ((#v-meshgateway-enabled)) (`boolean: true`) - If mesh gateways are enabled, a Deployment will be created that runs + gateways and Consul Connect will be configured to use gateways. + See [mesh gateway docs](https://www.consul.io/docs/connect/mesh_gateway.html). + Requirements: Consul 1.6.0+ and consul-k8s 0.15.0+ if using + `global.acls.manageSystemACLs`. + + - `globalMode` ((#v-meshgateway-globalmode)) (`string: "local"`) - Globally configure which mode the gateway should run in. + Can be set to either `"remote"`, `"local"`, `"none"` or `""` or `null`. + See [mesh gateway modes of operation](https://consul.io/docs/connect/mesh_gateway.html#modes-of-operation) for + a description of each mode. + If set to anything other than `""` or `null`, `connectInject.centralConfig.enabled` + should be set to true so that the global config will actually be used. + If set to the empty string, no global default will be set and the gateway mode + will need to be set individually for each service. + + - `replicas` ((#v-meshgateway-replicas)) (`int: 2`) - Number of replicas for the Deployment. + + - `wanAddress` ((#v-meshgateway-wanaddress)) - What gets registered as WAN (wide area network) address for the gateway. + + - `source` ((#v-meshgateway-wanaddress-source)) (`string: "Service"`) - source configures where to retrieve the WAN address (and possibly port) + for the mesh gateway from. + Can be set to either: `Service`, `NodeIP`, `NodeName` or `Static`. See the behavior of each below: + + * `Service` - Determine the address based on the service type. + + If `service.type=LoadBalancer` use the external IP or hostname of + the service. Use the port set by `service.port`. + + If `service.type=NodePort` use the Node IP. The port will be set to + `service.nodePort` so `service.nodePort` cannot be null. + + If `service.type=ClusterIP` use the ClusterIP. The port will be set to + `service.port`. + + `service.type=ExternalName` is not supported. + + * `NodeIP` - The node IP as provided by the Kubernetes downward API. + + * `NodeName` - The name of the node as provided by the Kubernetes downward + API. This is useful if the node names are DNS entries that + are routable from other datacenters. + + * `Static` - Use the address hardcoded in `meshGateway.wanAddress.static`. + + - `port` ((#v-meshgateway-wanaddress-port)) (`int: 443`) - Port that gets registered for WAN traffic. + If source is set to "Service" then this setting will have no effect. + See the documentation for `source` as to which port will be used in that + case. + + - `static` ((#v-meshgateway-wanaddress-static)) (`string: ""`) - If source is set to "Static" then this value will be used as the WAN + address of the mesh gateways. This is useful if you've configured a + DNS entry to point to your mesh gateways. + + - `service` ((#v-meshgateway-service)) - The service option configures the Service that fronts the Gateway Deployment. + + - `enabled` ((#v-meshgateway-service-enabled)) (`bool: true`) - Whether to create a Service or not. + + - `type` ((#v-meshgateway-service-type)) (`string: "LoadBalancer"`) - Type of service, ex. LoadBalancer, ClusterIP. + + - `port` ((#v-meshgateway-service-port)) (`int: 443`) - Port that the service will be exposed on. + The `targetPort` will be set to `meshGateway.containerPort`. + + - `nodePort` ((#v-meshgateway-service-nodeport)) (`int: null`) - Optionally hardcode the `nodePort` of the service if using a NodePort service. + If not set and using a NodePort service, Kubernetes will automatically assign a port. + + - `annotations` ((#v-meshgateway-service-annotations)) (`string: null`) - Annotations to apply to the mesh gateway service. + + ```yaml + annotations: | + "sample/annotation1": "foo" + "sample/annotation2": "bar" + ``` + + - `additionalspec` ((#v-meshgateway-service-additionalspec)) (`string: null`) - Optional YAML string that will be appended to the Service spec. + + - `imageEnvoy` ((#v-meshgateway-imageenvoy)) (`string: "envoyproxy/envoy:v1.13.0"`) - Envoy image to use. For Consul v1.7+, Envoy version 1.13+ is required. + + - `hostNetwork` ((#v-meshgateway-hostnetwork)) (`bool: false`) - If set to true, gateway Pods will run on the host network. + + - `dnsPolicy` ((#v-meshgateway-dnspolicy)) (`string: null`) - `dnsPolicy` to use. + + - `consulServiceName` ((#v-meshgateway-consulservicename)) (`string: "mesh-gateway"`) - Consul service name for the mesh gateways. + Cannot be set to anything other than `"mesh-gateway"` if `global.acls.manageSystemACLs` is true since the ACL token + generated is only for the name "mesh-gateway". + + - `containerPort` ((#v-meshgateway-containerPort)) (`int: 8443`) - Port that the gateway will run on inside the container. + + - `hostPort` ((#v-meshgateway-hostport)) (`int: null`) - Optional `hostPort` for the gateway to be exposed on. + This can be used with `wanAddress.port` and `wanAddress.useNodeIP` + to expose the gateways directly from the node. + If `hostNetwork=true`, this must be `null` or set to the same port as + `containerPort`. + **NOTE:** Cannot set to 8500 or 8502 because those are reserved for the Consul + agent. + + - `resources` ((#v-meshgateway-resources)) (`string`) - Resources for gateway pods. See values file for default. + + - `affinity` ((#v-meshgateway-affinity)) (`string`) - Affinity setting for gateway pods. See values file for default. + + - `tolerations` ((#v-meshgateway-tolerations)) (`string: null`) - Optional YAML string to specify tolerations. + + - `nodeSelector` ((#v-meshgateway-nodeselector)) (`string: null`) - Optional YAML string to specify nodeSelector config. + + - `priorityClassName` ((#v-meshgateway-priorityclassname)) (`string: """`) - Optional priorityClassName. + + - `annotations` ((#v-meshgateway-annotations)) (`string: null`) - Annotations for the mesh gateway deployment. + - `tests` ((#v-tests)) - Control whether to enable a test for this Helm chart. - - `enabled` ((#v-tests-enabled)) (`boolean: true`) If true, the test Pod manifest will be generated + - `enabled` ((#v-tests-enabled)) (`boolean: true`) - If true, the test Pod manifest will be generated to be used as a Helm test. The pod will be created when a `helm test` command is executed. ## Helm Chart Examples