Resource upgrade

This topic describes what steps you need to take to complete the Kubernetes resource types upgrade, when a new version of Consul requires it.

Overview

Kubernetes resources for Consul provide a way to configure and manage Consul on Kubernetes clusters. Consul 2.0.0 provides new resource types that offer enhanced functionality and improved compatibility with OpenShift Container Platform (OCP) versions 4.19 and above. These new resource types are part of the consul.hashicorp.com API group and are designed to replace the older resource types that previous versions of Consul used.

Requirements

OpenShift Container Platform (OCP) 4.19 or later
Consul 2.0.0 or later

Update the API gateway resources from the current API resource group gateway.networking.k8s.io to the new consul.hashicorp.com. This change is necessary to take advantage of the new features and improvements in the API gateway functionality on specific Kubernetes environments, like OpenShift.

Upgrade scenarios

Kubernetes clusters not using the TCPRoute resource can, but do not need to, upgrade their API gateway resources to the new API group. This leaves two cases:

OpenShift Container Platform (OCP) Kubernetes clusters that use TCPRoutes and want to upgrade their cluster from 4.18 to 4.19+.
Moving to the new consul.hashicorp.com custom API resource group is required to ensure compatibility with OpenShift 4.19+.
Any Kubernetes cluster that uses TCPRoutes and wants to use the new custom API resource group.
Moving to the new consul.hashicorp.com custom API resource group is not required, but we do recommend it.

Upgrade steps

To upgrade your Kubernetes resources for Consul, follow these steps:

Update your Consul Helm chart values.
This Helm upgrade generates manifests and applies the stable v1 API version by replacing the v1alpha API version of the gateway.networking.k8s.io resources and then applies the manifests.
Add this configuration to your values.yaml file.
```
openshift:
    enabled: true
    upgradeTo419From418: true
    crds:
        enableTcpRoute: false
        consulapi:
            enabled: true
```
If openshift.crds.enableTcpRoute is true, then install the TCPRoute CRD under the gateway.networking.k8s.io. If openshift.crds.consulapi.enabled is true, then install all the CRDs under the API group consul.hashicorp.com.
Make backups of all the manifests after the Consul upgrade before proceeding to the OCP upgrade.

Delete the old CRDs and resources.

Run the following command to delete the old CRDs:

for i in gateways gatewayclasses httproutes grpcroutes tcproutes referencegrants; \
do oc delete crd $i.gateway.networking.k8s.io; \
done

Upgrade your OpenShift cluster to version 4.19 or later.