Upgrade legacy installations
This guide upgrades setups that were installed using the gloo-mesh-enterpise
, gloo-mesh-agent
, and other included Helm charts, or using meshctl
version 2.2 or earlier. In Gloo Gateway 2.3 and later, these Helm charts are considered legacy. Migrate your legacy installation to the new gloo-platform
Helm chart.
Upgrade Gloo Platform minor and patch versions for the management server and agent in each cluster.
During the upgrade, the data plane continues to run, but you might not be able to modify the configurations through the management plane. Because zero downtime is not guaranteed, try testing the upgrade in a staging environment before upgrading your production environment.
You must always upgrade the Gloo management server before upgrading the Gloo agent to avoid unexpected behavior. Note that only n-1
minor version skew is supported between the management server and the agent. For more information, see the Skew policy.
Looking to update certain Helm chart values but not the version? See Modifying Helm chart values.
Before you begin
-
Review the changelog. Focus especially on any Breaking Changes that might require a different upgrade procedure.
- AWS Lambda integration: In 2.3, the Gloo custom resources for the AWS Lambda integration are changed in the following breaking ways. If you used the AWS Lambda integration in 2.2, you must create copies of your existing resources in the new format before you upgrade. After the upgrade is complete, you can delete the old resources in the outdated format. To see the updated format, check out the Lambda integration documentation.
- The
CloudProvider
andCloudResources
CRs are moved from thenetworking.gloo.solo.io/v2
API group to theinfrastructure.gloo.solo.io/v2
API group. You must delete the oldcloudproviders.networking.gloo.solo.io
andcloudresources.networking.gloo.solo.io
CRDs before you upgrade your installation. - The
logicalName
field is removed from theCloudResources
CR. - Routes for Lambda functions in
RouteTable
CRs now use a new destination type,awsLambda
. - The
WRAP_AS_API_GATEWAY
,UNWRAP_AS_API_GATEWAY
, andUNWRAP_AS_ALB
transformation settings are removed from theRouteTable
CR, as the transformation functionality from these settings is now included in theREQUEST_DEFAULT
andRESPONSE_DEFAULT
transformations.
- The
- AWS Lambda integration: In 2.3, the Gloo custom resources for the AWS Lambda integration are changed in the following breaking ways. If you used the AWS Lambda integration in 2.2, you must create copies of your existing resources in the new format before you upgrade. After the upgrade is complete, you can delete the old resources in the outdated format. To see the updated format, check out the Lambda integration documentation.
-
Check that your underlying Kubernetes platform runs a supported version for the Gloo version that you want to upgrade to.
- Review the supported versions.
- Compare the supported version against the version of Kubernetes that you run in your clusters.
- If necessary, upgrade Kubernetes. Consult your cluster infrastructure provider.
-
In your terminal, set the following environment variables to use in the subsequent steps, such as your target Gloo version.
# Set the Gloo Gateway version as an environment variable. The latest version is used as an example. You can find other versions in the Changelog documentation. export UPGRADE_VERSION=2.3.22 # Save the kubeconfig contexts for your clusters as environment variables. Run
kubectl config get-contexts
, look for your cluster in theCLUSTER
column, and get the context name in theNAME
column. export MGMT_CONTEXT=<management_cluster_config> export REMOTE_CONTEXT=<remote_cluster_config> # Set the gloo-mesh namespace. export NAMESPACE=gloo-mesh # Set your Gloo Gateway license key as an environment variable. If you do not have one, contact an account representative. export GLOO_GATEWAY_LICENSE_KEY=<your-key>
Step 1: Upgrade the CRDs for your management cluster
- Remove CRDs that are deprecated in 2.3.
kubectl --context $MGMT_CONTEXT delete crd apischemas.apimanagement.gloo.solo.io kubectl --context $MGMT_CONTEXT delete crd cloudproviders.networking.gloo.solo.io kubectl --context $MGMT_CONTEXT delete crd cloudresources.networking.gloo.solo.io
- Update the Helm repo in the management cluster for Gloo.
helm repo add gloo-mesh-enterprise https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-enterprise helm repo update --kube-context $MGMT_CONTEXT
- Pull the latest Gloo Helm chart files.
helm pull gloo-mesh-enterprise/gloo-mesh-enterprise --kube-context $MGMT_CONTEXT --version $UPGRADE_VERSION --untar
- Apply the Gloo custom resource definitions (CRDs) on your management cluster.
kubectl apply --context $MGMT_CONTEXT -f gloo-mesh-enterprise/charts/gloo-mesh-crds/crds/
If you upgrade to a release such as 2.4.6, you might see an error such as "error":"no matches for kind \"CertificateRequest\" in version \"certificates.mesh.gloo.solo.io/v1\""
. The management cluster also needs CRDs for the Gloo agent. Continue to Step 2, and apply the agent CRDs on your management cluster as well as your remote clusters.
Step 2: Upgrade the CRDs for each workload cluster
- Update the Helm repo in your workload cluster for Gloo. If you have a single cluster, the
$REMOTE_CONTEXT
is the same as the$MGMT_CONTEXT
.helm repo add gloo-mesh-agent https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-agent helm repo update --kube-context $REMOTE_CONTEXT
- Pull the latest Gloo agent Helm chart files.
helm pull gloo-mesh-agent/gloo-mesh-agent --version $UPGRADE_VERSION --kube-context $REMOTE_CONTEXT --untar
- If you used the AWS Lambda integration in Gloo Gateway 2.2, delete the deprecated CRDs.
kubectl --context $REMOTE_CONTEXT delete crd cloudproviders.networking.gloo.solo.io kubectl --context $REMOTE_CONTEXT delete crd cloudresources.networking.gloo.solo.io
- Apply the Gloo CRDs on each workload cluster.
kubectl apply --context $REMOTE_CONTEXT -f gloo-mesh-agent/charts/gloo-mesh-crds/crds kubectl apply --context $REMOTE_CONTEXT -f gloo-mesh-agent/charts/ext-auth-service/crds kubectl apply --context $REMOTE_CONTEXT -f gloo-mesh-agent/charts/rate-limiter/crds
- Repeat steps 3 and 4 for each workload cluster.
Step 3: Get your Helm chart values
As part of the upgrade, you can update or reuse the Helm chart values for your Gloo management server, agent, and any add-ons that you might have such as rate limiting and external authentication services.
–values
flag or with –set
flags. Otherwise, any previous custom values that you set might be overwritten. In single cluster setups, this might mean that your Gloo agent and ingress gateways are removed.-
Get your Helm chart values configuration file for your current version. Review the following options:
- Reuse the existing Helm chart values configuration file for your current installation
- Get the Helm chart values for your current installation
- Show the default Helm chart values for the current version
When you installed Gloo, you might have used a Helm chart values configuration file to customize your installation. This file might be stored in your CI/CD pipeline, such as in a Git repository. The installation instructions used the following file names. Helm installations:
- Single cluster: Both Gloo management server and agent in
single-cluster-values.yaml
, based on this sample values file. - Multicluster: Separate installations for the Gloo management server and agent.
- Management server:
mgmt-server-values.yaml
, based on this sample values file. - Agent:
agent-values.yaml
, based on this sample values file.
- Management server:
- Rate limiting and external authentication add-ons:
values.yaml
.
Getting started or
meshctl
installations:- Single cluster: Both Gloo management server and agent in
gs-single-values.yaml
, based on this sample values file. - Multicluster:
values-register.yaml
. Note that this sample values file was used only for the agent installation, because default Helm values were used for the management server installation. To get a values file for the management server installation, you can runhelm -n gloo-mesh get all gloo-mgmt --kube-context $MGMT_CONTEXT > values-mgmt-plane-env.yaml
, and use the values listed afterCOMPUTED VALUES:
for your Helm values file.
If you do not have the original values files that you used at installation time, you can get the values for the current Helm release in your clusters.
- Get the values for the current Helm releases.
- Management server: Note that if the release name
gloo-mgmt
is not found, your Helm release might be namedgloo-mesh-enterprise
instead.helm -n gloo-mesh get all gloo-mgmt --kube-context $MGMT_CONTEXT > values-mgmt-plane-env.yaml open values-mgmt-plane-env.yaml
- Agent: Note that if the release name
gloo-agent
is not found, your Helm release might be namedgloo-mesh-agent
instead.helm -n gloo-mesh get all gloo-agent --kube-context $REMOTE_CONTEXT > values-data-plane-env.yaml open values-data-plane-env.yaml
- Rate limiting and external authentication add-ons:
helm -n gloo-mesh get all gloo-agent-addons --kube-context $REMOTE_CONTEXT > values.yaml open values.yaml
- Management server: Note that if the release name
- In each file, delete the lines up to and including the
USER-SUPPLIED VALUES:
line, and delete all lines including and after theCOMPUTED VALUES
line. Save the file.
You can get the default values for the Helm chart at the version of your installation, which you can check by running
meshctl version
.- Management server:
helm show values gloo-mesh-enterprise/gloo-mesh-enterprise --version $CURRENT_VERSION > mgmt-server-values.yaml
- Agent:
helm show values gloo-mesh-agent/gloo-mesh-agent --version $CURRENT_VERSION > agent-values.yaml
-
Compare your current Helm chart values with the version that you want to upgrade to. You can get a values file for the upgrade version with the
helm show values
command.- Management server:
helm show values gloo-mesh-enterprise/gloo-mesh-enterprise --version $UPGRADE_VERSION > mgmt-server-values-env.yaml
- Agent:
helm show values gloo-mesh-agent/gloo-mesh-agent --version $UPGRADE_VERSION > agent-values-env.yaml
- Management server:
-
Review the changelog for any Helm Changes that might require modifications to your Helm chart.
-
Edit the Helm chart values file or prepare the
--set
flags to make any changes that you want. If you do not want to use certain settings, comment them out.For example, you might modify the following settings during an upgrade.
- The Gloo
image.tag
value for the version that you want to upgrade to. - Istio
images.hub
andimages.tag
fields for the Solo distribution of Istio that you want to use. - The
relay
section for custom certificates to use to establish mTLS between the management server and agent. - The
rate-limiter
andext-auth-service
sections in the agent chart.
Need to make changes after you upgrade? You can update these settings later. For more information, see Modify Helm chart values.
- The Gloo
Step 4: Upgrade and verify the Helm installation
-
Upgrade the Gloo Gateway Helm installation. Make sure to update any
--set
or--values
options, such as the values file name. For example, if you installed Gloo in a single-cluster environment usingmeshctl
, your values file might be namedgs-single-values.yaml
instead. Note: If the release namegloo-mgmt
is not found, your Helm release might be namedgloo-mesh-enterprise
instead.helm upgrade gloo-mgmt gloo-mesh-enterprise/gloo-mesh-enterprise \ --namespace gloo-mesh \ --set glooGatewayLicenseKey=${GLOO_GATEWAY_LICENSE_KEY} \ --kube-context=${MGMT_CONTEXT} \ --version ${UPGRADE_VERSION} \ --values values-mgmt-plane-env.yaml
-
Multicluster installations: Upgrade the Helm installation in your workload cluster. Make sure to update any
--set
or--values
options, such as the values file name. For example, if you installed Gloo in a multicluster environment usingmeshctl
, your values file might be namedvalues-register.yaml
instead. Note: If the release namegloo-agent
is not found, your Helm release might be namedgloo-mesh-agent
instead.helm upgrade gloo-agent gloo-mesh-agent/gloo-mesh-agent \ --kube-context=${REMOTE_CONTEXT} \ --namespace gloo-mesh \ --version ${UPGRADE_VERSION} \ --values values-data-plane-env.yaml
-
Optional: Upgrade the Gloo external auth or rate limiting services. If you already enabled these services in the single cluster or agent installation, or you do not use these services, you can skip this step.
helm upgrade gloo-agent-addons gloo-mesh-agent/gloo-mesh-agent \ --kube-context=${REMOTE_CONTEXT} \ --namespace gloo-mesh-addons \ --version ${UPGRADE_VERSION} \ --values values.yaml
-
Multicluster installations: Repeat steps 2 - 3 for each workload cluster.
-
Optional: Check that the Gloo management and agent resources are connected. See Step 1 of Debug the management server and relay connection.
-
Confirm that the server components such as
gloo-mesh-mgmt-server
run the version that you upgraded to.meshctl version --kubecontext ${MGMT_CONTEXT}
Example output:
"server": [ { "Namespace": "gloo-mesh", "components": [ { "componentName": "gloo-mesh-mgmt-server", "images": [ { "name": "gloo-mesh-mgmt-server", "domain": "gcr.io", "path": "gloo-mesh-mgmt-server", "version": "2.3.22" } ] },
-
Confirm that the agent components such as
gloo-mesh-agent
run the version that you upgraded to. If you have a single cluster, the$REMOTE_CONTEXT
is the same as the$MGMT_CONTEXT
.meshctl version --kubecontext ${REMOTE_CONTEXT}
Example output:
{ "componentName": "gloo-mesh-agent", "images": [ { "name": "gloo-mesh-agent", "domain": "gcr.io", "path": "gloo-mesh/gloo-mesh-agent", "version": "2.3.22" } ] },
Next steps
Now that you upgraded Gloo, you must upgrade your meshctl
CLI to the matching version. Depending on the Gloo version support, you might also want to upgrade Kubernetes in your clusters.
- Upgrade the
meshctl
CLI to the same version of Gloo. - Optional: If the new version of Gloo supports a more recent version of Kubernetes, you can upgrade Kubernetes on your cluster. For more information, consult your cluster infrastructure provider.
Update your Gloo license
Before your Gloo license expires, you can update the license by patching the license key secret. If you use Gloo Gateway along with other Gloo products such as Gloo Mesh and Gloo Network, you can also update those licenses.
To update your license, see the Licensing documentation.