open-consul/website/content/docs/k8s/crds/upgrade-to-crds.mdx

356 lines
11 KiB
Plaintext

---
layout: docs
page_title: Upgrade An Existing Cluster to CRDs
sidebar_title: Upgrade An Existing Cluster to CRDs
description: >-
Upgrade an existing cluster to use custom resources.
---
# Upgrade An Existing Cluster to CRDs
Upgrading to consul-helm versions >= `0.30.0` will require some changes if
you utilize the following:
- [`connectInject.centralConfig.enabled`](#central-config-enabled)
- [`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)
## Central Config Enabled
If you were previously setting `centralConfig.enabled` to `false`:
```yaml
connectInject:
centralConfig:
enabled: false
```
Then instead you must use `server.extraConfig` and `client.extraConfig`:
```yaml
client:
extraConfig: |
{"enable_central_service_config": false}
server:
extraConfig: |
{"enable_central_service_config": false}
```
If you were previously setting it to `true`, it now defaults to `true` so no
changes are required, but you can remove it from your config if you desire.
## Default Protocol
If you were previously setting:
```yaml
connectInject:
centralConfig:
defaultProtocol: 'http' # or any value
```
Now you must use [custom resources](/docs/k8s/crds) to manage the protocol for
new and existing services:
1. To upgrade, first 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, modify your Helm values:
1. Remove the `defaultProtocol` config. This won't affect existing services.
1. Set:
```yaml
controller:
enabled: true
```
1. Now you can upgrade your Helm chart to the latest version with the new Helm values.
1. From now on, any new service will require a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults)
resource to set its protocol:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: my-service-name
spec:
protocol: 'http'
```
1. Existing services will maintain their previously set protocol. If you wish to
change that protocol, you must migrate that service's `service-defaults` config
entry to a `ServiceDefaults` resource. See [Migrating Config Entries](#migrating-config-entries).
-> **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.
## Proxy Defaults
If you were previously setting:
```yaml
connectInject:
centralConfig:
proxyDefaults: |
{
"key": "value" // or any values
}
```
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_ any of the proxy defaults settings, you will need
to follow the [Migrating Config Entries](#migrating-config-entries)
instructions for your `proxy-defaults` config entry.
This will require Consul >= 1.9.0.
-> **Note:** This setting was removed because it couldn't be changed after initial
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. 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)
resource to set its protocol:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: my-service-name
spec:
protocol: 'http'
```
1. Existing services will maintain their previously set protocol. If you wish to
change that protocol, you must migrate that service's `service-defaults` config
entry to a `ServiceDefaults` resource. See [Migrating Config Entries](#migrating-config-entries).
-> **Note:** The annotation was removed because it didn't support changing the protocol
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
$ consul config read -kind <kind> -name <name>
```
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.
For example:
```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.