Docs for upgrading to CRDs (#9176)

* Add Upgrading to CRDs docs

website/data/docs-navigation.js

@@ -169,7 +169,10 @@ export default [
         ],
       },
       'service-sync',
-      'crds',
+      {
+        category: 'crds',
+        content: ['upgrade-to-crds'],
+      },
       'dns',
       {
         category: 'upgrade',

website/pages/docs/k8s/crds/index.mdx

@@ -1,19 +1,16 @@
 ---
 layout: docs
-page_title: Consul Custom Resource Definitions (Beta)
+page_title: Consul Custom Resource Definitions
-sidebar_title: Custom Resource Definitions <sup>(Beta)</sup>
+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 requires consul-helm >= 0.26.0, consul-k8s >= 0.20.0 and consul >= 1.8.4.
-
--> **This feature is currently in Beta.** It requires consul-helm >= 0.25.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.

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 <<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.

website/pages/docs/k8s/upgrade/index.mdx

@@ -281,7 +281,7 @@ 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
+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.