From a31c3b34dc2566f53ba07a0da1e8b195b3433e50 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 12 Jun 2023 20:40:37 -0700 Subject: [PATCH 1/5] Propose new changes to APIgw upgrade instructions --- website/content/docs/api-gateway/upgrades.mdx | 72 ++++++++++++++++--- 1 file changed, 61 insertions(+), 11 deletions(-) diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx index 31bc1ec82374..5e10f2ad4b7c 100644 --- a/website/content/docs/api-gateway/upgrades.mdx +++ b/website/content/docs/api-gateway/upgrades.mdx @@ -47,40 +47,63 @@ To begin using the native API gateway, complete one of the following upgrade pat ## Upgrade to native Consul API gateway -You must begin the upgrade procedure with Consul API gateway v1.1 installed. If you are currently using a version of Consul API gateway older than v1.1, complete the necessary stages of the upgrade path to v1.1 before you begin upgrading to the native API gateway. Refer to the [Introduction](#introduction) for an overview of the upgrade paths. +You must begin the upgrade procedure with API gateway with Consul on Kubernetes v1.1 installed. If you are currently using a version of Consul on Kubernetes older than v1.1, complete the necessary stages of the upgrade path to v1.1 before you begin upgrading to the native API gateway. Refer to the [Introduction](#introduction) for an overview of the upgrade paths. ### Consul-managed CRDs If you are able to tolerate downtime for your applications, you should delete previously installed CRDs and allow Consul to install and manage them for future updates. The amount of downtime depends on how quickly you are able to install the new version of Consul. If you are unable to tolerate any downtime, refer to [Self-managed CRDs](#self-managed-crds) for instructions on how to upgrade without downtime. -1. Run the `kubectl delete` command and reference the kustomize directory to delete the existing CRDs. The following example deletes the CRDs that were installed with API gateway v0.5.1: +1. Run the `kubectl delete` command and reference the `kustomize` directory to delete the existing CRDs. The following example deletes the CRDs that were installed with API gateway `v0.5.1`: ```shell-session $ kubectl delete --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.5.1" ``` -1. Issue the following command to apply the configuration and complete the installation: +1. Issue the following command to use the API gateway packaged in Consul. Since Consul will not detected an external CRD, it will try to install the API gateway packaged with Consul. ```shell-session - $ kubectl apply -f apigw-installation.yaml + $ consul-k8s install -config-file values.yaml ``` 1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information. -1. After updating all of your `gateway` configurations to use the new controller, you can complete the upgrade again and completely remove the `apiGateway` block to remove the old controller. +1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller. + + + + ```diff + global: + image: hashicorp/consul:1.15 + imageK8S: hashicorp/consul-k8s-control-plane:1.1 + - apiGateway: + - enabled: true + - image: hashicorp/consul-api-gateway:0.5.4 + - managedGatewayClass: + - enabled: true + ``` + + + + ```shell-session + $ consul-k8s install -config-file values.yaml + ``` ### Self-managed CRDs + + Since the Consul on Kubernetes 1.2 introduces `connectInject.apiGateway.manageExternalCRDs`, you must be on at least Consul on Kubernetes v1.2 for this upgrade method. + + If you are unable to tolerate any downtime, you can complete the following steps to upgrade to the native Consul API gateway. If you choose this upgrade option, you must continue to manually install the CRDs necessary for operating the API gateway. -1. Create a values file that installs the version of Consul API gateway that ships with Consul and disables externally-managed CRDs: +1. Create a Helm chart that installs the version of Consul API gateway that ships with Consul and disables externally-managed CRDs: - + ```yaml global: image: hashicorp/consul:1.16 - imageK8S: hashicorp/consul-k8s-control-plane + imageK8S: hashicorp/consul-k8s-control-plane:1.2 connectInject: apiGateway: manageExternalCRDs: false @@ -93,16 +116,43 @@ If you are unable to tolerate any downtime, you can complete the following steps -1. Issue the following command to apply the configuration and complete the installation: + + + You must set `connectInject.apiGateway.manageExternalCRDs` to `false`. If you have external CRDs with legacy installation and you do not set this, you will get an error when you try to upgrade because Helm will try to install CRDs that already exist. + + + +1. Issue the following command to install the new version of API gateway and disables externally-managed CRDs: ```shell-session - $ kubectl apply -f apigw-installation.yaml + $ consul-k8s install -config-file values.yaml ``` 1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information. -1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and rerun it. This completely removes the old gateway controller. +1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller. + + + ```diff + global: + image: hashicorp/consul:1.16 + imageK8S: hashicorp/consul-k8s-control-plane:1.2 + connectInject: + apiGateway: + manageExternalCRDs: false + - apiGateway: + - enabled: true + - image: hashicorp/consul-api-gateway:0.5.4 + - managedGatewayClass: + - enabled: true + ``` + + + + ```shell-session + $ consul-k8s install -config-file values.yaml + ``` ## Upgrade to v0.4.0 From 0794c0dd169badac153f81c978aa8d0e313552f8 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 12 Jun 2023 21:14:27 -0700 Subject: [PATCH 2/5] fix build error --- website/content/docs/api-gateway/upgrades.mdx | 84 +++++++++---------- .../ecs/terraform/secure-configuration.mdx | 4 +- 2 files changed, 44 insertions(+), 44 deletions(-) diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx index 5e10f2ad4b7c..d2637a942b36 100644 --- a/website/content/docs/api-gateway/upgrades.mdx +++ b/website/content/docs/api-gateway/upgrades.mdx @@ -69,20 +69,20 @@ If you are able to tolerate downtime for your applications, you should delete pr 1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller. - + + + ```diff + global: + image: hashicorp/consul:1.15 + imageK8S: hashicorp/consul-k8s-control-plane:1.1 + - apiGateway: + - enabled: true + - image: hashicorp/consul-api-gateway:0.5.4 + - managedGatewayClass: + - enabled: true + ``` - ```diff - global: - image: hashicorp/consul:1.15 - imageK8S: hashicorp/consul-k8s-control-plane:1.1 - - apiGateway: - - enabled: true - - image: hashicorp/consul-api-gateway:0.5.4 - - managedGatewayClass: - - enabled: true - ``` - - + ```shell-session $ consul-k8s install -config-file values.yaml @@ -98,23 +98,23 @@ If you are unable to tolerate any downtime, you can complete the following steps 1. Create a Helm chart that installs the version of Consul API gateway that ships with Consul and disables externally-managed CRDs: - + - ```yaml - global: - image: hashicorp/consul:1.16 - imageK8S: hashicorp/consul-k8s-control-plane:1.2 - connectInject: + ```yaml + global: + image: hashicorp/consul:1.16 + imageK8S: hashicorp/consul-k8s-control-plane:1.2 + connectInject: + apiGateway: + manageExternalCRDs: false apiGateway: - manageExternalCRDs: false - apiGateway: - enabled: true - image: hashicorp/consul-api-gateway:0.5.4 - managedGatewayClass: enabled: true - ``` + image: hashicorp/consul-api-gateway:0.5.4 + managedGatewayClass: + enabled: true + ``` - + @@ -132,23 +132,23 @@ If you are unable to tolerate any downtime, you can complete the following steps 1. After updating all of your `gateway` configurations to use the new controller, you can remove the `apiGateway` block from the Helm chart and upgrade your Consul cluster. This completely removes the old gateway controller. - + + + ```diff + global: + image: hashicorp/consul:1.16 + imageK8S: hashicorp/consul-k8s-control-plane:1.2 + connectInject: + apiGateway: + manageExternalCRDs: false + - apiGateway: + - enabled: true + - image: hashicorp/consul-api-gateway:0.5.4 + - managedGatewayClass: + - enabled: true + ``` - ```diff - global: - image: hashicorp/consul:1.16 - imageK8S: hashicorp/consul-k8s-control-plane:1.2 - connectInject: - apiGateway: - manageExternalCRDs: false - - apiGateway: - - enabled: true - - image: hashicorp/consul-api-gateway:0.5.4 - - managedGatewayClass: - - enabled: true - ``` - - + ```shell-session $ consul-k8s install -config-file values.yaml diff --git a/website/content/docs/ecs/terraform/secure-configuration.mdx b/website/content/docs/ecs/terraform/secure-configuration.mdx index 07031f5490e3..4db6c13abbaa 100644 --- a/website/content/docs/ecs/terraform/secure-configuration.mdx +++ b/website/content/docs/ecs/terraform/secure-configuration.mdx @@ -121,7 +121,7 @@ Follow the instructions described in [Create a task definition](/consul/docs/ecs The secret stores the gossip encryption key that the Consul clients use. - + ```hcl resource "aws_secretsmanager_secret" "gossip_key" { @@ -134,7 +134,7 @@ resource "aws_secretsmanager_secret_version" "gossip_key" { } ``` - + ### Enable secure deployment From 3de61561d24f1dc700418583eb4518c6c853fbe6 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 13 Jun 2023 04:41:58 -0700 Subject: [PATCH 3/5] update callouts to render correctly --- website/content/docs/api-gateway/upgrades.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx index d2637a942b36..15ac54015179 100644 --- a/website/content/docs/api-gateway/upgrades.mdx +++ b/website/content/docs/api-gateway/upgrades.mdx @@ -91,7 +91,9 @@ If you are able to tolerate downtime for your applications, you should delete pr ### Self-managed CRDs - Since the Consul on Kubernetes 1.2 introduces `connectInject.apiGateway.manageExternalCRDs`, you must be on at least Consul on Kubernetes v1.2 for this upgrade method. + + This upgrade method uses `connectInject.apiGateway.manageExternalCRDs`, which was introduced in Consul on Kubernetes v1.2. As a result, you must be on at least Consul on Kubernetes v1.2 for this upgrade method. + If you are unable to tolerate any downtime, you can complete the following steps to upgrade to the native Consul API gateway. If you choose this upgrade option, you must continue to manually install the CRDs necessary for operating the API gateway. @@ -115,13 +117,9 @@ If you are unable to tolerate any downtime, you can complete the following steps ``` - - You must set `connectInject.apiGateway.manageExternalCRDs` to `false`. If you have external CRDs with legacy installation and you do not set this, you will get an error when you try to upgrade because Helm will try to install CRDs that already exist. - - 1. Issue the following command to install the new version of API gateway and disables externally-managed CRDs: ```shell-session From bf70fa9e040a5b37ac5690a62725feb80337506e Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 13 Jun 2023 04:46:23 -0700 Subject: [PATCH 4/5] Add hideClipboard to log messages --- website/content/docs/api-gateway/upgrades.mdx | 8 ++++---- website/content/docs/enterprise/fips.mdx | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx index 15ac54015179..1fc7546c212a 100644 --- a/website/content/docs/api-gateway/upgrades.mdx +++ b/website/content/docs/api-gateway/upgrades.mdx @@ -201,7 +201,7 @@ Complete the following steps after performing standard upgrade procedure. You should receive a response similar to the following: - ```log + ```log hideClipboard "hashicorp/consul-api-gateway:0.4.0" ``` @@ -214,7 +214,7 @@ Complete the following steps after performing standard upgrade procedure. ``` If you have any active `ReferencePolicy` resources, you will receive output similar to the response below. - ```log + ```log hideClipboard Warning: ReferencePolicy has been renamed to ReferenceGrant. ReferencePolicy will be removed in v0.6.0 in favor of the identical ReferenceGrant resource. NAMESPACE NAME default example-reference-policy @@ -339,7 +339,7 @@ Ensure that the following requirements are met prior to upgrading: You should receive a response similar to the following: - ```log + ```log hideClipboard "hashicorp/consul-api-gateway:0.2.1" ``` @@ -493,7 +493,7 @@ Ensure that the following requirements are met prior to upgrading: You should receive the following response: - ```log + ```log hideClipboard "hashicorp/consul-api-gateway:0.1.0" ``` diff --git a/website/content/docs/enterprise/fips.mdx b/website/content/docs/enterprise/fips.mdx index 6ad145886be2..5f5cf281967a 100644 --- a/website/content/docs/enterprise/fips.mdx +++ b/website/content/docs/enterprise/fips.mdx @@ -87,13 +87,13 @@ Consul's FIPS 140-2 products on Windows use the CNGCrypto integration in Microso To ensure your build of Consul Enterprise includes FIPS support, confirm that a line with `FIPS: Enabled` appears when you run a `version` command. For example, the following message appears for Linux users: -```shell-session hideClipboard +```log hideClipboard FIPS: FIPS 140-2 Enabled, crypto module boringcrypto ``` The following message appears for Windows users: -```shell-session hideClipboard +```log hideClipboard FIPS: FIPS 140-2 Enabled, crypto module cngcrypto ``` @@ -121,7 +121,7 @@ Similarly, on a FIPS Windows binary, run `go tool nm` on the binary to get a sym On both Linux and Windows non-FIPS builds, the search output yields no results. -### Compliance Validation +### Compliance validation A Lab, authorized by the U.S. Government to certify FIPS 140-2 compliance, is in the process of verifying that Consul Enterprise and its related packages are compliant with the requirements of FIPS 140-2 Level 1. From 2ef136b908f85085acf5bfd883966cb1df4defc3 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 13 Jun 2023 13:21:19 -0700 Subject: [PATCH 5/5] Added clarification around consul k8s and crds --- website/content/docs/api-gateway/upgrades.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx index 1fc7546c212a..610dc0acee0c 100644 --- a/website/content/docs/api-gateway/upgrades.mdx +++ b/website/content/docs/api-gateway/upgrades.mdx @@ -7,7 +7,7 @@ description: >- # Upgrade Consul API gateway for Kubernetes -Since Consul v1.15, the Consul API gateway is a native feature within the Consul binary and is installed during the normal Consul installation process. Since Consul v1.16, the CRDs necessary for using the Consul API gateway for Kubernetes are also included. You can install Consul v1.16 using the Consul Helm chart v1.2 and later. Refer to [Install API gateway for Kubernetes](/consul/docs/api-gateway/install) for additional information. +Since Consul v1.15, the Consul API gateway is a native feature within the Consul binary and is installed during the normal Consul installation process. Since Consul on Kubernetes v1.2 (Consul v1.16), the CRDs necessary for using the Consul API gateway for Kubernetes are also included. You can install Consul v1.16 using the Consul Helm chart v1.2 and later. Refer to [Install API gateway for Kubernetes](/consul/docs/api-gateway/install) for additional information. ## Introduction