322 lines
8.8 KiB
Plaintext
322 lines
8.8 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
|
||
|
|
|
||
|
|
-> This feature requires consul-helm >= 0.26.0, consul-k8s >= 0.20.0 and consul >= 1.8.4.
|
||
|
|
|
||
|
|
If you have an existing Consul cluster running on Kubernetes you may need to perform
|
||
|
|
extra steps to migrate to CRDs.
|
||
|
|
|
||
|
|
You will need to perform extra steps if you are using any of the following configurations:
|
||
|
|
|
||
|
|
- Helm config `connectInject.centralConfig.defaultProtocol`, e.g.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
connectInject:
|
||
|
|
centralConfig:
|
||
|
|
defaultProtocol: http
|
||
|
|
```
|
||
|
|
|
||
|
|
- Or setting the `consul.hashicorp.com/connect-service-protocol` annotation on your
|
||
|
|
connect pods, e.g.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
annotations:
|
||
|
|
'consul.hashicorp.com/connect-service-protocol': 'http'
|
||
|
|
```
|
||
|
|
|
||
|
|
- Or Helm config `connectInject.centralConfig.proxyDefaults`, e.g.
|
||
|
|
```yaml
|
||
|
|
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
|
||
|
|
|
||
|
|
If you are setting `connectInject.centralConfig.defaultProtocol` 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. 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
|
||
|
|
|
||
|
|
If you are setting `connectInject.centralConfig.proxyDefaults` then you must
|
||
|
|
perform the follow steps to migrate to custom resources.
|
||
|
|
|
||
|
|
1. Get your existing proxy-defaults config:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ consul config read -name global -kind proxy-defaults
|
||
|
|
{
|
||
|
|
"Kind": "proxy-defaults",
|
||
|
|
"Name": "global",
|
||
|
|
"Config": {
|
||
|
|
"local_connect_timeout_ms": 1000
|
||
|
|
},
|
||
|
|
"MeshGateway": {
|
||
|
|
"Mode": "local"
|
||
|
|
},
|
||
|
|
"Expose": {},
|
||
|
|
"CreateIndex": 4,
|
||
|
|
"ModifyIndex": 4
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
1. Export to a file:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ 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
|
||
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
||
|
|
kind: ProxyDefaults
|
||
|
|
metadata:
|
||
|
|
name: global
|
||
|
|
spec:
|
||
|
|
config:
|
||
|
|
local_connect_timeout_ms: 1000
|
||
|
|
meshGateway:
|
||
|
|
mode: local
|
||
|
|
```
|
||
|
|
|
||
|
|
Any keys you had under `"Config"` must be set in YAML.
|
||
|
|
If you previously had `"MeshGateway"` config this must also be set now
|
||
|
|
under `spec.meshGateway`. Also, `metadata.name` must be `global`.
|
||
|
|
|
||
|
|
1. When you run `kubectl apply` on this file, the `ProxyDefaults` 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: 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 have no effect because changes to this config are not picked up
|
||
|
|
by Consul after initial installation.
|