mirror of https://github.com/status-im/consul.git
Luke Kysow
GitHub
parent
af56f86ad5
commit
11db2b37c3
|
|
@ -169,7 +169,10 @@ export default [
|
|||
],
|
||||
},
|
||||
'service-sync',
|
||||
'crds',
|
||||
{
|
||||
category: 'crds',
|
||||
content: ['upgrade-to-crds'],
|
||||
},
|
||||
'dns',
|
||||
{
|
||||
category: 'upgrade',
|
||||
|
|
|
|||
|
|
@ -1,19 +1,16 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Consul Custom Resource Definitions (Beta)
|
||||
sidebar_title: Custom Resource Definitions <sup>(Beta)</sup>
|
||||
page_title: Consul Custom Resource Definitions
|
||||
sidebar_title: Custom Resource Definitions
|
||||
description: >-
|
||||
Consul now supports managing configuration entries via Kubernetes Custom Resources.
|
||||
Consul supports managing configuration entries via Kubernetes Custom Resources.
|
||||
These custom resource can be used to manage the configuration for workloads
|
||||
deployed within the cluster.
|
||||
---
|
||||
|
||||
# Custom Resource Definitions <sup>(beta)</sup>
|
||||
# Custom Resource Definitions
|
||||
|
||||
## Overview
|
||||
|
||||
-> **This feature is currently in Beta.** It requires consul-helm >= 0.25.0 and
|
||||
consul >= 1.8.4.
|
||||
-> This feature requires consul-helm >= 0.26.0, consul-k8s >= 0.20.0 and consul >= 1.8.4.
|
||||
|
||||
We support managing Consul [configuration entries](/docs/agent/config-entries)
|
||||
via Kubernetes Custom Resources. Configuration entries are used to provide
|
||||
|
|
@ -35,15 +32,15 @@ The following kinds are **not** currently supported:
|
|||
|
||||
## Installation
|
||||
|
||||
Ensure you have version `0.25.0` of the helm chart:
|
||||
Ensure you have version `0.26.0` of the helm chart:
|
||||
|
||||
```shell-session
|
||||
$ helm search repo hashicorp/consul
|
||||
NAME CHART VERSION APP VERSION DESCRIPTION
|
||||
hashicorp/consul 0.25.0 1.8.4 Official HashiCorp Consul Chart
|
||||
hashicorp/consul 0.26.0 1.8.5 Official HashiCorp Consul Chart
|
||||
```
|
||||
|
||||
If you don't have `0.25.0`, you will need to update your helm repository cache:
|
||||
If you don't have `0.26.0`, you will need to update your helm repository cache:
|
||||
|
||||
```shell-session
|
||||
$ helm repo update
|
||||
|
|
@ -59,7 +56,7 @@ and enable the controller that acts on them:
|
|||
global:
|
||||
name: consul
|
||||
image: 'consul:1.9.0-beta1' # consul >= 1.8.4 must be used
|
||||
imageK8S: 'hashicorp/consul-k8s:0.19.0'
|
||||
imageK8S: 'hashicorp/consul-k8s:0.20.0'
|
||||
|
||||
controller:
|
||||
enabled: true
|
||||
|
|
@ -72,13 +69,18 @@ Note that:
|
|||
|
||||
1. `controller.enabled: true` installs the CRDs and enables the controller.
|
||||
1. `global.image` must be a Consul version `>= 1.8.4`, e.g. `consul:1.8.4` or `consul:1.9.0-beta1`.
|
||||
1. `global.imageK8S` must be `>= 0.19.0`
|
||||
1. `global.imageK8S` must be `>= 0.20.0`
|
||||
1. Configuration entries are used to configure Consul service mesh so it's also
|
||||
expected that `connectInject` will be enabled.
|
||||
|
||||
See [Install with Helm Chart](/docs/k8s/installation/install) for further installation
|
||||
instructions.
|
||||
|
||||
## Upgrading An Existing Cluster to CRDs
|
||||
|
||||
If you have an existing Consul cluster running on Kubernetes you may need to perform
|
||||
extra steps to migrate to CRDs. See [Upgrade An Existing Cluster to CRDs](/docs/k8s/crds/upgrade-to-crds) for full instructions.
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, you can use `kubectl` to create and manage Consul's configuration entries.
|
||||
|
|
@ -0,0 +1,321 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -281,9 +281,9 @@ to be stopped and restarted with the new image.
|
|||
This can be confirmed by issuing `consul members` on one of the previous servers,
|
||||
and ensuring that all servers are listed and are `alive`.
|
||||
|
||||
Decrease `updatePartition` by one and upgrade again. Continue until
|
||||
`updatePartition` is `0`. At this point, you may remove the
|
||||
`updatePartition` configuration. Your server upgrade is complete.
|
||||
1. Decrease `updatePartition` by one and upgrade again. Continue until
|
||||
`updatePartition` is `0`. At this point, you may remove the
|
||||
`updatePartition` configuration. Your server upgrade is complete.
|
||||
|
||||
## Upgrading Consul Clients
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue