Cloud 3.01

Cloud Configuration

Configuring routes.yaml, managing redirects, and migrating on-premises Magento to Cloud.

Exam Critical: Understanding Cloud configuration files (especially .magento/routes.yaml) is essential for the AD0-E717 exam! Know redirect types, domain configuration, and migration processes.

Cloud Configuration

mindmap root((Cloud Config)) routes.yaml Redirect management Domain routing Upstream config Wildcards Domain Variables default placeholder all placeholder Redirect Types redirect type upstream type Partial redirects Starter vs Pro Starter auto apply Pro support ticket Migration Code base Database Media files Configuration

.magento/routes.yaml

Purpose and Power

The .magento/routes.yaml file provides a codified means to manage redirects and routing on your Magento Cloud site.

Benefits

  • No more .htaccess management: Configuration is version-controlled
  • Powerful redirect system: Support for complex redirect patterns
  • Domain management: Handle multiple domains and subdomains
  • Environment-specific: Different configs per environment

Domain Variables

{default} Variable

The {default} placeholder is substituted with the domain name for the environment.

Example Usage

"http://www.{default}/":
    type: redirect
    to: "http://{default}/"

If environment domain is example.com, this becomes www.example.com → example.com

{all} Variable

Use {all} when your site serves multiple domains.

Multi-Domain Example

Useful when serving multiple domains like:

  • https://bonlineco.com
  • https://training.bonlineco.com

The {all} placeholder matches all configured domains.

Redirect Types

type: redirect

Used for HTTP redirects (301/302) from one URL to another.

Example: Enforce Naked Domain (non-www)

"http://www.{default}/":
    type: redirect
    to: "http://{default}/"
    
"http://{default}/":
    type: upstream
    upstream: "mymagento:http"

What This Does

  1. www.example.com → redirects to example.com
  2. example.com → serves Magento content

type: upstream

Used to serve content from the application defined in .magento.app.yaml.

Important Rule

The upstream value (e.g., "mymagento:http") must match the name defined in .magento.app.yaml.

# In .magento.app.yaml
name: mymagento

# In .magento/routes.yaml
upstream: "mymagento:http"  # Must match!

Subdomain Configuration

Serving from Subdomains

You can serve your Magento site from subdomains using .magento/routes.yaml:

Example: Redirect to Subdomain

# Redirect www to shop subdomain
"http://www.{default}/":
    type: redirect
    to: "http://shop.{default}/"

# Serve Magento from shop subdomain
"http://shop.{default}/":
    type: upstream
    upstream: "mymagento:http"

Example: Multiple Subdomains

# Serve Magento from blog subdomain
"http://blog.{default}/":
    type: upstream
    upstream: "mymagento:http"

# Serve from shop subdomain
"http://shop.{default}/":
    type: upstream
    upstream: "mymagento:http"

Wildcard Matching

Using Wildcards

Wildcards allow pattern matching for dynamic subdomain routing:

Example: Scope-Based Subdomains

# Match any subdomain
"http://*.{default}/":
    type: upstream
    upstream: "mymagento:http"

Use Case

Configure subdomains for different Magento website scopes:

  • us.example.com → US store
  • uk.example.com → UK store
  • eu.example.com → EU store

Partial Redirects

URL Structure Migration

Partial redirects help when migrating from an old site to a new URL structure:

Example: Category URL Redirect

"http://{default}/old-category/*":
    type: redirect
    to: "http://{default}/new-category/$1"

Pattern Matching

Redirects like:

  • /old-category/product-1 → /new-category/product-1
  • /old-category/product-2 → /new-category/product-2

The $1 captures the wildcard match.

Domain Visibility in Cloud Admin

Access Site Menu

Any domain added to .magento/routes.yaml automatically appears in the Access site menu in the Cloud Admin UI.

Location: Environment view → "Access site" dropdown

This makes it easy to access different configured domains directly from the dashboard.

Applying Configuration Changes

Starter vs Pro Plans

Plan Type Process Timeline
Starter Changes to .magento/routes.yaml are automatically applied when you merge code Immediate upon merge
Pro (Staging/Production) Must create a support ticket to apply changes Requires Magento Support intervention

Pro Plan Important Note

For Pro plans, changes to .magento/routes.yaml in Staging or Production environments require opening a support ticket with Adobe Commerce Support. The changes will not be automatically applied even after merging.

Migrating On-Premises to Cloud

Migration Overview

Migrating an existing Magento installation to Cloud involves multiple components:

Migration Components

  1. Code base: Application files and modules
  2. Database: Store data, customers, orders, etc.
  3. Media: Product images, category images, CMS images
  4. Configuration: Cloud-specific config files

Step 1: Prepare Code Base

Cloud Configuration Files

Create the required Cloud configuration files:

Required Files

  • .magento.app.yaml - Application configuration
  • .magento/services.yaml - Services (MySQL, Redis, Elasticsearch)
  • .magento/routes.yaml - Routing and redirects
  • magento-vars.php - Environment variables (deprecated in newer versions)

Composer Authentication

Configure Composer authentication credentials using one of these methods:

Method 1: auth.json File

{
    "http-basic": {
        "repo.magento.com": {
            "username": "your-public-key",
            "password": "your-private-key"
        }
    }
}

Security Warning

To prevent auth.json from being visible in production or repository, use environment variables instead.

Method 2: Environment Variable (Recommended)

env:COMPOSER_AUTH

Setting COMPOSER_AUTH Variable

  1. Go to Cloud Admin UI
  2. Click top menu gear icon
  3. Navigate to Variables
  4. Add variable: env:COMPOSER_AUTH
  5. Ensure it's marked as "Available during build"

Require Cloud Meta-Package

composer require magento/magento-cloud-metapackage --no-update

Version Matching

Require the Cloud meta-package with the same version as your existing Magento installation (e.g., if you have Magento 2.4.6, require magento-cloud-metapackage 2.4.6).

NonComposerComponentRegistration.php

Ensure NonComposerComponentRegistration.php is referenced in the files. All new Magento projects already include this.

Step 2: Push Code to Cloud Git

Git Repository

Push your prepared code to the Cloud git repository:

  • Magento's git repository: Default Cloud hosting
  • External git hosting: GitHub, GitLab, Bitbucket (if configured)
git add .
git commit -m "Prepare for Cloud migration"
git push origin master

Step 3: Migrate Database

Database Migration Process

Steps

  1. Export database from on-premises installation
  2. Import to Cloud environment via SSH or magento-cloud CLI
  3. Update URLs to match Cloud domain names

Export Database

# On-premises
mysqldump -u username -p database_name > database.sql

Import to Cloud

# Via SSH
ssh [environment-ssh]
mysql -h database.internal -u user main < database.sql

# Or via magento-cloud CLI
magento-cloud db:dump
# Then import locally and re-upload

Update URLs

UPDATE core_config_data 
SET value = 'https://your-cloud-domain.com/' 
WHERE path = 'web/unsecure/base_url';

UPDATE core_config_data 
SET value = 'https://your-cloud-domain.com/' 
WHERE path = 'web/secure/base_url';

Step 4: Set Encryption Key

app/etc/env.php Configuration

Set the encryption key in app/etc/env.php for each environment:

'crypt' => [
    'key' => 'your_encryption_key_from_old_installation'
]

Critical

The encryption key must match your original installation to decrypt sensitive data (passwords, payment info, etc.).

Step 5: Migrate Media Files

Media Migration

Transfer media files (product images, category images, CMS content) to Cloud:

Using rsync (Recommended)

# From on-premises server
rsync -avz pub/media/ [cloud-ssh]:pub/media/

Using SCP

scp -r pub/media/ [cloud-ssh]:pub/media/

Large Media Libraries

For very large media directories, consider using object storage (AWS S3) or CDN solutions instead of storing everything in pub/media/.

Best Practices

Do's
  • Use environment variables for sensitive data
  • Test routes.yaml changes in Integration first
  • Use {default} for single-domain setups
  • Match upstream names with .magento.app.yaml
  • Create support ticket for Pro route changes
  • Back up database before migration
  • Test migration in Integration environment first
  • Document custom configurations
Don'ts
  • Don't commit auth.json to repository
  • Don't manage redirects in .htaccess
  • Don't forget to update URLs after DB import
  • Don't skip encryption key configuration
  • Don't migrate merchant data without permission (GDPR)
  • Don't forget Pro requires support tickets
  • Don't mismatch upstream names

Practical Experience

Hands-On Tasks

  1. Set up .magento/routes.yaml in your project
  2. Redirect www to non-www (or vice versa)
  3. Configure subdomain routing (e.g., shop.example.com)
  4. Test partial redirects for URL migration
  5. Practice migration with a test site (not production data without permission)

Exam Tips

Key Points to Remember

  • Configuration file: .magento/routes.yaml manages redirects and routing
  • Domain variables: {default} for single domain, {all} for multiple
  • Redirect types: type: redirect (HTTP redirect), type: upstream (serve content)
  • Upstream matching: Must match name in .magento.app.yaml
  • Wildcards: Use * for pattern matching (e.g., subdomain routing)
  • Partial redirects: Use $1, $2 for captured wildcards
  • Starter vs Pro: Starter auto-applies, Pro requires support ticket
  • Migration components: Code, database, media, configuration
  • Required files: .magento.app.yaml, services.yaml, routes.yaml
  • Composer auth: Use env:COMPOSER_AUTH variable (not auth.json)
  • Cloud meta-package: Version must match existing Magento version
  • Database migration: Export, import, update URLs, set encryption key
  • Encryption key: Must match original in app/etc/env.php
  • Media transfer: Use rsync or scp to Cloud environment
  • GDPR warning: Never migrate merchant data without permission
Previous: Cloud 2.02 CLI Tool Practice Cloud 3.01