Resource upgrade

This topic describes how to upgrade API gateway Kubernetes resource types when a Consul release requires it.

Overview

Consul 2.0.0 introduces API gateway resource types in the consul.hashicorp.com API group. These resource types improve compatibility with OpenShift Container Platform (OCP) 4.19 and later, and support TCPRoute in environments where the platform manages Gateway CRDs.

Requirements

A Consul deployment in Kubernetes.

Prerequisites

kubectl tool should be instaleld for non-OCP clusters and oc for OCP clusters.
Back up Gateways, HTTPRoutes, TCPRoutes, and ReferenceGrants in your cluster. For example, run the following commands to create namespace-level, resource-specific backup files:

$ mkdir -p gateway-resource-backup && \
  for ns in $(oc get ns -o jsonpath='{.items[*].metadata.name}'); do \
    oc get gateways -n "$ns" -o yaml > "gateway-resource-backup/${ns}-gateways.yaml"; \
    oc get httproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-httproutes.yaml"; \
    oc get tcproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-tcproutes.yaml"; \
    oc get referencegrants -n "$ns" -o yaml > "gateway-resource-backup/${ns}-referencegrants.yaml"; \
  done

$ mkdir -p gateway-resource-backup && \
  for ns in $(kubectl get ns -o jsonpath='{.items[*].metadata.name}'); do \
    kubectl get gateways -n "$ns" -o yaml > "gateway-resource-backup/${ns}-gateways.yaml"; \
    kubectl get httproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-httproutes.yaml"; \
    kubectl get tcproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-tcproutes.yaml"; \
    kubectl get referencegrants -n "$ns" -o yaml > "gateway-resource-backup/${ns}-referencegrants.yaml"; \
  done

Additional info

If you use GoDaddy or Route53 as your DNS provider and have a CNAME record pointing to the API gateway, update that CNAME record when switching from the Standard API gateway to the Consul API gateway.
When you upgrade to Consul 2.0, Consul automatically generates and applies manifests based on your gateway selection:
- Standard API gateway: Consul generates manifests updated to the v1 version of the gateway.networking.k8s.io API group and applies them.
- Consul API gateway: Consul generates and applies manifests for both the Standard API gateway and the Consul API gateway, creating both gateways simultaneously. This gives you time to update your CNAME record in your DNS provider (such as GoDaddy or Route53) before decommissioning the Standard API gateway.

Upgrade scenarios

If your cluster does not use TCPRoute, you can keep existing gateway resources. If your cluster uses TCPRoute, upgrade to the new API group in one of these cases:

OCP clusters that use TCPRoute and upgrade from OCP 4.18 to 4.19 or later.
Move to the consul.hashicorp.com API group to maintain compatibility with OCP 4.19 and later.
Non-OCP Kubernetes clusters that use TCPRoute and platform-managed Gateway CRDs.
Move to the consul.hashicorp.com API group to maintain compatibility.

Upgrade flow charts

Use the following flow charts to choose the correct path for your upgrade.

Kubernetes upgrade flow: platform upgrade not involved

platform upgrade not involved flow

Kubernetes upgrade flow: platform upgrade involved

platform upgrade involved flow

OpenShift Container Platform (OCP) upgrade steps

The upgrade process

To prepare for an OCP upgrade from 4.18 to 4.19+ you can follow these steps:

Make sure the OCP cluster s running OCP 4.18 or earlier and the target version is OCP 4.19 or later.
Verify Consul is deployed in the Cluster
Validate if the gateway CRDs under API group gateway.networking.k8s.io are pre-installed in the cluster. If pre-installed, set global.installK8sNetworkingCRDs: false.
Make sure Gateway-related resources are backed up before the upgrade.

The backup and upgrade process involves these resource types:

After all the preparations are complete, use the flowchart to identify the specific steps for your upgrade.

Dual gateway new installation of Consul and OCP upgrade flow

Finally, follow the steps in the section below according to your configuration.

Upgrade steps

OpenShift upgrade from 4.18 to 4.19+

Run helm upgrade with one of the following values.yaml configurations as per requirement.

values.yaml

global:
  installK8sNetworkingCRDs: true
  generateManifests: true
  openshift:
    enabled: true
    crds:
      enableTcpRoute: false

Verify the access to the application.

Standard API gateway

Verify access to the application through the gateway.

$ oc get cgtw -A

 NAMESPACE   NAME                 CLASS                 ADDRESS   PROGRAMMED   AGE
 consul      api-gateway-consul   consul-custom-class             True         72m

Consul API gateway
```
$ oc get gtw -A

 NAMESPACE   NAME          CLASS    ADDRESS   PROGRAMMED   AGE
 consul      api-gateway   consul             True         3d19h
```
- You may see two gateways initially. Verify application access through both gateways.
- Update your DNS (for example, Route53) to point to Consul DNS.

Back up generated manifests from the PVC.
Follow the OpenShift documentation to complete the platform upgrade, including:
- Deleting Gateway CRDs.
- Approving adminAck, if required.
Verify the access to the application after platform upgrade.
- Standard API gateway
  - Apply the copied manifests taken from step 3.
  - After the gateway is ready, verify application access.
- Consul API gateway
  - Verify application access.
  - If application access fails, run helm upgrade with:
    global: installK8sNetworkingCRDs: false openshift: enabled: true upgradeTo419From418: false crds: enableTcpRoute: false consulapi: enabled: true

Non-OCP upgrade flow: platform upgrade not involved

Run helm upgrade with one of the following values.yaml configurations.

values.yaml

global:
  installK8sNetworkingCRDs: true
  generateManifests: true
  crds:
    enableTcpRoute: true

Verify application access.
Access the application using the Standard API gateway.
Back up generated manifests from the PVC.

Non-OCP upgrade flow: platform upgrade involved

This section assumes the current platform version does not manage Gateway CRDs, and the upgraded platform version does.

Run helm upgrade with one of the following values.yaml configurations.

values.yaml

global:
  installK8sNetworkingCRDs: true
  generateManifests: true
  crds:
    enableTcpRoute: false

Verify access to the application.
- Standard API gateway Verify access to the application through the gateway.
- Consul API gateway
  - You may see two gateways initially. Verify access through both gateways.
  - Update your DNS (for example, Route53) to point to Consul DNS.
  - Delete the Standard API gateway and related objects.
Back up generated manifests from the PVC.
Upgrade the platform following the official documentation of the platform.
Verify access to the application.
- Standard API gateway
  Verify access to the application through the gateway.
- Consul API gateway
  - Verify access to the application through the gateway.
  - If the application is not accessible, run helm upgrade with:
    global: installK8sNetworkingCRDs: false crds: enableTcpRoute: false consulapi: enabled: true

Rollback

Rollback from Consul 2.x to 1.9 or earlier than 1.8.14

There are two ways to roll back using Helm.

Option 1 — Direct version rollback

Run the helm rollback command to roll back to a previous release directly.

$ helm rollback --force-conflicts <release-number>

Option 2 — Explicit Helm values rollback

Export the Helm values from the target version you want to roll back to.
This example uses version 1.9.4.
```
$ helm show values hashicorp/consul --version 1.9.4 > values.yaml
```
Update all relevant fields in values.yaml as needed.

Run the helm upgrade command to upgrade to the target version using the updated values file.

$ helm upgrade --install <release-name> hashicorp/consul \
    --version 1.9.4 \
    --namespace <namespace> \
    --values values.yaml \
    --force-conflicts