Migrating to AEM as a Cloud Service: Lessons Learned

In the Architecture series we compared AEM 6.5 with AEM as a Cloud Service and listed the migration tools. This post is the practical companion: how a migration actually unfolds, where teams lose time, and what to do early to avoid it. It's organized around the phases of a typical project.

The Big Picture

A Cloud Service migration is really four migrations at once:

Teams that treat it as "just move the content" run late. Teams that treat it as a platform change with four coordinated tracks tend to deliver on time.

Phase 1: Assess

Run the Best Practices Analyzer (BPA) early, before you commit to a timeline. It scans your 6.5 instance and reports patterns that won't work on Cloud Service. The report drives your estimate far better than guesswork.

What to do with the findings:

• Group them by effort: quick fixes, moderate refactors, redesigns
• Find the redesigns first. One or two of these (a custom replication-based integration, for example) can dominate the schedule
• Inventory integrations: every system that calls AEM or that AEM calls
• Inventory custom code and third-party packages: check each for Cloud Service compatibility
• Measure the content: size of the repository, number of assets, versions, and how much of it is genuinely needed

Use Cloud Acceleration Manager to track the work and BPA results in one place.

Lesson: Clean Before You Move

Content you don't need costs time, storage and transfer effort. Before migration:

• Purge old versions and audit logs according to your retention policy
• Remove unused assets, abandoned sites and test content
• Decide what you will not migrate, and get that agreed in writing

Phase 2: Modernize the Code

Restructure the Repository

Cloud Service separates immutable content (/apps, /libs) from mutable content (/content, /conf, /home and others). Use the Repository Modernizer to restructure your project into packages that respect this split, then review its output instead of trusting it blindly.

Common problems it surfaces:

• Code that writes to /apps at runtime. This now has to move to a mutable location or be redesigned
• Packages that mix immutable and mutable content
• Hard-coded paths that assume the old layout
• Repoinit needs: users, service users, ACLs and base folder structures should become repoinit scripts

Move to the AEM SDK API

Replace the full AEM uber-jar dependency with the AEM SDK API, which exposes only the supported APIs. Compile errors here are useful: they tell you exactly what to replace.

Refactor the Usual Suspects

Lesson: Do the Refactoring on 6.5 First Where You Can

Many changes (service users, the SDK API, restructuring, cleaning up scheduled jobs) can be done while you are still on 6.5, then deployed there and tested. That shrinks the final cutover to "move and verify" rather than "change everything at once."

Phase 3: Configuration and Dispatcher

Dispatcher

Use the Dispatcher Converter for a first pass, then:

• Validate with the SDK validator, in your CI build, not just on a developer machine
• Test locally in Docker
• Expect to rework filters, rewrites and virtual hosts, because the cloud configuration is more prescriptive
• Remember the immutable files you can't change
• Review cache rules and TTLs for the CDN that now sits in front

Environment Configuration

• Move environment-specific values into Cloud Manager environment variables and secrets
• Use run modes (author, publish, and environment types) for config that differs
• Review integration credentials. Nothing sensitive should be committed to the repository

Networking and Integrations

Third-party systems often depend on fixed IP addresses or network paths. On Cloud Service, outbound traffic doesn't come from a single known server, so if a downstream system allows only specific IPs, look into Adobe's advanced networking options early, since provisioning takes lead time. Also review:

• CORS policies for front-end applications
• SMTP/email configuration for any outbound mail
• Inbound access for external systems that call Author or Publish APIs

Identity and Access

User management moves to Adobe IMS: users and groups come from the Admin Console, and single sign-on is configured through your identity provider. Plan the group structure carefully, because it replaces locally managed users and permissions in many cases. Review any custom authentication handlers.

Phase 4: Content Migration

The Content Transfer Tool (CTT) moves content in two stages:

1. Extraction: content is read from the source repository into a staging container
2. Ingestion: content is loaded into the target cloud environment

How It Usually Goes

• Plan multiple passes. A first full transfer, then top-up transfers that bring only the differences. This keeps the final window short
• Large binary stores (very large DAMs) can take a long time to move, so start early and consider the pre-copy options Adobe documents for blob data
• Validate after every pass: counts of pages and assets, spot-checks of key sections, permission checks and reference integrity
• Fix problems at the source where possible, then re-run the top-up
• Reprocess assets after ingestion where needed, since Cloud Service generates renditions through processing profiles, and old renditions may not match your new profiles

Lesson: Rehearse the Cutover

Run the complete content move at least once in a non-production environment, with timing. The first rehearsal almost always finds surprises (a missing permission, a slow stage, a broken reference), and you want them in rehearsal, not on cutover night.

Phase 5: Pipelines, Testing and Operations

Set Up Cloud Manager Early

Pipelines are the only supported route to deploy code to Stage and Production, so get them working while development is still happening:

• Code quality gates will fail builds that contain critical issues. Run the scans on your codebase early, so you aren't discovering hundreds of findings the week before launch
• Create separate pipelines for dev and stage/production
• Establish branching and release rules that fit the pipeline model

Testing

Take a performance baseline on 6.5 before you start, otherwise you can't prove (or disprove) that the new platform performs as well.

Operations

• Configure log forwarding to your logging platform, and set up alerts
• Learn the Developer Console and how to download logs, since server access no longer exists
• Document how to run incident response without SSH, including who contacts Adobe and when

Phase 6: Cutover and After

The Cutover Plan

A typical cutover sequence:

1. Announce the content freeze well in advance
2. Run the final top-up content transfer
3. Validate content, permissions and critical journeys
4. Finalize DNS and CDN changes, with reduced TTLs set in advance so the switch propagates quickly
5. Smoke-test the live site and key integrations
6. Monitor closely for a defined period, with named people on call
7. Keep the old environment available for a rollback window, then decommission on a schedule

After Go-Live

• Review performance and cache behavior with real traffic
• Run author training, covering what's different (for example, publishing behavior and asset processing)
• Capture lessons learned and update runbooks
• Plan for continuous updates: Cloud Service updates arrive regularly, so keep a lightweight regression suite and watch the release notes

A Sample Timeline

Every project differs, but a mid-size migration often looks like this:

Treat these as rough proportions to sanity-check a plan, not as a promise.

Top Lessons, Summarized

1. Run BPA first and let it shape the estimate
2. Find the redesign items early. They, not the volume of work, set the schedule
3. Clean the content before you move it
4. Do as much refactoring on 6.5 as you can before the cutover
5. Validate Dispatcher in CI and test with the real CDN behavior
6. Plan networking and identity early, because they depend on other teams and lead times
7. Move content in passes and rehearse the cutover
8. Get pipelines and quality gates working early
9. Baseline performance on 6.5 so you can compare fairly
10. Train authors and operations, because the platform feels different even when the editor looks the same

Series Wrap-Up

That completes Advanced AEM & Career, and with it the five-series AEM learning path on this blog. You've now covered:

• Foundations: what AEM is, its architecture, Sling and project structure
• Core Development: components, HTL, Sling Models, dialogs and content fragments
• Assets: workflows, Smart Tags, DAM design and Asset Compute
• Architecture and Operations: Dispatcher, replication, Cloud Service and performance
• Advanced topics and career: headless GraphQL, Edge Delivery Services, interview preparation and migration

From here, the best next step is to build something real: a small headless front end, an Edge Delivery Services site, or a migration rehearsal of a sample project. Then write about it, because the posts that help other developers the most are the ones that start from a real problem you solved.