status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs describing migrating to CRDs (#9562) 

* Document how users can migrate to CRDs.
* Update documentation for federation with new `ProxyDefaults`
requirement.
* Ensure `controller.enabled: true` is set in our example configs.
* Remove `connect-service-protocol` annotation docs.
This commit is contained in:
Luke Kysow 2021-02-17 11:01:52 -08:00 committed by GitHub
parent c309d2b6cb
commit 2df91c2050
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 357 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
website/content/docs/k8s/connect/index.mdx
View File

@ -248,14 +248,6 @@ Annotations can be used to configure the injection behavior.
"consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],prepared_query:[query name]:[port]" "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],prepared_query:[query name]:[port]"
``` ```
- `consul.hashicorp.com/connect-service-protocol` - For pods that will be
registered with Consul's [central configuration](/docs/agent/config-entries)
feature, information about the protocol the service uses is required. Users
can define the protocol directly using this annotation on the pod spec, or by
defining a default value for all services using the Helm chart's
[defaultProtocol](/docs/k8s/helm#v-connectinject-centralconfig-defaultprotocol)
option. Specific annotations will always override the default value.
- `consul.hashicorp.com/envoy-extra-args` - A space-separated list of [arguments](https://www.envoyproxy.io/docs/envoy/latest/operations/cli) - `consul.hashicorp.com/envoy-extra-args` - A space-separated list of [arguments](https://www.envoyproxy.io/docs/envoy/latest/operations/cli)
to be passed to the injected envoy binary. to be passed to the injected envoy binary.
@ -345,16 +337,13 @@ Installation of the mutating admission webhook is automated using the
To install the Connect injector, enable the Connect injection feature using To install the Connect injector, enable the Connect injection feature using
[Helm values](/docs/k8s/helm#configuration-values) and [Helm values](/docs/k8s/helm#configuration-values) and
upgrade the installation using `helm upgrade` for existing installs or upgrade the installation using `helm upgrade` for existing installs or
`helm install` for a fresh install. The Connect injector **also requires** `helm install` for a fresh install.
[client agents](/docs/k8s/helm#v-client) are enabled on
the node with pods that are using Connect and that
[gRPC is enabled](/docs/k8s/helm#v-client-grpc).
```yaml ```yaml
connectInject: connectInject:
enabled: true enabled: true
client: controller:
enabled: true enabled: true
``` ```
@ -363,10 +352,6 @@ This will configure the injector to inject when the
is set to `true`. Other values in the Helm chart can be used to limit the namespaces is set to `true`. Other values in the Helm chart can be used to limit the namespaces
the injector runs in, enable injection by default, and more. the injector runs in, enable injection by default, and more.
~> NOTE: If setting `global.bootstrapACLs: true`, it's important that your pod's `ServiceAccount`
has the **same name** as the Consul service that's being registered. If not, the init
container will log: `Error logging in: Unexpected response code: 403 (rpc error making call: rpc error making call: Permission denied)`.
### Controlling Injection Via Annotation ### Controlling Injection Via Annotation
By default, the injector will inject only when the By default, the injector will inject only when the

566
website/content/docs/k8s/crds/upgrade-to-crds.mdx
View File

@ -8,314 +8,348 @@ description: >-
# Upgrade An Existing Cluster to CRDs # Upgrade An Existing Cluster to CRDs
-> This feature requires consul-helm >= 0.26.0, consul-k8s >= 0.20.0 and consul >= 1.8.4. Upgrading to consul-helm versions >= `0.30.0` will require some changes if
you utilize the following:
If you have an existing Consul cluster running on Kubernetes you may need to perform - [`connectInject.centralConfig.enabled`](#central-config-enabled)
extra steps to migrate to CRDs. - [`connectInject.centralConfig.defaultProtocol`](#default-protocol)
- [`connectInject.centralConfig.proxyDefaults`](#proxy-defaults)
- [`meshGateway.globalMode`](#mesh-gateway-mode)
- [Connect annotation `consul.hashicorp.com/connect-service-protocol`](#connect-service-protocol-annotation)
You will need to perform extra steps if you are using any of the following configurations: ## Central Config Enabled
- Helm config `connectInject.centralConfig.defaultProtocol`, e.g. If you were previously setting `centralConfig.enabled` to `false`:
```yaml ```yaml
connectInject: connectInject:
centralConfig: centralConfig:
defaultProtocol: http enabled: false
``` ```
- Or setting the `consul.hashicorp.com/connect-service-protocol` annotation on your Then instead you must use `server.extraConfig` and `client.extraConfig`:
connect pods, e.g.
```yaml ```yaml
annotations: client:
'consul.hashicorp.com/connect-service-protocol': 'http' extraConfig: |
``` {"enable_central_service_config": false}
server:
extraConfig: |
{"enable_central_service_config": false}
```
- Or Helm config `connectInject.centralConfig.proxyDefaults`, e.g. If you were previously setting it to `true`, it now defaults to `true` so no
```yaml changes are required, but you can remove it from your config if you desire.
connectInject:
centralConfig:
proxyDefaults: |
{
"local_connect_timeout_ms": 1000
}
```
## Why Migrate?
All of the above settings do not support modification after the initial
installation of Consul, i.e. they cannot be updated through the Helm chart.
By switching to custom resources, these settings can now be modified.
## Migration Overview
The migration process will consist of identifying which [config entries](/docs/agent/config-entries)
have been created in Consul and adding metadata to them so that they can
be managed by a custom resource instead.
## Default Protocol ## Default Protocol
If you are setting `connectInject.centralConfig.defaultProtocol` then you must If you were previously setting:
perform the follow steps to migrate to custom resources.
1. Find existing `service-defaults` config entries: ```yaml
```shell-session connectInject:
$ consul config list -kind service-defaults centralConfig:
static-client defaultProtocol: 'http' # or any value
static-server ```
```
1. For each entry, export the config to a file:
```shell-session Now you must use [custom resources](/docs/k8s/crds) to manage the protocol for
$ consul config read -name static-client -kind service-defaults > static-client.json new and existing services:
```
1. Edit the file and add the key `"Meta": {"consul.hashicorp.com/source-datacenter": "dc1"}`. 1. To upgrade, first ensure you're running Consul >= 1.9.0. See [Consul Version Upgrade](/docs/k8s/upgrade#consul-version-upgrade)
Where `dc1` is the name of your datacenter. Make sure you add any missing trailing commas required for JSON: for more information on how to upgrade Consul versions.
```json This version is required to support custom resources.
{
"Kind": "service-defaults",
"Name": "static-client",
"Protocol": "http",
"MeshGateway": {},
"Expose": {},
"CreateIndex": 26,
"ModifyIndex": 26,
"Meta": { "consul.hashicorp.com/source-datacenter": "dc1" }
}
```
1. Write the updated config entry: 1. Next, modify your Helm values:
1. Remove the `defaultProtocol` config. This won't affect existing services.
```shell-session 1. Set:
$ consul config write static-client.json ```yaml
Config entry written: service-defaults/static-client controller:
``` enabled: true
```
1. Now you're ready to create a custom resource that takes over control of this 1. Now you can upgrade your Helm chart to the latest version with the new Helm values.
config entry. The custom resource will look like: 1. From now on, any new service will require a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults)
resource to set its protocol:
```yaml ```yaml
apiVersion: consul.hashicorp.com/v1alpha1 apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults kind: ServiceDefaults
metadata: metadata:
name: static-client name: my-service-name
spec: spec:
protocol: 'http' protocol: 'http'
``` ```
Where `metadata.name` is the name of your service and `spec.protocol` is 1. Existing services will maintain their previously set protocol. If you wish to
the default protocol you've set. change that protocol, you must migrate that service's `service-defaults` config
entry to a `ServiceDefaults` resource. See [Migrating Config Entries](#migrating-config-entries).
1. When you run `kubectl apply` on this file, the `ServiceDefaults` custom -> **Note:** This setting was removed because it didn't support changing the protocol after a service was first run and because it didn't work in secondary datacenters.
resource should be created successfully and its `synced` status will be `True`:
```shell-session
$ cat <<EOF | kubectl apply -f -
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: static-client
spec:
protocol: "http"
EOF
servicedefaults.consul.hashicorp.com/static-client created
$ kubectl get servicedefaults static-client
NAME SYNCED AGE
static-client True 1s
```
1. Repeat steps 2-6 for each service-defaults config entry.
1. Finally, delete your `connectInject.centralConfig.defaultProtocol` Helm config and run Helm upgrade.
From here on out, you must create a `ServiceDefaults` custom resource
for each new service to set its protocol. As there will no longer be a
default.
## Connect Service Protocol Annotation
If you are setting the `consul.hashicorp.com/connect-service-protocol` annotation on your
connect pods, then you must perform the follow steps to migrate to custom resources.
1. Find existing `service-defaults` config entries:
```shell-session
$ consul config list -kind service-defaults
static-client
static-server
```
1. For each entry, export the config to a file:
```shell-session
$ consul config read -name static-client -kind service-defaults > static-client.json
```
1. Edit the file and add the key `"Meta": {"consul.hashicorp.com/source-datacenter": "dc1"}`.
Where `dc1` is the name of your datacenter. Make sure you add any missing trailing commas required for JSON:
```json
{
"Kind": "service-defaults",
"Name": "static-client",
"Protocol": "http",
"MeshGateway": {},
"Expose": {},
"CreateIndex": 26,
"ModifyIndex": 26,
"Meta": { "consul.hashicorp.com/source-datacenter": "dc1" }
}
```
1. Write the updated config entry:
```shell-session
$ consul config write static-client.json
Config entry written: service-defaults/static-client
```
1. Now you're ready to create a custom resource that takes over control of this
config entry. The custom resource will look like:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: static-client
spec:
protocol: 'http'
```
Where `metadata.name` is the name of your service and `spec.protocol` is
the default protocol you've set.
1. When you run `kubectl apply` on this file, the `ServiceDefaults` custom
resource should be created successfully and its `synced` status will be `True`:
```shell-session
$ cat <<EOF | kubectl apply -f -
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: static-client
spec:
protocol: "http"
EOF
servicedefaults.consul.hashicorp.com/static-client created
$ kubectl get servicedefaults static-client
NAME SYNCED AGE
static-client True 1s
```
1. Repeat steps 2-6 for each service-defaults config entry.
1. You can now remove the `consul.hashicorp.com/connect-service-protocol`
annotation from your deployments to indicate it is no longer used.
## Proxy Defaults ## Proxy Defaults
If you are setting `connectInject.centralConfig.proxyDefaults` then you must If you were previously setting:
perform the follow steps to migrate to custom resources.
1. Get your existing proxy-defaults config: ```yaml
connectInject:
centralConfig:
proxyDefaults: |
{
"key": "value" // or any values
}
```
```shell-session You will need to perform the following steps to upgrade:
$ consul config read -name global -kind proxy-defaults
{ 1. You must remove the setting from your Helm values. This won't have any
"Kind": "proxy-defaults", effect on your existing cluster because this config is only read when
"Name": "global", the cluster is **first created**.
"Config": { 1. You can then upgrade the Helm chart.
"local_connect_timeout_ms": 1000 1. If you later wish to _change_ any of the proxy defaults settings, you will need
}, to follow the [Migrating Config Entries](#migrating-config-entries)
"MeshGateway": { instructions for your `proxy-defaults` config entry.
"Mode": "local"
}, This will require Consul >= 1.9.0.
"Expose": {},
"CreateIndex": 4, -> **Note:** This setting was removed because it couldn't be changed after initial
"ModifyIndex": 4 installation.
}
## Mesh Gateway Mode
If you were previously setting:
```yaml
meshGateway:
globalMode: 'local' # or any value
```
You will need to perform the following steps to upgrade:
1. You must remove the setting from your Helm values. This won't have any
effect on your existing cluster because this config is only read when
the cluster is **first created**.
1. You can then upgrade the Helm chart.
1. If you later wish to _change_ the mode or any other setting in [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults), you will need
to follow the [Migrating Config Entries](#migrating-config-entries)
instructions to migrate your `proxy-defaults` config entry to a `ProxyDefaults` resource.
This will require Consul >= 1.9.0.
-> **Note:** This setting was removed because it couldn't be changed after initial
installation.
## connect-service-protocol Annotation
If any of your Connect services had the `consul.hashicorp.com/connect-service-protocol`
annotation set, e.g.
```yaml
apiVersion: apps/v1
kind: Deployment
...
spec:
template:
metadata:
annotations:
"consul.hashicorp.com/connect-inject": "true"
"consul.hashicorp.com/connect-service-protocol": "http"
...
```
You will need to perform the following steps to upgrade:
1. Ensure you're running Consul >= 1.9.0. See [Consul Version Upgrade](/docs/k8s/upgrade#consul-version-upgrade)
for more information on how to upgrade Consul versions.
This version is required to support custom resources.
1. Next, remove this annotation from existing deployments. This will have no
effect on the deployments because the annotation was only used when the
service was first created.
1. Modify your Helm values and add:
```yaml
controller:
enabled: true
``` ```
1. Export to a file: 1. Now you can upgrade your Helm chart to the latest version.
1. From now on, any new service will require a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults)
```shell-session resource to set its protocol:
$ consul config read -name global -kind proxy-defaults > proxy-defaults.json
```
1. Edit the file and add the key `"Meta": {"consul.hashicorp.com/source-datacenter": "dc1"}`.
Where `dc1` is the name of your datacenter. Make sure you add any missing trailing commas required for JSON:
```json
{
"Kind": "proxy-defaults",
"Name": "global",
"Config": {
"local_connect_timeout_ms": 1000
},
"MeshGateway": {
"Mode": "local"
},
"Expose": {},
"CreateIndex": 4,
"ModifyIndex": 4,
"Meta": { "consul.hashicorp.com/source-datacenter": "dc1" }
}
```
1. Write the updated config entry:
```shell-session
$ consul config write proxy-defaults.json
Config entry written: proxy-defaults/global
```
1. Now you're ready to create a custom resource that takes over control of this
config entry. The custom resource will look like:
```yaml ```yaml
apiVersion: consul.hashicorp.com/v1alpha1 apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults kind: ServiceDefaults
metadata: metadata:
name: global name: my-service-name
spec: spec:
config: protocol: 'http'
local_connect_timeout_ms: 1000
meshGateway:
mode: local
``` ```
Any keys you had under `"Config"` must be set in YAML. 1. Existing services will maintain their previously set protocol. If you wish to
If you previously had `"MeshGateway"` config this must also be set now change that protocol, you must migrate that service's `service-defaults` config
under `spec.meshGateway`. Also, `metadata.name` must be `global`. entry to a `ServiceDefaults` resource. See [Migrating Config Entries](#migrating-config-entries).
1. When you run `kubectl apply` on this file, the `ProxyDefaults` custom -> **Note:** The annotation was removed because it didn't support changing the protocol
resource should be created successfully and its `synced` status will be `True`: and it wasn't supported in secondary datacenters.
## Migrating Config Entries
A config entry that already exists in Consul must be migrated into a Kubernetes custom resource in order to
manage it from Kubernetes:
1. Determine the `kind` and `name` of the config entry. For example, the protocol
would be set by a config entry with `kind: service-defaults` and `name` equal
to the name of the service.
In another example, a `proxy-defaults` config has `kind: proxy-defaults` and
`name: global`.
1. Once you've determined the `kind` and `name`, query Consul to get its contents:
```shell-session ```shell-session
$ cat <<EOF | kubectl apply -f - $ consul config read -kind <kind> -name <name>
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
config:
local_connect_timeout_ms: 1000
meshGateway:
mode: local
EOF
proxydefaults.consul.hashicorp.com/global created
$ kubectl get proxydefaults global
NAME SYNCED AGE
global True 1s
``` ```
1. Finally, delete your `connectInject.centralConfig.proxyDefaults` Helm config and run Helm upgrade. This will require `kubectl exec`'ing into a Consul server or client pod. If
you're using ACLs, you will also need an ACL token passed via the `-token` flag.
This will have no effect because changes to this config are not picked up For example:
by Consul after initial installation.
```shell-session
$ kubectl exec consul-server-0 -- consul config read -name foo -kind service-defaults
{
"Kind": "service-defaults",
"Name": "foo",
"Protocol": "http",
"MeshGateway": {},
"Expose": {},
"CreateIndex": 60,
"ModifyIndex": 60
}
```
1. Now we're ready to construct a Kubernetes resource for the config entry.
It will look something like:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: foo
annotations:
'consul.hashicorp.com/migrate-entry': 'true'
spec:
protocol: 'http'
```
1. The `apiVersion` will always be `consul.hashicorp.com/v1alpha1`.
1. The `kind` will be the CamelCase version of the Consul kind, e.g.
`proxy-defaults` becomes `ProxyDefaults`.
1. `metadata.name` will be the `name` of the config entry.
1. `metadata.annotations` will contain the `"consul.hashicorp.com/migrate-entry": "true"`
annotation.
1. The namespace should be whatever namespace the service is deployed in.
For `ProxyDefaults`, we recommend the namespace that Consul is deployed in.
1. The contents of `spec` will be a transformation from JSON keys to YAML
keys.
The following keys can be ignored: `CreateIndex`, `ModifyIndex`
and any key that has an empty object, e.g. `"Expose": {}`.
For example:
```json
{
"Kind": "service-defaults",
"Name": "foo",
"Protocol": "http",
"MeshGateway": {},
"Expose": {},
"CreateIndex": 60,
"ModifyIndex": 60
}
```
Becomes:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: foo
annotations:
'consul.hashicorp.com/migrate-entry': 'true'
spec:
protocol: 'http'
```
And
```json
{
"Kind": "proxy-defaults",
"Name": "global",
"MeshGateway": {
"Mode": "local"
},
"Config": {
"local_connect_timeout_ms": 1000,
"handshake_timeout_ms": 10000
},
"CreateIndex": 60,
"ModifyIndex": 60
}
```
Becomes:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
annotations:
'consul.hashicorp.com/migrate-entry': 'true'
spec:
meshGateway:
mode: local
config:
# Note that anything under config for ProxyDefaults will use the exact
# same keys.
local_connect_timeout_ms: 1000
handshake_timeout_ms: 10000
```
1. Run `kubectl apply` to apply the Kubernetes resource.
1. Next, check that it synced successfully:
```shell-session
$ kubectl get servicedefaults foo
NAME SYNCED AGE
foo True 1s
```
1. If its `SYNCED` status is `True` then the migration for this config entry
was successful.
1. If its `SYNCED` status is `False`, use `kubectl describe` to view
the reason syncing failed:
```shell-session
$ kubectl describe servicedefaults foo
...
Status:
Conditions:
Last Transition Time: 2021-01-12T21:03:29Z
Message: migration failed: Kubernetes resource does not match existing Consul config entry: consul={...}, kube={...}
Reason: MigrationFailedError
Status: False
Type: Synced
```
The most likely reason is that the contents of the Kubernetes resource
don't match the Consul resource. Make changes to the Kubernetes resource
to match the Consul resource (ignoring the `CreateIndex`, `ModifyIndex` and `Meta` keys).
1. Once the `SYNCED` status is true, you can make changes to the resource and they
will get synced to Consul.

30
website/content/docs/k8s/helm.mdx
View File

@ -278,7 +278,7 @@ and consider if they're appropriate for your deployment.
enable `server.exposeGossipAndRPCPorts` and `client.exposeGossipPorts`, enable `server.exposeGossipAndRPCPorts` and `client.exposeGossipPorts`,
that will configure the LAN gossip ports on the servers and clients to be that will configure the LAN gossip ports on the servers and clients to be
hostPorts, so if you are running clients and servers on the same node the hostPorts, so if you are running clients and servers on the same node the
ports will conflict if they are both 8301. When you enable ports will conflict if they are both 8301. When you enable
`server.exposeGossipAndRPCPorts` and `client.exposeGossipPorts`, you must `server.exposeGossipAndRPCPorts` and `client.exposeGossipPorts`, you must
change this from the default to an unused port on the host, e.g. 9301. By change this from the default to an unused port on the host, e.g. 9301. By
default the LAN gossip port is 8301 and configured as a containerPort on default the LAN gossip port is 8301 and configured as a containerPort on
@ -1111,25 +1111,6 @@ and consider if they're appropriate for your deployment.
- `secretKey` ((#v-connectinject-aclinjecttoken-secretkey)) (`string: null`) - The key of the Kubernetes secret. - `secretKey` ((#v-connectinject-aclinjecttoken-secretkey)) (`string: null`) - The key of the Kubernetes secret.
- `centralConfig` ((#v-connectinject-centralconfig)) - Requires Consul >= v1.5 and consul-k8s >= v0.8.1.
- `enabled` ((#v-connectinject-centralconfig-enabled)) (`boolean: true`) - Controls whether central config is enabled on all servers and clients.
See https://www.consul.io/docs/agent/options.html#enable_central_service_config.
If changing this after installation, servers and clients must be restarted
for the change to take effect.
- `defaultProtocol` ((#v-connectinject-centralconfig-defaultprotocol)) (`string: null`) - Allows you to specify a convenience default protocol if
most of your services are of the same protocol type. The individual annotation
on any given pod will override this value.
Valid values are "http", "http2", "grpc" and "tcp".
- `proxyDefaults` ((#v-connectinject-centralconfig-proxydefaults)) (`string: {}`) - Raw json string that will be written as the value of
the "config" key of the global proxy-defaults config entry.
See: https://www.consul.io/docs/agent/config-entries/proxy-defaults.html
NOTE: Changes to this value after the chart is first installed have _no_
effect. In order to change the proxy-defaults config after installation,
you must use the Consul API.
- `sidecarProxy` ((#v-connectinject-sidecarproxy)) - `sidecarProxy` ((#v-connectinject-sidecarproxy))
- `resources` ((#v-connectinject-sidecarproxy-resources)) (`map`) - Set default resources for sidecar proxy. If null, that resource won't - `resources` ((#v-connectinject-sidecarproxy-resources)) (`map`) - Set default resources for sidecar proxy. If null, that resource won't
@ -1184,15 +1165,6 @@ and consider if they're appropriate for your deployment.
Requirements: consul 1.6.0+ and consul-k8s 0.15.0+ if using Requirements: consul 1.6.0+ and consul-k8s 0.15.0+ if using
global.acls.manageSystemACLs. 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 empty string or null.
See 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)) (`integer: 2`) - Number of replicas for the Deployment. - `replicas` ((#v-meshgateway-replicas)) (`integer: 2`) - Number of replicas for the Deployment.
- `wanAddress` ((#v-meshgateway-wanaddress)) - What gets registered as WAN address for the gateway. - `wanAddress` ((#v-meshgateway-wanaddress)) - What gets registered as WAN address for the gateway.

2
website/content/docs/k8s/installation/install.mdx
View File

@ -107,6 +107,8 @@ global:
name: consul name: consul
connectInject: connectInject:
enabled: true enabled: true
controller:
enabled: true
``` ```
Once you've created your `config.yaml` file, run `helm install` with the `-f` flag: Once you've created your `config.yaml` file, run `helm install` with the `-f` flag:

46
website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx
View File

@ -68,6 +68,9 @@ connectInject:
# Consul Connect service mesh must be enabled for federation. # Consul Connect service mesh must be enabled for federation.
enabled: true enabled: true
controller:
enabled: true
meshGateway: meshGateway:
# Mesh gateways are gateways between datacenters. They must be enabled # Mesh gateways are gateways between datacenters. They must be enabled
# for federation in Kubernetes since the communication between datacenters # for federation in Kubernetes since the communication between datacenters
@ -114,8 +117,7 @@ Modifications:
see the [Helm reference](/docs/k8s/helm#v-meshgateway) for that setting. see the [Helm reference](/docs/k8s/helm#v-meshgateway) for that setting.
With your `config.yaml` ready to go, follow our [Installation Guide](/docs/k8s/installation/install) With your `config.yaml` ready to go, follow our [Installation Guide](/docs/k8s/installation/install)
to install Consul on your primary cluster and then skip ahead to the [Federation Secret](#federation-secret) to install Consul on your primary cluster.
section.
-> **NOTE:** You must be using consul-helm 0.21.0+. To update, run `helm repo update`. -> **NOTE:** You must be using consul-helm 0.21.0+. To update, run `helm repo update`.
@ -155,7 +157,43 @@ If you've set `enableAutoEncrypt: true`, this is also supported.
With the above settings added to your existing config, follow the [Upgrading](/docs/k8s/operations/upgrading) With the above settings added to your existing config, follow the [Upgrading](/docs/k8s/operations/upgrading)
guide to upgrade your cluster and then come back to the [Federation Secret](#federation-secret) section. guide to upgrade your cluster and then come back to the [Federation Secret](#federation-secret) section.
-> **NOTE:** You must be using consul-helm 0.21.0+. To update, run `helm repo update`. -> **NOTE:** You must be using consul-helm 0.21.0+.
#### ProxyDefaults
If you are using consul-helm 0.30.0+ you must also create a [`ProxyDefaults`](/docs/connect/config-entries/proxy-defaults)
resource to configure Consul to use the mesh gateways for service mesh traffic.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
meshGateway:
mode: 'local'
```
The `spec.meshGateway.mode` can be set to `local` or `remote`. If set to `local`,
traffic from one datacenter to another will egress through the local mesh gateway.
This may be useful if you prefer all your cross-cluster network traffic to egress
from the same locations.
If set to `remote`, traffic will be routed directly from the pod to the remote mesh gateway
(resulting in one less hop).
Verify that the resource was synced to Consul:
```shell-session
$ kubectl get proxydefaults global
NAME SYNCED AGE
global True 1s
```
Its `SYNCED` status should be `True`.
-> **NOTE:** The `ProxyDefaults` resource can be created in any namespace, but
we recommend creating it in the same namespace that Consul is installed in.
Its name must be `global`.
## Federation Secret ## Federation Secret
@ -286,6 +324,8 @@ global:
secretKey: gossipEncryptionKey secretKey: gossipEncryptionKey
connectInject: connectInject:
enabled: true enabled: true
controller:
enabled: true
meshGateway: meshGateway:
enabled: true enabled: true
server: server:

12
website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx
View File

@ -21,8 +21,8 @@ must be the [primary](/docs/k8s/installation/multi-cluster/kubernetes#primary-da
If your primary datacenter is running on Kubernetes, use the Helm config from the If your primary datacenter is running on Kubernetes, use the Helm config from the
[Primary Datacenter](/docs/k8s/installation/multi-cluster/kubernetes#primary-datacenter) section to install Consul. [Primary Datacenter](/docs/k8s/installation/multi-cluster/kubernetes#primary-datacenter) section to install Consul.
Once installed, you'll need to export the following information from the primary Kubernetes Once installed, and with the `ProxyDefaults` [resource created](/docs/k8s/installation/multi-cluster/kubernetes#proxydefaults),
cluster: you'll need to export the following information from the primary Kubernetes cluster:
1. The certificate authority cert: 1. The certificate authority cert:
@ -271,6 +271,8 @@ global:
connectInject: connectInject:
enabled: true enabled: true
controller:
enabled: true
meshGateway: meshGateway:
enabled: true enabled: true
server: server:
@ -290,5 +292,9 @@ to install Consul on your secondary cluster(s).
## Next Steps ## Next Steps
Read the [Verifying Federation](/docs/k8s/installation/multi-cluster/kubernetes#verifying-federation) After installation, if you're using consul-helm 0.30.0+, [create the
`ProxyDefaults` resource](/docs/k8s/installation/multi-cluster/kubernetes#proxydefaults)
to allow traffic between datacenters.
Follow the [Verifying Federation](/docs/k8s/installation/multi-cluster/kubernetes#verifying-federation)
section to verify that federation is working as expected. section to verify that federation is working as expected.