From 9050263072b87a60026edebeca61093e118e553f Mon Sep 17 00:00:00 2001
From: Luke Kysow <1034429+lkysow@users.noreply.github.com>
Date: Fri, 13 Nov 2020 15:19:21 -0800
Subject: [PATCH] Docs for upgrading to CRDs (#9176)
* Add Upgrading to CRDs docs
---
website/data/docs-navigation.js | 5 +-
.../docs/k8s/{crds.mdx => crds/index.mdx} | 28 +-
.../pages/docs/k8s/crds/upgrade-to-crds.mdx | 321 ++++++++++++++++++
website/pages/docs/k8s/upgrade/index.mdx | 6 +-
4 files changed, 343 insertions(+), 17 deletions(-)
rename website/pages/docs/k8s/{crds.mdx => crds/index.mdx} (93%)
create mode 100644 website/pages/docs/k8s/crds/upgrade-to-crds.mdx
diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js
index 5f1ac13106..c9ccdc10e4 100644
--- a/website/data/docs-navigation.js
+++ b/website/data/docs-navigation.js
@@ -169,7 +169,10 @@ export default [
],
},
'service-sync',
- 'crds',
+ {
+ category: 'crds',
+ content: ['upgrade-to-crds'],
+ },
'dns',
{
category: 'upgrade',
diff --git a/website/pages/docs/k8s/crds.mdx b/website/pages/docs/k8s/crds/index.mdx
similarity index 93%
rename from website/pages/docs/k8s/crds.mdx
rename to website/pages/docs/k8s/crds/index.mdx
index a0292880b8..301a6747cd 100644
--- a/website/pages/docs/k8s/crds.mdx
+++ b/website/pages/docs/k8s/crds/index.mdx
@@ -1,19 +1,16 @@
---
layout: docs
-page_title: Consul Custom Resource Definitions (Beta)
-sidebar_title: Custom Resource Definitions (Beta)
+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 (beta)
+# 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.
diff --git a/website/pages/docs/k8s/crds/upgrade-to-crds.mdx b/website/pages/docs/k8s/crds/upgrade-to-crds.mdx
new file mode 100644
index 0000000000..e864ab2c2d
--- /dev/null
+++ b/website/pages/docs/k8s/crds/upgrade-to-crds.mdx
@@ -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 < 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 < 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 <