Parallel production upgrade

This guide describes how to upgrade Magnolia on DX Cloud by running a parallel production environment alongside your current production namespace, validating the upgrade, and cutting over traffic when ready.

This is not strict blue/green deployment. It is a recommended procedure for customers who need production-fidelity testing before switchover, or who want a rollback path during a major upgrade.

For Magnolia application changes (bundle version, Jakarta EE, custom code), complete the steps in Upgrading to Magnolia first, then return here for platform-specific steps.

Choose your upgrade approach

Before starting, decide whether an in-place upgrade is sufficient or whether you need a parallel production namespace.

Overview

A parallel production upgrade follows this sequence:

1. Provision a second production-grade namespace on your cluster.
2. Copy the production database into the new namespace (typically with Helpdesk support).
3. Deploy the upgraded Magnolia version into the new namespace.
4. Validate via a subdomain or direct ingress URL without affecting live traffic.
5. Cut over production traffic by recreating production Ingresses in the new namespace. Production hostnames are down during this swap while Fastly is reconfigured.
6. Decommission the old namespace once you are confident, or roll back if needed.

Prerequisites

Before you begin:

• Confirm automatic backups are enabled and healthy for your production environment. See Automatic backups for architecture and values.yml configuration.
• Ensure backup prerequisites are met (WAL archiving, adequate database persistence, and related db.backup settings). See Automatic backups and the values.yml db.backup section in The values.yml file.
• Plan for temporary additional cluster capacity. Running two production-grade namespaces in parallel may require extra nodes.
• Complete Magnolia-specific upgrade preparation from Upgrading to Magnolia (bundle version, certified stack, custom module compatibility).
• Update your Helm chart to a version compatible with your target Magnolia release. See Do I need to use the latest Helm chart version?.

Procedure

1. Provision a parallel production namespace

Create a new Kubernetes namespace with production-grade sizing, mirroring your current prod topology (author, public, database, ingress).

1. Create the namespace and add it to your .gitlab-ci.yml pipeline. For the general pattern, see Feature environments.
2. Configure values.yml (or a dedicated values file) with production-appropriate resource limits, replica counts, and backup settings. See The values.yml file and Architecture.
3. Create ingress resources for the new namespace. Use a test subdomain or separate hostname so you can reach the parallel environment without affecting production traffic. See Create an ingress.

2. Copy the production database

Copy a point-in-time production database into the parallel namespace so you can validate against production-fidelity content.

DX Cloud takes automatic database backups as configured in your values.yml file. See Automatic backups. There is currently no self-serve Cockpit action to copy a backup from one environment to another.

1. Open a Helpdesk request for an environment-to-environment database copy (or restore into the parallel namespace). Include the source environment, target parallel environment, and the point-in-time you need.
2. Confirm with Helpdesk which instances are in scope (author, public, or both) and any Solr or search-index follow-up.
3. After the restore completes, delete indexes on the target environment so Magnolia rebuilds them from the restored database. See Delete indexes and workloads after restore.

3. Deploy the upgraded Magnolia version

Deploy your upgraded webapp and Helm chart into the parallel namespace.

1. Update your project dependencies and bundle version per Upgrading to Magnolia.
2. Run the GitLab CI deployment pipeline for the parallel namespace.
3. Verify pods are healthy and Magnolia starts without errors.

4. Validate the parallel environment

Before cutover, thoroughly test the parallel environment:

• Access the site via the test subdomain or direct ingress URL.
• Verify authoring, publishing, and public rendering.
• Run smoke tests for critical integrations and custom modules.
• Check the Definitions app for deprecated or problematic definitions.

Do not modify production ingress or DNS until validation is complete.

5. Cut over production traffic

When validation passes, switch live traffic to the parallel environment. Keep the same production hostnames so you avoid a manual Fastly backend switch (see Fastly backend switch). Fastly is still updated automatically when the old Ingress is removed and when the new one is added.

Ingress swap (primary DX Cloud path)

An ingress is namespaced. It targets a Service in the same namespace (the controller load-balances via that Service’s EndpointSlices). You cannot point an existing production Ingress at a Service in the parallel namespace.

Cutover means:

• Stop the old Ingress from owning the production host and path; delete it, or change it so it no longer claims that host (for example a different path prefix).
• Create an equivalent Ingress in the new namespace, with the same hostnames and rules, pointing at services in that namespace.

Delete then create is the default: it is simpler and leaves no stray production Ingress in the old namespace.

During that window, the production hostnames are down. When the old Ingress is removed, DX Cloud reconfigures Fastly; when the new Ingress is added, Fastly is reconfigured again. That two-step CDN update is why you should expect a short outage even if the hostnames stay the same. Plan a maintenance window and communicate the outage.

1. Prepare the replacement Ingress (same hosts, paths, TLS, and CDN settings as production), either in the Cockpit or as infrastructure as code. Point its backends at the new namespace’s services (for example prod-next-magnolia-public-svc).
2. Schedule the cutover. Have rollback materials ready: a copy of the old Ingress definition so you can recreate it quickly.
3. Delete the production Ingress in the old namespace (or alter it so it no longer claims the production host and path).
4. Immediately create the equivalent Ingress in the new namespace.
5. Verify production URLs serve content from the upgraded environment.
6. Flush CDN cache if needed.

DNS changes

DNS updates are required only when you migrate to a new cluster and production hostnames must point elsewhere. For upgrades within the same cluster, recreating the ingress with the same hostnames is usually sufficient.

Fastly backend switch (last resort)

DX Cloud generally avoids changing Fastly backends during a parallel upgrade. A backend switch is tedious and needs manual intervention:

• The backend certificate typically breaks and must be recreated.
• If you use WAF, Fastly and WAF must be resynced. That resync is hard to automate.

Prefer keeping production hostnames unchanged and swapping Ingresses instead. That avoids a manual backend switch. Fastly still changes during the Ingress swap because DX Cloud reconfigures it when the old Ingress is removed and when the new one is added.

Use a Fastly backend switch only when there is no other way (for example, a new cluster whose origin Fastly cannot keep). Involve Helpdesk.

For Magnolia-managed CDN configuration, see Connect to Fastly.

Some customers route traffic through their own CDN. Coordinate any origin change with that provider around the same cutover window.

6. Roll back (if needed)

If issues appear after cutover, reverse the same namespaced Ingress swap:

1. Delete (or alter) the production Ingress in the new namespace so it no longer claims the production host.
2. Recreate the original Ingress in the old namespace (same hostnames and rules as before cutover).
3. Verify the previous environment serves traffic correctly. Production hostnames are down again during this swap, including the Fastly reconfiguration on remove and add.
4. Investigate and fix issues in the parallel namespace before attempting cutover again.

The old namespace remains available as a fallback until you decommission it.

After cutover

Once the upgraded environment is stable in production:

• Monitor alerts and logs in the Cockpit.
• Decommission the old namespace when you no longer need it as a rollback target.
• Complete any remaining post-upgrade steps from Upgrading to Magnolia.

Related topics

• Environments: default dev, uat, and prod environment model
• Feature environments: adding namespaces to your pipeline
• Automatic backups: backup architecture and values.yml configuration
• Delete indexes after restore: required after restoring a database
• Go Live guide: production readiness checklist
• Multicluster environments: active/active regional deployments (different use case)