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. For upgrade instructions, see Upgrade Gloo Gateway.
Review the changelog for Gloo Platform releases. Changelog entries are categorized into the following types:
- Dependency Bumps: The version for a dependency in Gloo Platform is bumped in this release. Be sure to check for any Breaking Change entries that accompany a dependency bump.
- Breaking Changes: An API is changed in a way that is not backwards compatible, such as a changed format for an API field. Occasionally, a breaking change occurs for the process to upgrade Gloo, in which the changelog entry indicates how to use the new upgrade process.
- Helm Changes: The installation Helm chart is changed. If this change is not backwards compatible, an accompanying Breaking Change entry is indicated for the release.
- New Features: A new feature is implemented in the release.
- Fixes: A bug is resolved in this release.
The Solo team fixes bugs, delivers new features, and makes changes on a regular basis as described in the changelog. Some issues, however, might impact many users for common use cases. These known issues are as follows:
- Cluster names: Do not use underscores (
_) in the names of your clusters or in the
kubeconfigcontext for your clusters.
- AWS Lambda: In Gloo Gateway 2.3, the Gloo custom resources for the AWS Lambda integration are changed in breaking ways. Additionally, you must delete the old
cloudresources.networking.gloo.solo.ioCRDs before you upgrade your installation. For more information, see the AWS Lambda integration notes in the version 2.3 migration guide.
- OTel pipeline:
- If you set up the Gloo OpenTelemetry (OTel) pipeline prior to Gloo Gateway version 2.3, your installation continues to use the OTel pipeline after you upgrade to 2.3. However, due to a service name change for telemetry components, you must update the telemetry gateway IP address that the collector agents send metrics to. For more information, see the OTel pipeline notes in the version 2.3 migration guide.
- FIPS-compliant builds are not currently supported for the OTel collector agent image.
- Istio version 1.17 does not support the Gloo legacy metrics pipeline. If you run the legacy metrics pipeline, before you upgrade or deploy gateway proxies with Istio 1.17, be sure that you set up the Gloo OpenTelemetry (OTel) pipeline instead in your new or existing Gloo Gateway installation.
- For any FIPS-compliant builds, you must use the
-patch1versions of the latest Istio versions published by Solo, such as
1.17.2-patch1-solo-fipsfor Gloo Istio version 1.17. These patch versions fix a FIPS-related issue introduced in the upstream Envoy code.
- Istio versions 1.14.0 - 1.14.3 have a known issue about unused endpoints failing to be deleted. Additionally, version 1.14.4 has a known issue about short hostnames causing Kubernetes service and ServiceEntry conflicts. Both issues are resolved in Istio 1.14.5.
- Istio versions 1.13.0 - 1.13.3 have a known issue about service entry hostname expansion. The issue is resolved in Istio 1.13.4.
- GraphQL: For known issues regarding the GraphQL module, see the GraphQL documentation.
- Bring your own Prometheus: If you used your own Prometheus instance to scrape metrics in your cluster instead of using the built-in Prometheus, enter the Prometheus URL that your instance is exposed on, such as
http://kube-prometheus-stack-prometheus.monitoring:9090, in the
common.prometheusUrlfield. You can get this value from the
--web.external-urlfield in your Prometheus Helm values file or by selecting Status > Command-Line-Flags from the Prometheus UI. Do not use the FQDN for the Prometheus URL.