Steps to plan and perform AEM upgrade

In this post we will see the steps that are required to plan and perform an AEM version upgrade.

Step 1: Establish the objectives
The first step in the migration process is to clearly layout the objectives for the migration.

There could be many reasons why you might want to upgrade your AEM instance. Some of the common reasons to upgrade are

1. An AEM version in use go out of support and you want to be safe and remain on a supported version
2. You wanted to use the new features in a later release and hence need the upgrade
3. You wanted to leverage the enhancements and performance improvements in the later releases
4. You have a bloated CMS, accumulating a lot of junk content over the period and wanted to use the upgrade to cleanup and trim down your CMS
5. You may even be wanting to rewrite your application for a newer version and want to migrate the content over to the new version
6. Or it could just simply be for the reason that you are tech savvy and you don’t want to be on a stale environment or be left behind

The reasons for upgrade could be many. But the important thing to start the upgrade is to clearly establish your reasons for upgrading and their priority.

These reasons typically form the primary objectives for migration and would significantly influence the decisions taken in the subsequent steps

Secondary objectives
You might be upgrading for one or more primary reasons, but you would also want to leverage it to achieve few other objectives. List down all the other objectives that you want to achieve along with the upgrade.

Some examples of such objectives are

1. Migration the infrastructure to the cloud
2. Move the datastore to S3
3. Migrate to MongoMK from the current TarMK setup or vice versa
4. And so on…

By the end of this exercise, have a listing of all objectives to be achieved with the upgrade, classifying them into primary and secondary objectives.

This would greatly help in making the right choices in the subsequent steps of the migration

Step 2: Finalize the target version to migrate to
This might seem trivial but it’s prudent to give some consideration before finalizing the target version to migrate to.

The default choice is to migrate to the latest available version, but consider the AEMs release timeline to decide if you can wait for some time for the next release before performing the migration.

Or to be safe, you might not want to move to the version that just got released but instead wanted to move to the latest – 1 version so that the stability is guaranteed.

Step 3: Assess the current state
Once you have established the objectives for the upgrade, the next step is to analyze the current state and document it (or update your documentation if there is already one present).

The current state document should include all the details relevant for migration, including

1. The topology of the deployment – including all components (Author, Publish, Dispatcher, integrations, third party systems, …) and their specifications
2. Current infrastructure details
3. Operating systems and JRE versions the current environment is on
4. The size of your current repository, and how recently / frequently the compaction and maintenance jobs are run
5. The sanity and validity of the content accumulated – How much of your current content is junk?
6. A listing of OOB components and services used by the application
7. Details of all the custom components and services deployed. How frequently do they change? Is there any development work in progress? What is the release cycle followed? When is the next release planned?
8. Document all the customizations done on the AEM directly (OSGi configurations, Workflow customizations, Overlays, User/User Groups, ACLs,…)
9. Document all the indexes used (OOB or custom indexes created). Newer versions do not come with indexes pre-defined and we will have to plan creating all missing indexes when migrating
10. Document the users and usage volume – No. of users, frequency of access and authentication, authorization mechanisms
11. Does the application generate UGC content? How much is the volume of content created each day?
12. Detail of integrating systems and integration approach followed by each. Are the regular feeds into AEM or going out of AEM?
13. Constraints and limitations in the current setup that you would like to be addressed in the target environment

With the objectives established and detailed analysis done on the current state, we can jump in to define the target state on the decided target AEM version.

Step 4: Define the target topology
Based on the objectives for the upgrade and the current state assessment, define the target topology to migrate to the target version.

This topology defines the deployment architecture of the target environment with all components included (author, publisher, dispatcher, integration systems and third party systems).

Validate the infrastructure, OS and JRE requirements for the target version to migrate to and arrive at the hardware, OS and software update requirements for the target environment

Step 5: Agree on the migration and cutover downtime
It is extremely critical to agree with all stakeholders on the downtime that the upgrade would need. The approach taken for migration would be influenced by the downtime that can be taken up.

Also check if authoring freeze can be brought in during the migration window so that new content is not getting created when migration is happening.

Applications handling UGC content brings in additional complexity, which has to be factored in for migration

Step 6: Finalize the approach for upgrade
Based on the objectives, current state assessment and the target topology, finalize the approach for upgrade.

Basically there are two approaches to choose from for migration

• Direct instance upgrade or In-place upgrade where the current instance with all the contents in it is migrated to the target version
• New installation in which a fresh install of the target version is done with content extracted from the current instance and migrated over to the target instance

Choose which approach to adopt for your upgrade.

If the upgrade involves cleaning up of significant part of the content or change in deployment architecture (like moving from TarMK to MongoMK or vice versa), the new installation approach would be appropriate.

On the other hand, if you need to retain all revision history, audit logs and when cleanup is required, direct instance upgrade would be appropriate.

Step 7: Prepare for the migration
With the approach for migration decided, now it’s time to build the pieces that are needed to do the migration. This would involve

• Getting the infrastructure for the target state ready, with OS and JRE matching the requirements for the target state. Some spare capacity is required to setup the environments for testing the migration
• Updating if required and making sure the application code builds and deploys to the new environment and preferably does not use any deprecated APIs
• Keeping ready all the maintenance processes (cleanups, compaction…) and backup scripts, to be used before the migration
• In case where content cleanup is required, device an approach to identify active content and eliminate stale content
• Creating scripts and commands to extract and sync content to target environment
• Make ready the scripts for creating the replication agents and dispatcher flush agents for the target environment
• Validate the authentication configuration and authorization mechanism in the new version
• Create the test plans to validate the migration. Test plan to cover all the functional and non-functional aspects of the application
• Following points apply specifically for the fresh install
• Check the customizations done directly on the AEM and move those to code and scripts where possible. Create document & checklists for performing custom configuration in the target environment for items that cannot be moved to code / scripts
• Check the indexes in use in the current application and have the configuration ready to create them in the target environment
• In case where users need to be migrated, create sync scripts to migrate users and their ACLs
• Work out the details for performing the migration on different components (Author, publish and dispatcher)

By the end of this exercise, create a process document and checklists for executing the migration.

Make it comprehensive and cover all aspects of migration including the pre-migration steps (running the maintenance procedures, taking backups), migration activities (executing the actual migration), post migration activities (validation, cut over steps, and covering changes in ops and dev ops processes post migration) and fall back procedures (rollback option).

This aids the execution process greatly and ensures none of the steps gets missed out. Also these documents help bring clarity to all stakeholders during execution.

With the preparation compete, we can jump in to do a test migration on a lower environment.

Step 8: Perform test migration and validate
With the preparation done, it’s time to perform a test migration.

For direct instance migration, cloning the production instance and performing the test migration on the cloned instance is preferred.

For fresh install, plan to sync content as closely with production as possible when performing test migration.

Execute the process as documented in the previous preparation step. Follow the document religiously, updating the document if required to reflect actual execution.

Cover all aspects of migration starting with the pre-migration steps and following through to simulate cutover. Do not miss to simulate rollback scenario so that you are prepared for the worst case if the need arises when migrating your production.

Make sure to measure and validate the following in the test migration

All the objectives set for the migration are achieved
The application functions and performs as expected in the target environment
You would be able to meet the downtime limits agreed for the migration

Step 9: Tweak the process and repeat test migration (Optional)
This optional step can be applied if required. If you are not able to meet any of your set objectives or if any change is needed in the migration execution, make sure to update the migration document and repeat the test migration starting from the beginning.

You may end up in situation where you have to go back to preparation step (step 7) to cover for any gaps identified and come back to step 8 to redo the test migration.

It’s essential to make sure a full end-to-end cycle of migration is performed in the test environment to be absolutely sure of repeating the same in production.

By the end of this exercise, you should have performed an end-to-end test migration and have a proven migration document that can be followed for doing the migration in production.

Step 10: Redefine the dev, ops and devops processes
After the successful test migration, you might want to start aligning the development, operations and dev ops processes for the target AEM version.

Also start planning the migration for your lower environments (Dev, stage, …) to the new version. Update the maintenance procedures for these lower environments for the new AEM version.

Development can also shift to the new version and sub-sequent releases can be planned for the new version. Dev ops process can now be updated for the new AEM version.

With the test migration successfully completed.

Step 11: Train all stakeholders to get them ready
Training is an often overlooked aspect of migration. Make sure you do not miss this important step and cover the training for all the stakeholders, including

• Business team who use AEM day to day for authoring and publishing
• Developers and the support team who customize, fix issues that arise and build new features
• Administrators and the operations team who maintain and manage the environments

The training could even be a self-training where the stakeholders explore the newer version on their own with the aid of documentation or video training materials available. Or it could be a classroom training conducted by a professional services team.

Whatever be the mode of training, make sure to cover this important step. This helps to bring every one on-board and get them excited about the new version you would soon be switching to.

Step 12: Finalize the date(s) for performing the migration
You might have had a target period for completing the migration even before the start of this migration exercise.

One of your stated objectives could be say ‘the migration has to be completed before the end of the mentioned year / quarter” or “before the beginning of a peak season”.

But as you complete your preparation and testing and are nearing the final migration, it is very critical to fix specific dates during which you will carry out the migration.

If your scenario involves putting an authoring freeze during the period of migration, finalize the authoring freeze period. You may want to bring down the web server or disable the gateway to the authoring instance during this period to avoid accidental changes to the content.

Take care to choose a non-peak day and off peak hours to run the final migration impacting end customers. Inform all stakeholders, and declare your downtimes if needed. Plan to bring up your application maintenance page during this period.

Step 13: Socialize your fallback options
Things do go wrong and unexpected does happen at times. Keep all stakeholders appraised of the various fallback options you have in place.

Especially keep all the key decision makers informed so that an informed decision can be taken quickly, if something goes wrong during the execution.

By now you have covered all bases, prepared and fully ready for the final migration. The final part of this series has the steps for the final migration run.

Step 14: Perform the upgrade
Finally, here you go… Go-ahead and execute the migration as you have defined in the migration document in step 7 and validated on a test environment in step 8, 9.

Do not experiment or take any deviation when running the migration in production, especially when you are handling a complex installation with large repository and voluminous content.
Stick to the tested process, making sure you are not skipping or missing out on anything.

If something goes wrong or you get into a scenario which did not occur in the test configuration, assess the situation and kick off the rollback process if needed.

And if everything goes fine, well your migration gets complete and you are ready to expose it to the world!!!

Just hold on... not before its tested and certified

Step 15: Test and certify
Make sure your application is sanity tested after the migration. Certify that the application is working fine and open it up to the world.

Step 16: The new normal
Embrace the new normal. Adopt the changes in development, operations and dev ops processes. And somewhere down the line, you will be in for another upgrade!!!

Disclaimer
This is a generalization based on my experience with handling AEM upgrades. Please do check the official documentation for upgrade available (it’s at https://helpx.adobe.com/experience-manager/6-5/sites/deploying/using/upgrade.html for AEM6.5) which contents version specific instructions and points to check for performing the upgrade