AEM Cloud Migration: Planning Your Move from AEM 6.5

Migration Overview

Migrating from AEM 6.x to AEM as a Cloud Service isn't a simple upgrade—it's a transformation. The cloud-native architecture requires changes to how code is structured, configured, and deployed. But with proper planning, the migration is manageable and the benefits are substantial.

Most migrations follow these phases:

Phase 1: Assessment

Best Practices Analyzer (BPA)

The Best Practices Analyzer is your starting point. It's an AEM package that scans your existing implementation and generates a report of cloud compatibility issues.

BPA identifies:

• Blocking issues — Must fix before migration (deprecated APIs, incompatible code)
• Warnings — Should fix but won't block (performance concerns, best practices)
• Information — Awareness items (features that work differently in Cloud)

What to Inventory

• Custom components — HTL/JSP components, client libraries, front-end code
• OSGi services — Custom services, schedulers, workflows
• Integrations — External APIs, SSO, analytics, third-party systems
• Dispatcher rules — Rewrites, filters, caching rules
• Content volume — Number of pages, DAM assets, total repository size

Phase 2: Code Refactoring

Package Restructuring

AEM Cloud requires a specific project structure that separates code from content:

• all — Container package that embeds all sub-packages
• ui.apps — Immutable content (components, templates, client libraries)
• ui.config — OSGi configurations (Sling Feature Model format)
• ui.content — Mutable content (sample content for development only)
• core — Java bundle (OSGi services, Sling models)
• dispatcher — Dispatcher configuration module

OSGi Configuration Changes

AEM Cloud uses the Sling Feature Model for OSGi configurations. Key differences:

• Configuration files use .cfg.json format (not .config or .xml)
• Run mode folders: config.author, config.publish, config.dev, etc.
• No custom run modes—only standard environment run modes
• Secrets go in Cloud Manager environment variables, not configs

Dispatcher Configuration

Dispatcher configuration is now part of your code repository and validated at build time:

• Use the dispatcher module with standard folder structure
• Run dispatcher validate locally before committing
• No access to dispatcher servers—all config via Git
• Some directives not supported (e.g., mod_rewrite loops)

Phase 3: Content Migration

Content Transfer Tool (CTT)

The Content Transfer Tool is Adobe's official solution for migrating content:

1. Install CTT on your source AEM instance
2. Create migration set — Select content paths to migrate
3. Extract — Pull content into a migration package
4. Ingest — Push content into Cloud environment

Migration Strategy

For large migrations, plan multiple passes:

DAM Asset Considerations

Large DAM libraries need special attention:

• Renditions — Don't migrate renditions; Cloud regenerates them via Asset Compute
• Size limits — CTT handles large binaries but network speed matters
• Metadata — All metadata and folder structure transfers correctly
• Smart Tags/Crops — May need reprocessing in Cloud

Phase 4: Testing & Go-Live

Testing Checklist

• Functional testing — All components render, forms submit, workflows run
• Integration testing — External systems connect, data flows correctly
• Performance testing — Page load times, Time to First Byte (TTFB)
• Content validation — All pages migrated, assets display, links work
• Author experience — Authoring UI works, permissions correct

Go-Live Checklist

1. Final content migration complete
2. All test cases passing
3. SSL certificates configured
4. Custom domain in Cloud Manager
5. CDN configuration verified
6. Redirects in place (old URLs → new)
7. Analytics/tag management updated
8. Rollback plan documented

Common Migration Challenges

Custom Run Modes

If you relied on custom run modes like config.brand1 or config.region-eu, you'll need a different approach. Options include:

• Context-aware configurations (Sling Context-Aware Config)
• Cloud Manager environment variables
• Content-based configuration nodes

Server-Side Integrations

Integrations that required server access need rearchitecting:

• File system access → Cloud storage (Azure Blob, S3)
• Direct database connections → API-based integration
• Custom JMX beans → Cloud Manager monitoring

Migration Timeline

Typical timelines based on implementation complexity:

• Simple sites (minimal custom code): 3-4 months
• Standard implementations: 4-6 months
• Complex enterprise sites: 6-9+ months

Factors that extend timelines: heavy customization, many integrations, large content volume, regulatory requirements, multiple brands/sites.