Cloud: Migrating from a Single Server

A Magento shop on one server keeps five kinds of state: the database, the media (pub/media), the search index (in OpenSearch), the code and configuration (the Composer project, app/etc/config.php, app/etc/env.php) and a lot of transient state (sessions, cache, generated code, queue messages) that is not worth moving. The cluster stores each in a different place, so a migration is several moves that must agree with each other at the end.

The rule that keeps a shop safe is the one of every migration with orders: at any moment exactly one side takes orders. The old server stays untouched until the new shop has answered real requests, and it stays available as the rollback.

Do not start the new stack before you know what the old one contains. The inventory finds the facts that decide the method (the database size and engine, the queue backend, the indexer modes) and the differences between the production server and the repository the image is built from, which are the usual cause of "it worked on the old server". It reads the configuration by key path, never by value, so its output can be pasted into a ticket.

Source: Adobe: env.php reference

Source: Adobe: bin/magento CLI reference for Adobe Commerce on-premises and MySQL reference: the INFORMATION_SCHEMA TABLES table

What to do with each result:

Do not run setup:install against the production database. The installer creates a fresh schema and a new crypt/key, which is the opposite of what a migration needs; the Job pocketcoffee-install of the chart is for a shop that starts empty. The target is prepared in this order:

The rehearsal repeats everything on this page against a copy: a dump of the old shop, a scratch database and a scratch bucket or prefix. It is the only way to learn how long the dump, the import, the media delta and the reindex take, which decides the length of the freeze.

Magento stores its URLs in core_config_data, per scope, and the Admin, the URL generation, the cookies and the redirects read them from there. A URL that points to the old environment is the classic result of a copied database: the storefront redirects to the old host, or the admin form posts to it. There are two cases for the Pocket Coffee shop, and the SQL below handles both.

The paths, read in the system.xml of the Store and Backend modules and in the Adobe documentation, are:

Source: Adobe: Set configuration values and magento2: Backend module system.xml

Notes on the statements:

Source: Adobe: Set configuration values

A value written with config:set --lock-env goes to env.php and one written with --lock-config to config.php, and both make the field read-only in the Admin. Neither is what you want for URLs on a cluster whose env.php is a read-only ConfigMap: keep plain config:set (database) for values that editors may change and put environment-specific settings in the env.php template. A value in env.php or config.php takes precedence over the same path in core_config_data, so an old system section copied from the old server’s env.php would silently override the rows you just corrected; see Rebuilding env.php.

app/etc/env.php is the file that makes the image a copy of this shop, and the one place where a careless migration destroys data. Never copy it as it is, and never create it by running the installer.

Why the key matters. Magento encrypts some values before it stores them, with the key in crypt/key of env.php: the values of configuration fields that use the encrypted backend model (payment gateway credentials, SMTP passwords and similar), the secrets of extensions that use EncryptorInterface, and anything else your modules encrypt. The value has the form <key version>:<cipher>:<data> (read in Magento\Framework\Encryption\Encryptor; the current cipher is 3, ChaCha20-Poly1305). A new key cannot decrypt them. The result is not an error at the import but a payment method that stops authorising, a mail server that rejects the stored password, or a decryption exception at the first use. Keep crypt/key identical to the old shop’s value. In the Pocket Coffee setup it is only a secret reference: the value lives in the secret pocketcoffee/prod/magento under the key crypt_key, reaches the pods as the environment variable MAGENTO_CRYPT_KEY, and is never written into a manifest, an image, a ticket or a chat. How the first-install Job handles a key for a shop that starts empty is on the Helm page; it is not used for a migration.

The value can hold more than one key. Encryptor splits the value on whitespace (preg_split('/\s+/s', trim(...))) and uses the last key for new encryption and the earlier ones, by version number, for old data. A shop that changed its key from the Admin has several keys on separate lines in crypt/key; copy all of them, in order, as the secret crypt_key. The inventory prints how many the old file holds.

Which values can be checked. You can find the encrypted rows without reading them: count the values of core_config_data that have the shape of an encrypted value, list only their paths, and after the migration open one of them through the feature that uses it (a test payment in the sandbox of the provider, a test mail).

Source: magento2: Magento\Framework\Encryption\Encryptor

How to move the key. It crosses from the old server to Secrets Manager through a channel that does not leave a trace: an SSH stream into a file in memory (umask 077, on a tmpfs such as /dev/shm) on an administrator’s workstation, then put-secret-value, then the file is deleted. The key is never an argument of a command (arguments appear in the process list and in shell history), never printed and never stored in a repository. The script reads the key from the old server’s env.php by key path and handles the value only inside the pipe; the jq call keeps the other keys of the secret.

Source: AWS CLI: put-secret-value and AWS Secrets Manager: Best practices

The script shows only the length, which proves that something was stored and lets you compare it with the same measurement on the old server; it never shows a part of the key. Restrict secretsmanager:PutSecretValue on that secret to the people who run the migration and remove it afterwards. The key rotation that follows the migration is part of the operations page, Cloud: Autoscaling, Observability, Backups and Security; do not rotate during the migration.

What else env.php contains, and where each part comes from in the cluster. The new file is the template in the ConfigMap pocketcoffee-env-php, read with getenv() (see the Helm page). Compare it, key path by key path, with the output of the inventory:

config.php is not copied either. Run bin/magento app:config:dump on a configured reference system (it needs an installed database, so it is not a step of the image build itself; the build consumes the committed file, see Cloud: Container Image and Pipeline Build); it writes the shared, non-sensitive configuration (modules, scopes, themes and system settings that are not environment-specific) into app/etc/config.php, which is committed, while the sensitive and system-specific settings stay out of it. Adobe states that config.php is the file shared by all instances and env.php is the environment-specific one that is not committed. A config.php produced from a production dump is the evidence that the modules list and the website and store codes of the image match the database; if the image has a module that the database does not know, setup:db:status reports it and the upgrade Job handles it.

Source: Adobe: Export configuration settings and Adobe: env.php reference

pub/media holds what the shop writes: the product and category images (catalog/), the files of the editor (wysiwyg/), customer uploads, downloadable-product files, the import folder and the generated caches. The target is the S3 bucket pocketcoffee-prod-media, used through the AWS S3 driver of Magento’s remote storage (the design, the CloudFront distribution and the local paths that stay per pod are on Cloud: Media and Remote Storage). Two things move: the files, and the information that the shop now reads them from S3.

What not to copy. The folder catalog/product/cache holds the resized product images that Magento generates from the originals on demand; they are regenerated, they are usually the largest part of pub/media and copying them only moves bytes that the first visitors would regenerate anyway. tmp/ holds temporary uploads. Copy everything else. Look at the real tree in the inventory: an extension may keep files under its own folder.

Two ways to copy.

Source: AWS CLI: aws s3 sync

The script uses the credentials of the machine’s AWS profile (a role, for the old server a temporary identity from aws sso or an assumed role); never put access keys into the script. The .htaccess files of pub/media protect folders on Apache (downloadable files are denied to direct access); they mean nothing on S3 and must not be copied. Protect the same folders on the new side: the downloadable-product files, customer uploads and the import folder must not be readable through the public media host; the CloudFront and bucket-policy design that does it is on the media page. Test one downloadable product after the move.

Magento then has to read the files from the bucket. The settings are documented by Adobe and are part of the new env.php (remote_storage) built from the environment; the commands are shown here because the rehearsal runs them once against a copy.

Source: Adobe: Configure remote storage with AWS S3

No access keys: the optional --remote-storage-key and --remote-storage-secret are omitted, so the SDK uses the pod’s IAM role (pocketcoffee-prod-magento, Pod Identity), as Adobe’s page allows. The Adobe page states two constraints that matter here: generated or cached images are written on the local file system, so pub/media and similar folders need the permissions they have with local storage, and code must use Magento’s file adapters instead of native PHP file functions, because the files are not on the disk. That is why extensions of the old shop that write into pub/media with file_put_contents must be found in the inventory and tested in the rehearsal. The remote-storage module also caches file metadata (the module ships a cached adapter); flush the Magento cache after a bulk copy that bypassed Magento. How long that cache keeps entries is not documented in the pages read for this one: verify it in the rehearsal by copying a file with aws s3 cp and reading it through the shop.

A variant for a shorter freeze. Switch the old server to the S3 driver a few days before the cutover (the same two commands on the old server, a role or an identity that can write to the bucket): Magento itself uploads the existing files with remote-storage:sync and every new upload goes to the bucket from that moment. The old server and the cluster then share one bucket and the cutover has no file delta. The cost is a change to the production shop before the move (rehearse it) and the rollback, which then also uses the bucket: the old server keeps working because it uses the same driver.

The OpenSearch index is a derived structure: nothing of it is copied. The imported database already holds the MySQL-based index tables (catalog_product_index_* and others) and the state of the indexers, but the search index of the old server is not in the cluster’s OpenSearch domain, so the storefront has no search results and no layered navigation until it is built.

Engine and connection. The engine is the configuration path catalog/search/engine; the connection values for OpenSearch are catalog/search/opensearch_server_hostname, opensearch_server_port, opensearch_index_prefix, opensearch_enable_auth, opensearch_username and opensearch_password (all read in the system.xml and di.xml of the OpenSearch module; the hostname and the password are declared system-specific there). Three situations occur:

Source: Adobe: Search engine overview

The reindex. bin/magento indexer:reindex rebuilds every indexer, the search index among them. It is the slowest step of the freeze for a large catalogue; run it once in the rehearsal and write the time down. It runs as a Job, not in kubectl exec, so a dropped connection does not stop it: use the Job pocketcoffee-reindex of the chart and run it the way the Cloud: Cron, Queue Consumers and Indexers page describes. After it, switch the indexers back to "Update by Schedule" if the old shop used it (indexer:status and indexer:show-mode show the modes that came with the database), and let the cron on the cluster, not the freeze, process the changelogs. Two behaviours to know:

The cache of the cluster starts empty (a new Valkey instance and an empty Varnish), so there is nothing stale to purge; run bin/magento cache:flush once after the import and the URL statements, before the first real request, because the configuration cache is built from core_config_data.

The times are an example for a shop whose dump takes ten minutes, whose import takes twenty and whose full reindex takes forty; replace them with the numbers of your rehearsal. Each step has an owner and a stop condition; "stop" means that the cutover is abandoned and the old server leaves maintenance mode (see Rollback plan).

Source: Helm: helm upgrade and Kubernetes: Running automated tasks with a CronJob

The script assumes the chart of the Helm page, whose values and resource names it uses (web.replicas, pocketcoffee-web, pocketcoffee-reindex, pocketcoffee-cron). The CronJob must not run before the cutover: suspend it with kubectl patch (the same command with true) after the first Helm install, or with the equivalent value if your chart has one, and note that a later helm upgrade can revert a patch made by hand, so set the final state in the values afterwards. The config:set of the engine runs in a pod whose root file system is read-only: it writes to the database and to var/, which is an emptyDir; if the command asks for more, run it in the migration Job of the chart instead and treat that as a result of the rehearsal.

Two sets of checks: numbers that must be equal between the old and the new database, and requests through the new stack with the real host name before DNS points to it.

Source: MySQL reference: mysql client options

The two max_ lines catch the order that exists on one side only. The password reaches the client through the MYSQL_PWD environment variable or a defaults file, as in the import script. Then the requests, resolving the real host name to the load balancer of the new stack with --resolve, which tests TLS, routing, the Varnish layer, the media host and the Admin without touching DNS:

Source: curl: manual page

By hand, in this order: log in to the Admin as an administrator and open the configuration of the payment method (it decrypts the stored credentials, which proves the key), place a test order with the sandbox of the provider on the rehearsal copy, open a product page of each store view, search for a product (OpenSearch), open the sales order grid and a recent order, and send a test mail from the order page. Compare the search results count of one query with the old shop.

The rollback is possible because the old server is untouched. What it costs depends on how much time passed since the switch.

Three things make the rollback cheap and must be decided before the cutover: