Upgrade GoodData.CN

As an administrator, before upgrading to a new version, review the version specific upgrades section to identify any intermediate versions between your current version and the target version that require additional upgrade steps. If such versions exist, follow the corresponding upgrade instructions in sequence before proceeding.

Once version-specific upgrades are complete, or if none are required, you can upgrade GoodData.CN to a new official release using the following command:

helm upgrade --namespace gooddata-cn --version <gooddata-cn-release> \
    -f gdcn-values.yaml gooddata-cn gooddata/gooddata-cn

When upgrading, ensure you reapply your custom configurations from the gdcn-values.yaml file, saved during the original installation. This prevents your settings from being overwritten by default values. You can also edit this file to opt into new features, see Feature Flags.

Version Specific Upgrades

Certain upgrades require additional steps. For instance, if you are on version 3.1 and wish to upgrade to 3.16, you must first upgrade to version 3.10 by following the 3.10 upgrade guide, before proceeding to 3.16.

Below are the version-specific upgrade instructions starting from version 3.0.0:

Version 4.15.0

The auth-service microservice is removed in this release. Its responsibilities were moved to other services in earlier versions: the API Gateway (api-gw) now serves the OIDC sign-in flow, Dex user management, and /api/v1/schemas/auth, and metadata-api serves /api/v1/profile and /api/v1/actions/invite.

Upgrade to 4.14 First

If you run 4.13.x or older, upgrade to 4.14 before upgrading to 4.15. Do not jump directly.

In 4.13.x and older, the API Gateway forwards /api/v1/profile, /api/v1/actions/invite, and /api/v1/auth/* to the auth-service Service. During a direct upgrade to 4.15, the auth-service Deployment and Service are removed while the outgoing API Gateway pods are still running and still forwarding to them. Until the API Gateway rollout completes, /api/v1/profile — the call the user interface makes right after sign-in — returns 502 or 503, which looks like a broken login.

4.14 already routes profile and invitations to metadata-api and serves the auth schemas and user endpoints from the API Gateway itself, so it needs nothing from auth-service. Upgrading 4.14 to 4.15 requires no intermediate version.

Sign-in itself is not affected by this change in any version. Dex is a separate deployment and is unaffected, and /appLogin, /logout, the OIDC callback, and the authorization-server endpoints are served by the API Gateway.

Remove Leftover authService Values

Any authService: block left in your gdcn-values.yaml is ignored from 4.15 on. The chart does not validate or reject it, so a stale override fails silently. Remove the block.

One override needs to be moved rather than deleted. If you enabled invitations, rename the key:

# Before (4.14 and older)
authService:
  pulsar:
    inviteGenerator:
      enabled: true

# From 4.15
metadataApi:
  pulsar:
    inviteGenerator:
      enabled: true

The Pulsar topic and message TTL are unchanged. If you do not move it, POST /api/v1/actions/invite responds with 403, which reads as a permission problem rather than a missing configuration value.

For details, see the 4.15.0 release notes.

Version 4.13.0

This release fixes a high-severity vulnerability in the API Gateway. No additional upgrade steps are required, but if you are upgrading from an affected version, review the exposure details and the verification guidance below.

Unauthorized Access to Internal Diagnostic Endpoints

The API Gateway restricts internal diagnostic endpoints, namely heap dump and thread dump, to an internal probe connector so that they are not reachable from the public network path. The gateway determined which network port a request arrived on based on client-supplied request data, which an unauthenticated remote caller could manipulate to bypass the restriction. A specially crafted request could return a full JVM heap dump.

A heap dump of the gateway can contain:

• Internal database credentials and the encryption keyset
• Cached identity provider client secrets
• Session and OIDC access, refresh, and ID tokens
• API token material in flight

The port check no longer depends on client-supplied data, and the heap dump and thread dump endpoints have been removed from the gateway. Standard health checks continue to work as expected on the intended probe connector.

GoodData.CN versions 3.46.0 through 4.12.1 are affected. The fix is also available in the 4.10 LTS line starting with version 4.10.3.

GoodData identified this issue through its internal security audit process; it was not reported externally.

Verify Your Own Environment

To check your own deployment, search the gateway container logs for successful (HTTP 200) requests to the diagnostic paths. For example, using Grafana/Loki:

{container="gateway-api-gw"} |~ "/health/(heap|thread)dump" | json | state="200"

Legitimate internal health checks from kubelet probes never carry an x-forwarded-for header. Treat any matching request that does carry this header as an external caller and investigate it.

Version 4.12.1

GoodData.CN 4.12.0 contains a critical issue that can cause some analytical results to change unexpectedly. Do not deploy 4.12.0. Upgrade directly to 4.12.1, which fixes the issue.

The 4.12 line ships the new unified AI Assistant experience. If you use the AI features from SDKs, upgrade embedded applications to React SDK v11.48+ and integrations to Python SDK 1.71+. The previous AI Assistant will be deprecated in upcoming releases.

For details, see the 4.12.1 and 4.12.0 release notes.

Version 4.11.0

If you embed GoodData dashboards, Analytical Designer, or visualizations, note the embedded analytics URL migration: embed URLs change from /dashboards/embedded/#/workspace/<id>/... to /embedded/workspace/<id>/dashboards/#/... (and equivalents for Analytical Designer). The new URLs are available immediately; old URLs are migrated on August 13, 2026. Update your embedding applications before that date.

For details, see the 4.11.0 release notes.

Version 4.10.0

This is a long-term support (LTS) release. See Releases and Version Tags for what that means and how long the line is maintained.

The Helm chart value exportController.useNewExportFlow now defaults to true. If you relied on the previous export flow, review this default change before upgrading.

If you embed dashboards with the React SDK, note that React SDK versions v11.35.0, v11.36.0, v11.38.0, and v11.39.0 contained a bug that could delete dashboard filters during use. Upgrade embedded applications to React SDK v11.40.0 or newer and redeploy them.

For details, see the 4.10.0 release notes.

Version 4.9.0

The temporary opt-out for gateway-side authentication has been removed. The API Gateway now always handles OIDC sign-in, JWT bearer authentication, and API-token validation. The following Helm values can no longer disable this behavior:

• enableGatewayOauth
• enableGatewayJwt
• enableGatewayApiTokens
• apiGw.oauth.enabled
• apiGw.jwt.enabled

If you previously set any of these values to false, remove the overrides from your Helm configuration before upgrading.

If a WAF, CDN, reverse proxy, or any other component between the browser and the API Gateway filters cookies by name, ensure the GD_SESSION_ID and GD_OAUTH_FLOW cookies are allowed.

For details, see the 4.9.0 release notes.

Version 4.7.0

This release upgrades the internal nginx component to address the CVE-2026-9256 vulnerability. We recommend upgrading without undue delay.

The 4.7.0 release notes announced that the current AI Assistant would be retired in favor of the new agentic AI Assistant experience. That experience shipped in the 4.12 line. No version has been announced in which the switch becomes mandatory. Before you switch, ensure your configured LLM Provider uses a supported model (ChatGPT 5.2 or newer), update embedded React SDK integrations to version 11.32.0 or newer, and migrate any AI Assistant API usage to the new endpoint.

For details, see the 4.7.0 release notes.

Version 4.5.0

Starting with version 4.5.0, the API Gateway handles OIDC sign-in, JWT bearer authentication, and API-token validation by default, using a server-side session model (GD_SESSION_ID as the primary session cookie and GD_OAUTH_FLOW as the short-lived sign-in flow cookie). Users who are already signed in remain signed in after the upgrade.

If a WAF, CDN, reverse proxy, or any other component filters cookies by name, add GD_SESSION_ID and GD_OAUTH_FLOW to your allow-list.

You can temporarily opt out by setting enableGatewayOauth, enableGatewayJwt, enableGatewayApiTokens, apiGw.oauth.enabled, and apiGw.jwt.enabled to false. This opt-out is removed in version 4.9.0.

For details, see the 4.5.0 release notes and Upgrade to GoodData.CN 4.0.

Version 4.2.0

Starting with version 4.2.0, the API Gateway uses database mode by default and stores the required data in its own database.

The previous gRPC mode is no longer supported.

Standard deployments need no manual action. However, if you previously used custom API Gateway resolver settings, review your values.yaml file and remove any old gRPC-based configuration.

This release also fixes a connection issue that could affect deployments using an external PostgreSQL database with TLS, such as AWS RDS.

Version 4.1.0

The LLM Endpoint entity is replaced by LLM Provider. Existing LLM settings are migrated via gen-ai-metadata-sync metadata synchronization, and any API or SDK code that manages LLM endpoints must be updated to use the new LLM Provider model.

For details, see the 4.1.0 release notes.

Version 4.0.0

GoodData.CN 4.0 introduces several breaking changes and one-time migration steps, including etcd configuration updates, migration away from the built-in PostgreSQL (postgresql-ha) subchart, API Gateway authentication changes, removed Organization custom resource fields, renamed NetworkPolicy Helm values, and geo chart base-map configuration moving from extraEnvVars to apiGw.locationService.

Before upgrading to 4.0, follow the Upgrade to GoodData.CN 4.0 guide.

Version 3.57.0

There is a known issue in version 3.57 related to a change in capitalization of FrontendEmptyValueHandling, which may require manual metadata updates (for example in automation_dashboard_tabular_export) as a workaround. However this approach is not recommended for production - please upgrade to version 3.58, where the issue is resolved.

Version 3.56.0

Starting with version 3.56.0, GoodData.CN is ingress controller agnostic. If you are migrating from ingress-nginx to another Kubernetes-compatible ingress controller, you must update your ingress configuration accordingly.

Required Ingress Configuration

GoodData.CN requires:

• Minimum request body size: 20 MB
• Timeout: 180 seconds

With ingress-nginx, this was typically configured using annotations such as:

annotations:
  nginx.ingress.kubernetes.io/proxy-body-size: "20m"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "180"

When migrating to a different ingress controller, configure equivalent settings according to the documentation of your chosen controller.

Migrate To a New Ingress Controller

Migration of GoodData.CN and all existing organizations is performed by updating the Helm chart values for ingress configuration.

Set the new ingress class name and any required annotations in your gdcn-values.yaml file:

ingress:
  annotations:
    <your_ingress_annotations>
  ingressClassName: <your_new_ingress_class_name>

After modifying the Helm values, upgrade or reinstall the GoodData.CN Helm chart. All existing GoodData.CN ingresses will be updated to use the new ingress class, and the specified annotations will be applied automatically.

Version 3.54.0

This release introduces geo area charts and revamped geo charts as default features. To be able to use these features, you need to do some additional configuration. Follow instructions in Geo Chart Configuration.

Version 3.53.0

This release introduces geo area charts and revamped geo charts as opt-in features. To opt in, ensure your custom Helm values file contains the following:

1. Enable the enableGeoArea and enableNewGeoPushpin feature flags.
2. Follow the steps outlined in Geo Chart Configuration.

Version 3.40.0

This release introduces changes to the internal GenAI service deployment. For the new GenAI service to work correctly, you must explicitly enable metadata synchronization for GenAI.

Set the following Helm chart value to true in your gdcn-values.yaml file before upgrading:

deployGenAIMetadataSync: true

If this value is not set, the system will attempt to deploy the older GenAI service, which is no longer functional in this version. As a result, AI Assistant and related GenAI features will not work until the correct flag is enabled.

Version 3.38.0

This release introduces two new AI-powered features: AI assistant and workspace search. These features are initially hidden behind two feature flags:

• enableGenAIChat – Enables the AI Assistant
• enableSemanticSearch - Enables semantic search across workspaces

To support these AI capabilities, two additional new Helm chart values have been introduced. These control whether required services and dependencies are deployed:

• deployGenAIService - Deploys internal GenAI services that power both AI Assistant and semantic search. Must be set to true if any AI features are enabled.
• deployQdrant - Deploys the Qdrant vector database, used by both AI features. If you are using a managed Qdrant service (e.g., cloud Qdrant or an Operator-based deployment), you can leave this set to false.

Enabling either enableGenAIChat or enableSemanticSearch requires both deployGenAIService to be true and access to a Qdrant database, either deployed via deployQdrant or provided externally.

Version 3.32.0

As part of the dashboard to slide deck export feature, we have introduced the export-builder microservice. To enable the microservice, set deployExportBuilder to true. Additionally, the slide deck export feature is controlled by the feature flag enableSlidesExports, which you must also set to true if you want to use it. Include these entries in your gdcn-values.yaml file before performing the upgrade:

deployExportBuilder: true
enableSlidesExports: true

This microservice may require you to allocate additional Kubernetes resources to your deployment to ensure your system does not run out of resources when users use the export service. Read the microservice description for details, but in short we recommend allocating up to 3 additional GiB of memory, and 2 CPU cores.

Version 3.10.0

You need to do this when upgrading from GoodData.CN version 3.9 to 3.10.

The 3.10.0 image has an updated PostgreSQL server, so you need to migrate your data to the new PostgreSQL server:

1. Start a container from image 3.9.0 with the data volume mounted as usual.

2. Run the backup script inside the running container (replace gdcn-id with your container name):

   $ docker exec -it gdcn-id /opt/scripts/dump_database.sh

   You should see the message: “Backup successfully created.”

3. Stop and optionally delete the old container, but keep the volume.

4. Run the new container (version 3.10.0) with the original volume. The data will be upgraded automatically.

You will know the data restoration is successful if you see these messages at the start of the new container:

/data/backup/dump.sql.gz: OK

Found a dump to restore.

...

BACKUP RESTORED

Rollback

If the upgrade fails, you can still use the old image (3.9.0) and data volume.

If you accidentally start the new image with the old volume without running the backup script, the application will start but show no data. To recover, follow these steps:

1. Stop and delete the container you started from the new image.

2. Run a container from the old image (3.9.0) with the mounted volume and modified entry point to remove the incompatible Redis savepoint:

   docker run -it --rm -v gd-data:/data --entrypoint /bin/rm gooddata/gooddata-cn-ce:3.9.0 -f /data/redis/dump.rdb

   1. Run the database backup as described above.
   2. Run a container from the new image, and your data will be available again.