Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Propose new changes to APIgw upgrade instructions #17693

Merged
merged 8 commits into from
Jun 27, 2023
Merged

Propose new changes to APIgw upgrade instructions #17693

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a31c3b3
Propose new changes to APIgw upgrade instructions
im2nguyen Jun 13, 2023
40e2659
Merge branch 'main' into docs/update-apigw-upgrade-instructions
im2nguyen Jun 13, 2023
0794c0d
fix build error
im2nguyen Jun 13, 2023
d3d9f4f
Merge branch 'docs/update-apigw-upgrade-instructions' of ssh://github…
im2nguyen Jun 13, 2023
3de6156
update callouts to render correctly
im2nguyen Jun 13, 2023
bf70fa9
Add hideClipboard to log messages
im2nguyen Jun 13, 2023
2ef136b
Added clarification around consul k8s and crds
im2nguyen Jun 13, 2023
b7f65ce
Merge branch 'main' into docs/update-apigw-upgrade-instructions
im2nguyen Jun 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 75 additions & 27 deletions website/content/docs/api-gateway/upgrades.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -47,62 +47,110 @@ 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.

<CodeBlockConfig filename="values.yaml">

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

</CodeBlockConfig>

```shell-session
$ consul-k8s install -config-file values.yaml
```

### Self-managed CRDs

<Note>

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.

</Note>

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:

<CodeBlock heading="apigw-installation.yaml">
<CodeBlockConfig filename="values.yaml" highlight="2-3,5-6">

```yaml
global:
image: hashicorp/consul:1.16
imageK8S: hashicorp/consul-k8s-control-plane
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
```

</CodeBlock>
</CodeBlockConfig>

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 apply the configuration and complete the installation:
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.

<CodeBlockConfig filename="values.yaml">

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

</CodeBlockConfig>

```shell-session
$ consul-k8s install -config-file values.yaml
```

## Upgrade to v0.4.0

Expand Down Expand Up @@ -153,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"
```

Expand All @@ -166,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
Expand Down Expand Up @@ -291,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"
```

Expand Down Expand Up @@ -445,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"
```

Expand Down
4 changes: 2 additions & 2 deletions website/content/docs/ecs/terraform/secure-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<CodeBlock>
<CodeBlockConfig>

```hcl
resource "aws_secretsmanager_secret" "gossip_key" {
Expand All @@ -134,7 +134,7 @@ resource "aws_secretsmanager_secret_version" "gossip_key" {
}
```

</CodeBlock>
</CodeBlockConfig>

### Enable secure deployment

Expand Down
6 changes: 3 additions & 3 deletions website/content/docs/enterprise/fips.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down Expand Up @@ -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.