AEM Upgrades ‑ A Quick Guide to Minimize Your Risk
The time has come to upgrade your Adobe Experience Manager (AEM) instances. Maybe Adobe Managed Services (AMS) is encouraging you to update to remain on a supported version. Maybe your on-premise instances are several versions behind and you need/want to upgrade in order to get performance improvements and/or new features. Maybe you just have a lot of free time on your hands and you really enjoy software patching (really?).
There are two main approaches to an AEM upgrade: the inplace upgrade and the fresh install. Before diving into the pros and cons of each, please take time to review Adobe’s own upgrade guidelines.
Approaches
Option 1 - In-place upgrade
An in-place upgrade works by taking your existing AEM instance and converting the instance and all the content inside of it to the new version. Even with an in-place upgrade you should still consider cloning the environments to new servers first so that you have an easy rollback plan.
|
PROS |
CONS |
|
Adobe-/AEM-supported process. |
Depending on the version difference between the old and new instances, the upgrade can be a long and arduous process (Adobe has made great strides to simplifying this in more recent versions). |
|
No moving of content packages, especially in cases of an extremely large DAM. |
Potential strange scenarios caused by upgrading a system vs. starting fresh (you’re bringing all the junk along with you). |
|
No need to republish content after migration. |
Complex developer setup and automation of the upgrade process. You need to fire up an instance of the old AEM version, sync the content, then execute the upgrade to the new AEM version. |
|
No risk of forgetting pieces of content in the upgrade process (which can extend to items outside of /content). |
Lost opportunity to remove content that is no longer in use, as it will likely not be reviewed. |
|
ACLs/users/groups remain in place. |
|
|
Content revision history is preserved. |
|
Option 2 - Fresh Install
A fresh install would generally be done on a new server but could also be done side by side on an existing server. That instance would just need to exist in a different directory to have a completely new content repository. In that case you will either need to only run one server at a time or make sure to use different ports.
|
PROS |
CONS |
|
A "fresh start" where you can remove cruft of miscellaneous hacks that were done via the AEM UI and admin interfaces (CRX, Felix, etc.) and were relevant to the older AEM version or were done with incomplete understanding. |
Potential to forget pieces of content to migrate, especially items outside of /content. This results in a higher chance of bugs that will get through to production due to being missed by testing. |
|
Simpler server upgrade process with less points of failure, especially if jumping multiple versions, since there is no true server "upgrade" process happening - you're simply installing to a fresh server already on the new version. |
Potential to miss important OSGi configs set via Felix console and not from code packages. This results in a higher chance of bugs in behind the scenes processes that are not immediately apparent. |
|
Easier developer setup and automation of the upgrade process, as it requires less steps. Simply fire up a new server instance and sync the content. |
Syncing large content packages (particularly assets) can be very time consuming (i.e. days). |
|
Avoids potential strange scenarios caused by upgrading a system vs. starting fresh. |
Content must be published from the author to the publish server OR content must be synced separately to the publish server. |
|
|
ACLs/users/groups must be recreated. |
|
|
Content revision history is lost (unless you still use crx2oak migration tool). |
Planning your work
If you don’t find yourself aligning towards one approach, the general consensus is to go with the in-place approach as it is Adobe’s recommended and fully supported approach. As a general rule of thumb, you should go with an in-place upgrade unless you have an instance that has accumulated a lot of “stuff” (pages, assets, code, tags, etc) over time.
Now that you picked your approach, it’s time to get to work. You can use all the items listed below to estimate and plan out a release related to your upgrade. The work will generally fall into the three categories listed below.
The Standard
Before starting anything, create an upgrade-specific branch of your code. Do not make upgrade-specific changes directly in your develop or master branches. This way if there are any features or bug fixes that need to be addressed in the existing AEM version you can complete those in the normal branches. Please note that if there are changes happening in those branches, you will need to make sure you are merging those changes into your upgrade branch often to avoid merge conflicts down the road.
- Run out-of-the-box (OOTB) tools to test for upgrade readiness.
- Use the AEM console at http://localhost:4502/system/console/depfinder to determine version updates needed for both OOTB and non-OOTB dependencies.
- Verify that your package not only builds, but deploys successfully to the new AEM version.
- Develop a comprehensive test plan for all sites.
- Review build and runtime logs for WARN and ERROR messages.
The Often Overlooked
You might get lucky and just doing the basics might be enough to launch your AEM upgrade to a production environment. That being said, the following are things that can be easily overlooked and can cause you problems down the road. It’s best to look at these now and improve your codebase where possible.
- (Fresh install approach) Create and document sync commands to sync content from the old AEM servers to the new.
- (In-place upgrade approach) Migrate content from production to lower environments before testing the upgrade.
- Smoke test using the comprehensive test plan early on in the process.
- Remove all obsolete code.
- Inventory and test all OSGi services and external integrations.
- Inventory and test all JCR queries. Add necessary indexes as Newer versions of AEM may require explicitly setting some indexes that weren’t needed in older versions.
- Inventory and test all data APIs (web services).
- Inventory and test all AEM code overlays and tight integrations.
- Review and potentially update component and page dialogs. In newer versions of AEM coralui2 might have deprecated certain components (for example, datepicker). Coralui3 info can be found here.
- Review and update all uses of deprecated APIs (both AEM and non-AEM).
- Review OSGi configurations made from the Felix console and migrate to the codebase where appropriate.
- Review workflow modifications made from the AEM UI. Capture all the modifications so that they are included as part of the upgrade process.
- Add ACLs for tags (/etc/tags was allowed by default in 5.x).
- Determine ACLs and User Groups. This can be an opportunity to improve/simplify existing ACL and User group setups.
- Upgrade LDAP authentication integration, if applicable.
- Upgrade personalization engine from Client Context to ContextHub.
- Review third-party packages and upgrade if necessary.
- Upgrade dispatcher version and associated configurations.
- Inventory and test all web server (e.g. Apache) redirect and rewrite rules.
The Extra Mile
Any new AEM project should include things like an AEM runbook and comprehensive test plan as part of its initial launch. These are types of things that easily fall out of date, as once they are completed they generally tend to be forgotten. During an upgrade is the perfect time to take stock of these things and bring it all up to speed.
- Migrate code from administrative resource resolver (deprecated) to service users.
- Create Touch UI code overlays to match Classic UI code overlays. Move customizations away from classic UI where possible.
- Update your AEM Runbook. Most likely your runbook was created and then your system has had numerous updates that aren’t reflected in it. This is a good opportunity to get it up to date since you will most likely be in there changing server addresses anyway.
- Create an automated build to execute a full, repeatable upgrade. You can test out an automated upgrade process in a lower-level environment and then utilize and that process across your other servers. By the time you get to a production install you will have an easily repeatable and successful process.
Special Considerations
- What if you are using MongoDB for your repository? You shouldn’t have to do a content migration on this, however you might need to update your version of Mongo to match what is supported for your target version of AEM. You can check Adobe’s in-place upgrade documentation to determine when repository content migration is required.
- What if you have an extremely large repository? For one, you are going to need to factor in time for this. If you do an in-place upgrade, the repository migration is going to take longer. If you do a fresh install, then moving the content via packages is going to take some time. There are a couple things you can consider for this. As noted in Oak’s documentation under “Incremental Migration,” you can do the production migration early and then rely on incremental migrations between that time and the actual production release date. Also, if possible you can consider bumping up the processing power on the servers running the migration temporarily until the migration is complete. Lastly, if you are seeing that the migration is taking several days even in your lower environments, I suggest reaching out to Adobe support to help determine an appropriate plan for your use case.
Now that you’ve picked an approach and planned out the tasks for moving towards a release, it’s time to get the work started. Good luck and happy upgrading!
