Migrating Distributed Gateway from 6.1.x to the latest versions

Edit online

Z APM Connect introduces significant new capabilities, including OpenTelemetry support, along with major updates to packaging and deployment processes. If you plan an upgrade, follow the streamlined migration process in this section to move from an existing 6.1.1.x Distributed Gateway to a newer release.

New versioning format for Distributed Gateway

Starting with Z APM Connect 6.2.0.x, the Distributed Gateway uses a new version format based on year.month.iteration. For example, version 25.2.0 means that the image was released in February 2025.

Single packaging for standalone and cluster deployments

For 6.1.1.x Distributed Gateway, two separate installation packages (.tar.gz) were provided for standalone docker deployments and cluster-based deployments.

In the newer version, the Distributed Gateway is distributed as a single unified package that includes configuration options for both standalone and cluster environments.

To download the Distributed Gateway package, go to Fix Central.

Understand the packaging and configuration changes

When you extract the 25.2.0 or later Distributed Gateway .tar.gz package from Fix Central, note the following changes:

  • Use the new cluster directory- This directory contains the values.yaml file, Helm chart, and a log collection script for Kubernetes or Red Hat OpenShift deployments. It replaces the production directory that is used in 6.1.1.x.
  • Use the new standalone directory- This directory provides scripts and configuration for single-machine deployments with Docker or Podman. Podman support is available starting in 25.2.0.
  • Use the unified images directory- This directory contains the same images for both standalone and cluster deployments. For cluster environments, you can also pull these images from the IBM Container Registry.
  • Use the new zapm-exporter image- This image supports OpenTelemetry integration.
  • Do not use the sandbox directory- The sandbox option is no longer available. For proofs of concept, testing, or environments that handle fewer than 1,000 transactions per second, use the standalone deployment.
  • Use Helm for deployments- Manifest-based deployment files are no longer provided. In 6.1.1.x, Kubernetes deployments used manifests, while Red Hat OpenShift required Helm. Starting with 25.2.0, use Helm for both Kubernetes and Red Hat OpenShift deployments. If you previously used manifests, move your configuration to values.yaml and deploy with the Helm chart included in the package.