Cloud: Releases and Zero-Downtime Deployments

Magento keeps the state of a release in four places, and each has its own trigger and its own failure mode. The release pipeline has to touch each exactly once and in an order that the old pods can survive.

Two consequences set the shape of everything below. First, the database is changed before the new pods exist, so the old pods run, for the length of the Job and the rollout, against a schema that the new release already changed: every schema change has to be compatible with the old code or the release needs a maintenance window. Second, the configuration of the new release is imported into a database that the old pods are still using, which is harmless for a new module and visible for a theme or a store view.

The Adobe documentation has three things that are called deployment, and they are easy to mix up when reading about "zero downtime".

Adobe documents no blue/green procedure for Adobe Commerce or Magento Open Source. A search of the Experience League for "blue/green" finds it only in the documentation of Cloud Manager for Adobe Experience Manager, which is a different product. What exists is the pipeline sequence below, the zero-downtime configuration of the cloud platform, and the Kubernetes rolling update, which is what this page uses. A real blue/green (a second environment with its own database copy and a switch of the Gateway) is discussed in Blue/green and rolling releases as an option that you would build yourself, with the data problem that it brings.

The production sequence in Adobe’s pipeline documentation is, in this order: start maintenance mode, pull code and configuration, stop the queue workers (Adobe Commerce), app:config:import, setup:upgrade --keep-generated if components that change the schema were installed, set system-specific and sensitive values (config:set, config:sensitive:set or environment variables), flush the cache, end maintenance mode. On EKS the steps become: maintenance mode only for a breaking release (Maintenance mode on a cluster); code and config.php arrive in the image through helm upgrade; queue workers are stopped only for a breaking release (The release workflow); the import and the upgrade are the migrate Job; system-specific and sensitive values come from env.php reading the ConfigMap and the Secret, because there is no config:set on a read-only image; the cache is cleaned by the warm-up Job after the rollout (Cache clean, Varnish purge and warm-up); and ending maintenance mode is the last workflow step.

Source: Adobe Commerce docs: Deployment technical details

Source: Adobe Commerce on cloud infrastructure: Zero downtime deployment

Source: Adobe Commerce docs: Deployment flow

A word on the config:set options, because the question comes up. bin/magento config:set has three lock options in 2.4.9: --lock-env (-e) saves the value in app/etc/env.php and makes the field read-only in the Admin, --lock-config (-c) saves it in app/etc/config.php, to be shared with other installations, and --lock (-l) is deprecated in favour of --lock-env. Adobe’s pipeline page still shows the older --lock. In an image, neither file can be written at run time, so these commands belong on the development system, where their effect is committed (config.php) or becomes an environment variable (env.php); a value that the release must carry is set there, followed by app:config:dump. The precedence that Adobe documents is the reason this works: environment variables first, then env.php, then config.php, then the database, then the default.

Source: GitHub: magento/magento2 2.4.9, ConfigSetCommand

bin/magento setup:db:status asks every registered validator (schema, data, declarative schema, patches) whether the database matches the code. Its exit codes were read from DbStatusCommand.php in the tags 2.4.8, 2.4.9 and Mage-OS 3.6.0, which all define them the same way:

Source: GitHub: magento/magento2 2.4.9, DbStatusCommand

Two details matter for a Job. A validator that throws (for example because the database is unreachable or the user lacks a privilege) is reported as "Treating as upgrade required due to validation error" and gives 2, so an exit code of 2 can mean a real upgrade or a broken connection; the Job then fails one step later, in setup:upgrade, with the real message, which is why the gate is not a health check. And the command compares the database with the code of the image that runs it, which is exactly the question a release asks, so it must run with the new image (the pre-upgrade hook uses the new image) and never with the one that is currently serving.

The gate is the cheap half of a safe release. Its value is what it prevents: a release that touches no schema skips setup:upgrade altogether, so the most common release (a template, a CSS file, a plugin that adds no table) does not take the locks that setup:upgrade takes and does not clean the shared caches (next section).

setup:upgrade does more than change tables, and four of the things it does decide how the Job must be built. All four were read from the 2.4.9 sources of UpgradeCommand, Installer and DeploymentConfig\Writer:

The Job also needs everything the application needs at boot: the database (as mg_migrate), OpenSearch (setup:upgrade validates the search engine configuration), the Valkey cache, and the environment of the ConfigMap and the Secret. The mg_migrate password reaches the pod from the same Secrets Manager secret as the others (db_migrate_password, which the ExternalSecret writes as MAGENTO_MIGRATE_DB_PASSWORD), and the Job overrides MAGENTO_DB_USER and MAGENTO_DB_PASSWORD because an explicit env entry wins over envFrom. The privileges of the two users are on Cloud: Managed Database (RDS and Aurora); the parameter log_bin_trust_function_creators that triggers need on a database with binary logging is there too.

The script lives in the image, versioned with the code. Here is the script, then the Job.

Source: Adobe Commerce docs: Declarative schema

Source: GitHub: magento/magento2 2.4.9, UpgradeCommand

What the script does that the commands alone do not:

Source: Helm Docs: Chart hooks

Source: Kubernetes Documentation: Jobs

The values it reads are database.migrateUser: mg_migrate, migrate.enabled: true and migrate.timeoutSeconds: 1800; the helpers pc.*, the ConfigMaps and the ExternalSecret are those of the Helm page. Points about the Job’s pod:

app:config:import copies the shared configuration of config.php (and env.php) into the database for three sections. Adobe’s page lists them: scopes (websites, store groups and store views, imported in modes create, update and delete), themes (registered if their source code exists, never removed if missing from config.php) and system configuration, which is not copied at all because Magento reads the system array of the file directly, so the values need no import. Root categories are not imported and have to be assigned in the Admin.

The delete mode is the one that matters for a pipeline. The importer in Processor::execute() asks for confirmation before it applies a section whose importer warns, and the Store importer warns about "These stores will be deleted". The confirmation helper YesNo::execute() returns true without asking when the input is not interactive. A Job always runs non-interactively, so a store view that exists in the database and is missing from config.php is deleted by the release. That is the documented model (the development system owns the scopes, and production receives them), and it has two consequences for Pocket Coffee:

The commands for it are bin/magento app:config:dump on the development system (check that app/etc/config.php contains modules, scopes, themes and system) and a commit of the file.

Source: Adobe Commerce docs: Deployment technical details

Source: Adobe Commerce docs: Import configuration

The dump writes the sensitive settings nowhere (Adobe’s page: "It does not write sensitive settings"), so a payment gateway key that the Admin shows on the development system never ends up in git, and on production it comes from the Secret through env.php. The shared and the environment-specific split is also what lets one image run in staging and in production with different ConfigMaps and Secrets.

app:config:import skips a section whose hash did not change ("Nothing to import" when nothing changed); the hash is stored in the database. A release in which nothing changed in config.php therefore does no work in the Job, which is the second reason for the gate.

bin/magento maintenance:enable makes Magento answer 503, and --ip=<address> (repeatable) exempts the addresses of the people who test. The mechanism is two files in var/: .maintenance.flag and .maintenance.ip, defined as MaintenanceMode::FLAG_FILENAME, IP_FILENAME and FLAG_DIR = DirectoryList::VAR_DIR. On a single server that is one place. On the cluster of this series var/ is an emptyDir per pod, so the command run in one pod closes that pod and no other, and a pod that starts a minute later is open. The usual remedies do not fit:

The switch that works is outside the application: the nginx container of every web pod returns 503 while a flag file exists, and the flag file comes from a ConfigMap mounted as a directory, which Kubernetes updates in the running pods (after the kubelet’s sync delay, typically a minute, so it is not instantaneous; files mounted with subPath are not updated). Varnish does not cache the answer: the generated VCL refuses to cache responses that are not 200 or 404.

Source: nginx documentation: error_page

Source: Kubernetes Documentation: Mounted ConfigMaps are updated automatically

The ConfigMap pocketcoffee-maintenance is created by the chart with empty data and mounted at /etc/nginx/maintenance; the page maintenance.html is part of the image at /usr/share/nginx/maintenance/. release-control.sh maintenance-on of the workflow adds the key enabled, maintenance-off removes it. The configuration was checked with nginx -t and exercised in a container (200 without the flag, 503 with it and the maintenance page with Cache-Control: no-store); the geo block uses $remote_addr, so behind the ALB it needs the real client address (set_real_ip_from and the forwarded header) configured as on Cloud: Varnish and Full Page Cache on Kubernetes. Whether Helm’s merge keeps a key that kubectl patch added to a ConfigMap that the chart owns, across helm upgrade, depends on the Helm version and its apply strategy; I did not test it with Helm 4.3.1 against a cluster, so the workflow sets the flag before helm upgrade and checks it afterwards. If it disappears, own the ConfigMap outside the chart.

Source: Adobe Commerce docs: Maintenance mode options

Source: GitHub: magento/magento2 2.4.9, MaintenanceMode

Three caches see a release, and each needs a different action:

Two facts from the sources of 2.4.9 decide the command. CacheCleanCommand::performAction() dispatches the event adminhtml_cache_flush_system when no type is given or full_page is, and CacheFlushCommand dispatches adminhtml_cache_flush_all in the same cases; both are observed by Magento\CacheInvalidate\Observer\FlushAllCacheObserver, which sends a PURGE with the tag pattern .* to the Varnish hosts if the full page cache is Varnish and enabled. So cache:clean from the CLI does purge Varnish, as long as the pod has http_cache_hosts in env.php (from MAGENTO_VARNISH_HOSTS) and the stored configuration system/full_page_cache/caching_application is Varnish (2). A pod without these silently cleans only Valkey. Prefer cache:clean over cache:flush: clean removes the enabled types by tag, flush empties the whole Valkey database, and with Valkey that is every key in it. The caches of this series have their own replication groups for that reason, but a flush is still a larger hammer than the release needs.

The warm-up is a Job after the rollout that requests the key URLs from every Varnish replica, not through the Service: each replica has its own memory-only cache, so a request through the Service warms one replica chosen at random. It uses the replica names of MAGENTO_VARNISH_HOSTS (the headless Service names) and sends the Host header and the offloaded-protocol header (X-Forwarded-Proto: https) that the real traffic carries, because the VCL adds the offloader header to the hash: a page warmed without it would be a different object from the one the customers request. Each URL is requested twice, so that the log shows whether the second answer was a hit (the VCL’s X-Magento-Cache-Debug header), which is the check that the page is cacheable at all.

Source: Adobe Commerce docs: Manage the cache

Source: GitHub: magento/magento2 2.4.9, CacheCleanCommand

Source: GitHub: magento/magento2 2.4.9, CacheInvalidate events.xml

Source: Helm Docs: Chart hooks

The chart also renders the ConfigMap pocketcoffee-warmup-paths (one path per line, from warmup.paths), which the Job mounts. The Job is a post-install,post-upgrade hook. Helm runs the post-upgrade hooks after the resources of the new revision are updated and, with --wait (which --rollback-on-failure turns on as watcher in Helm 4.3.1), after the pods are ready, so the Varnish replicas and the new web pods exist when the Job starts. The warm-up fails the hook only for a 5xx or no answer, which means a broken release and a rollback; a page that is not cacheable or a miss is reported in the log and is not an error. The paths are values (warmup.paths) because they are the shop’s own: the home page of each store view and the top categories. Which URLs exist depends on the URL rewrites of the catalog (the .html suffix and the store code in the path are settings of the shop), so the ones in the listing are examples; if the store views are served by host name instead of by code in the path, warm each host. Warming checkout, cart or account pages is useless for Varnish (they are not cacheable) and useful only for PHP and OPcache; warm the pages that carry the traffic.

An optional refinement, which Adobe does not document as a release technique, is a different cache id_prefix per release in the cache section of env.php, so that the old and the new pods never read each other’s entries during the rollout, and the old entries expire on their own. It would need the prefix as an environment variable in the template of the Helm page and a decision about the cost of a cold cache after every release; measure before adopting it.

setup:static-content:deploy runs in the image build (Cloud: Container Image and Pipeline Build) and pub/static/deployed_version.txt is baked with it. The version in that file becomes part of every static URL (/static/version<number>/frontend/...), which is how a new release invalidates the browsers' and the CDN’s copies. Three details from the 2.4.9 sources:

During a rolling update both versions exist at once. The new pods render pages with /static/version<new>/...; if the browser’s request for that URL lands on an old pod, the nginx rewrite strips the version and the old pod answers with its file under the new URL. For a file that did not change that is correct; for one that did, a CDN or a Varnish that caches the answer by URL keeps the old content under the new version until it expires. Magento’s VCL passes /static/ by default, so Varnish is not the problem, but a CDN in front of /static/ is. The remedies are to keep the window short (maxUnavailable: 0, a fast readiness check), to put the CDN’s static behavior on a short time to live or to invalidate /static/* after the rollout, or to serve the static files from a place that holds every version (S3 with a prefix per version, which is a design of its own). The media host media.pocketcoffee.example is not affected: it serves pub/media, not pub/static.

Source: Kubernetes Documentation: Rolling Update Deployment

Source: GitHub: magento/magento2 2.4.9, Deployment Version

maxUnavailable: 0 with maxSurge: 1 replaces a pod only after its successor is ready, minReadySeconds keeps a flapping pod from counting as ready, and the preStop sleep gives the Service and the Varnish backend list time to stop sending requests before nginx quits. The probe path is /health_check.php, which checks the database and the cache backends, so a release whose pods cannot reach Valkey never becomes ready and the rollout stops by itself. A PodDisruptionBudget on pocketcoffee-web must allow at least one pod to be unavailable or the node drains of EKS Auto Mode (which replaces nodes at most every 21 days) will block; see Scheduling and Disruptions.

Between the migrate Job and the end of the rollout the old code runs on the new schema. For a pod that is replaced a minute later this is a short window, but it is real traffic: carts, orders and the Admin. The discipline that makes it safe is the expand-and-contract pattern, and Magento’s declarative schema gives it a shape.

Source: Adobe Commerce docs: Configure declarative schema

The whitelist and the contract release. A declarative schema drops a column or table that disappeared from db_schema.xml only if it is listed in the module’s etc/db_schema_whitelist.json, which bin/magento setup:db-declaration:generate-whitelist --module-name=PocketCoffee_RoastAdmin generates from the XML as it is at that moment. The sequence that works across releases is: add the element in release N, generate the whitelist and commit it in release N, remove the element from the XML in release N+k and ship; the whitelist file remains committed and the drop happens in N+k’s Job. If the element is removed before the whitelist knew it, it is never dropped. The existing page Declarative Schema and Patches shows these cases with the commands and the outputs; the pipeline consequence is that the contract release is a separate release, labelled breaking in the workflow if the old code could still read the column.

Data patches and rollback. A data patch is recorded by class name in patch_list when it applies, and is not run again. A patch may implement PatchRevertableInterface, but revert() is called only when the module is uninstalled, not by a release rollback; a schema patch is never reverted. So a rolled-back release leaves its applied patches applied: the data they wrote stays, and the old code must tolerate it. Write data patches so that old code can live with their result (add rows, do not rewrite them), and keep a destructive data change out of the release that ships the code that needs it.

--safe-mode and --data-restore. setup:upgrade --safe-mode=1 writes a CSV dump of what a destructive change would remove into var/declarative_dumps_csv/, and --data-restore=1 loads it back when the declaration returns. In the Job var/ is an emptyDir, so the dump disappears with the pod; it is not a substitute for the snapshot. If you want it, copy the directory out in the script before the Job ends (to S3, with the Job’s Pod Identity role extended for it) and treat that as part of the release.

Rolling back means different things for the three layers of a release, and the answers differ.

Source: Helm Docs: helm rollback

Source: Amazon RDS User Guide: Restoring from a DB snapshot

So there are two answers to "can I roll back": a release whose schema change was additive can be rolled back with helm rollback and then cleaned (cache:clean, a warm-up Job again); a release whose schema or data change was not compatible can only be rolled forward with a fix, or restored from the snapshot taken before the Job, with everything that follows from a restore of a shop that took orders in the meantime. The snapshot is not optional for a release that has a schema change: the workflow takes it before anything else can change the database. Restoring creates a new RDS instance with a new endpoint; the running instance is never overwritten. The order for a restore without a maintenance window, as on the PrestaShop sibling page (Cloud: Releases and Upgrades): stop the writers you control (release-control.sh quiesce and maintenance mode on), restore the snapshot into a new instance, point the release at the new endpoint with the previous image tag and migrate.enabled=false, reconcile the orders between the snapshot and the restore against the payment provider and the mails sent, reopen the shop, resume the cron last. helm upgrade with an old tag runs the old image’s migrate Job against the new database, which is worse than helm rollback; use migrate.enabled=false for any redeploy of an older image.

Source: Amazon RDS User Guide: Restoring from a DB snapshot

For Aurora the commands are the cluster ones (create-db-cluster-snapshot, restore-db-cluster-from-snapshot, then a new instance in the new cluster); the backup side (automated backups, point in time restore, retention) is on Cloud: Autoscaling, Observability, Backups and Security. A restore also does not move the secrets: crypt_key is in Secrets Manager, not in the snapshot, and the restored database works with it as long as it was not rotated in between (Cloud: Migrating from a Single Server). Manual snapshots stay until deleted, so automate their expiry.

The rolling update is the Kubernetes default and gives a zero-downtime release when the schema change is compatible. A blue/green release, two complete stacks and a switch, adds a rehearsal and an instant way back, and costs a good deal:

For the strategies in general (rolling, recreate, blue/green, canary) see Deployment Strategies. A canary of the web tier through weighted Gateway API routes serves two code versions against one database, which is the same compatibility problem as the rolling update with a longer window.

The workflow authenticates to AWS with OpenID Connect, as the WordPress page explains (Authenticating GitHub Actions to AWS with OIDC): no AWS keys are stored in GitHub, the job asks GitHub for a token and exchanges it for the temporary credentials of the role pocketcoffee-prod-github-deploy. The role of the infrastructure page can push images and call eks:DescribeCluster; a release that takes an RDS snapshot needs the extra statement of the policy below. The trust policy names the two subjects that may assume it: runs on the branch main (the build job) and jobs that target the GitHub environment production (the deploy job, which is the one where a reviewer approves). eks:DescribeCluster only lets aws eks update-kubeconfig find the endpoint; what the role may do inside the cluster is decided by an EKS access entry for the role, with an access policy scoped to the namespace pocketcoffee (EKS Auto Mode requires access entries; see EKS Clusters). The two policies, both with the placeholders of this series:

Source: GitHub Docs: Configuring OpenID Connect in Amazon Web Services

Source: Amazon RDS User Guide: Creating a DB snapshot

The repository name pocketcoffee-shop/magento is a placeholder; the sub claim has the form repo:<owner>/<repository>:... and the policy should name your repository exactly, not a wildcard for the whole organization. The workflow itself follows; the quiesce and maintenance steps of a breaking release are in a script that the workflow calls.

Source: KEDA documentation: Scaling Deployments

Source: Kubernetes Documentation: kubectl patch

Source: GitHub: aws-actions/configure-aws-credentials

Source: Helm Docs: helm upgrade

Where it differs from the sibling workflows:

The workflow was parsed and passed actionlint; nothing was run on GitHub or against AWS.

After helm upgrade returns, the checks that go beyond the smoke test run from a pod, so that the environment is production’s:

After helm upgrade returns, the checks that go beyond the smoke test run from a pod, so that the environment is production’s: kubectl exec deployment/pocketcoffee-web -c php-fpm — php bin/magento setup:db:status must end with "All modules are up to date.", module:status --enabled must equal the module list of config.php, config:show web/unsecure/base_url must print https://www.pocketcoffee.example/, and indexer:status must show no "Reindex required" unless the release meant to leave one (the reindex Job is on the cron page). Then check that the pods of the new revision are spread over the zones, that the suspend field of the CronJob pocketcoffee-cron is false and that no ScaledObject still carries the pause annotation, and sign in to the Admin from the allowed address to open System > Tools > Cache Management (no type marked invalidated) and the Index Management grid.

Source: Adobe Commerce docs: Command-line reference

Verified on 2026-10-29: in the sources of Magento 2.4.9 (and, for DbStatusCommand and UpgradeCommand, 2.4.8 and Mage-OS 3.6.0) DbStatusCommand and its exit codes, UpgradeCommand, Installer (updateModulesSequence, createModulesConfig, cleanupGeneratedFiles), DeploymentConfig\Writer, DbInitStatementsCleanup, ConfigImportCommand, ConfigImport\Processor, YesNo, ConfigSetCommand (the lock options), MaintenanceMode, CacheCleanCommand, CacheFlushCommand, the events.xml of Magento_CacheInvalidate, DeployStaticOptions, DeployStaticContent, Version of the static deployment, pub/health_check.php and nginx.conf.sample; and in the Adobe documentation the deployment technical details, the zero-downtime page of Adobe Commerce on cloud infrastructure, the deployment flow, the page on importing configuration and the one on maintenance mode. The scripts were run through shellcheck and exercised with a stub for php (gate with exit codes 0, 2 and 1, and the second check failing); the PHP snippet passed php -l (PHP 8.5) and was run against sample config.php files with equal, reordered and different module lists; the Jobs and the Deployment fragment were rendered with helm template (Helm 4.3.1), passed helm lint and kubeconform -strict against the Kubernetes 1.36 schemas; the nginx configuration passed nginx -t and was run in a container; the workflow passed actionlint; the two policies parsed as JSON; the diagram passed the Mermaid validator of this repository and the figure xmllint.

Not verified: setup:upgrade or app:config:import against a real installation in a read-only image (the claims about the writes are from the sources), the Jobs on a cluster, External Secrets Operator, KEDA, Varnish purges from a Job (the observers were read, not run), the maintenance ConfigMap across helm upgrade with Helm 4.3.1, a non-numeric static content version, the id_prefix technique, the EKS access entry and its policy, anything against AWS or GitHub, the duration of any step with a production-sized database, and the Aurora variants of the snapshot commands.