Upgrading to RPI v7.x with a parallel environment
Overview
RPI v7.x is the current version of RPI that is actively updated and enhanced. RPI v7.x is a containerized version of RPI which can be deployed on container management software like Kubernetes (K8s), while RPI v6.x was installed on a physical server or virtual machine. This document reviews the approach and considerations to migrate from RPI v6.x to RPI v7.x using a parallel install of v7.x.
Parallel upgrade vs. in place upgrade
You have the option to do a parallel upgrade or an in place upgrade. Alternately, you may do a combination of parallel upgrades in a lower environment to validate the process and ensure everything works as expected followed by an in place upgrade of the upper environments, including production. Using this approach, after a successful parallel upgrade, you would shift to an in place upgrade and perform in place upgrades of the upper environments based on the validation and learnings from the parallel upgrade. There are pros and cons to each approach, and they need to be considered to determine your best path forward.
Parallel upgrade illustration
The following is a high-level illustration of a parallel upgrade.
In place upgrade illustration
The following is a high-level illustration of an in place upgrade.
Upgrade considerations
Non-production vs. production
Non-Production: these environments are lower-level environments, for example, development, test, and staging. Start with the lowest level environment and duplicate the components for testing as a starting point. Depending on what you plan to do for production after performing a duplicated upgrade and working out any issues, you may want to do a final in place upgrade of the lower environments if that is how you plan to perform the upgrade in production.
Production: for the production environment you can either do an in place upgrade or duplicate the components as done with the non-production environments.
Why and when to use parallel upgrade vs. in place upgrade?
When doing a parallel environment upgrade, you can always shut down the upgraded/duplicated environment and turn the v6.x environment back on.
Doing an in place upgrade would require a restoration of the original environment to fall back to version v6.x.
How do multi-node v6.7 environments translate in v7.x?
RPI v6.x environments with multiple nodes for failover and scalability would translate to K8s-based scale-out of the containers based on environmental scaling configurations.
Environmental components to duplicate
Ops databases
Make copies or backup/restore the following databases so they can be used in the upgrade process:
Interaction
Interaction Audit
Pulse
Pulse Logging
Data warehouse and auxiliary databases
These databases should be backed up at a minimum, but creating a copy to perform the upgrade against is the highest level of separation between environment versions as well as the quickest way to fall back to the older versions, if needed.
Queues
Creating separate queues will provide a high level of separation between the environments, but as long as both systems are not on at the same time and the queues are fully drained, then the same queues may be used for the upgrade validation process.
FormSubmissionQueuePathWebCacheQueuePathWebEventQueuePathRPIListenerQueue
File shares / output locations
File share references as well as External Content Providers (ECPs) should be identified and new ones established for duplicate environment upgrade process.
File Shares
ECPs
Azure Storage
Amazon S3
Google Cloud Storage
FTP
Web Publish Sites
Channels
Channels should be disabled so that they will not execute a send but the workflows can be run to test the execution up to the point of sending through the 3rd party channel. Channels will not require duplication but in both Non-Production and Production environments you should put measures in place to prevent accidently sending messages until you are ready to cut over to the new version of RPI.
Callback servers
Any callback servers will need to be duplicated for end-to-end testing.
Key v7.x upgrade configurations
Mapping to parallel component instances
Firewall rule to prevent outbound message execution
Disabling workflows
Setting fulfillment channels to “do not send”
Offer history ID seeding
This can only be done if the data warehouse is duplicated since in some of the supported data warehouses the actual tables maintain the IDs. For instance, SQL server uses an identity column to support assigning a unique ID to the records. So, in order to adjust this ID, you will need a copy of the offer history table/database. We do not recommend using offer history tables with different names for testing, as this alters the configuration of the audience definitions, it will not provide a true one-to-one comparison for the upgrade, and it opens up the opportunity to forget to adjust the configuration back and generate undesired results at the end of testing.
Prevent outbound channel execution from parallel environment
In order to prevent accidental outbound sends via native channels, you need to ensure that the firewall/egress has rules in place to prevent this parallel environment from accessing external resources. If you want to test a specific outbound channel, this should be done after initial testing, and it should be a coordinated effort where the firewall/egress rules are adjusted for the duration of the test and then turned back on to prevent accidental sends.
Running the upgrade in the parallel environment
Refer to the v7.x upgrade documentation.
Here are the high-level steps:
Make copies of environment databases
Run v7 configuration script against v6
Use configuration script to prepare v7 deployment
Adjust configuration for all of the copied resources
Fully back-up and shut down v6 environment and databases
Execute v7 upgrade
Test v7 upgrade to validate all active features are tested
If there are any issues, they will need to be resolved before installation is a success
If all looks good, then parallel install is a success
If you are planning to do an in place upgrade, then you would repeat this process from step 3 on with configuration script results unmodified
If you are planning to migrate to a parallel environment, then the process is complete and you can move on to other upper environments, including production
Recommended post-upgrade testing
You will want to perform some general tests as well as some specific tests to evaluate some of the specific functions that you have deployed.
General system test
Catalog: validate that you can sync the catalog successfully.
Selection Rules: test a selection rule for each resolution that is configured.
Audiences: test an audience for each audience definition configured.
Simple Interaction: test a couple of interactions to ensure successful end-to-end completion.
Test an interaction writing to a control first.
Test an interaction with a channel.
Ensure that the script to disable channel execution has been run before you run these tests.
Realtime components:
Test creating visitor and profile and ensure the data makes it to files or the database, depending on how things have been configured.
Test Realtime decision.
Test Realtime events:
Events
Queue listeners
Client-specific system test
The goal of these smoke tests is to ensure that the system is operating in version 7.x as expected for your custom specific configurations. We recommend selecting a subset of campaigns and components that are representative of the overall functionality being supported by the system. We refer to this as MVP (Minimum Viable Product) testing. The idea would be that if you have 50 campaigns that execute with an email channel, one email campaign would be representative of that functionality for all 50 campaigns, so you only need to test one campaign as a part of the MVP testing.
Generally speaking, the high-level areas of consideration when determining what is considered to be MVP for your system are:
Interactions
Different interaction trigger types
Manual
Recurring
Delay
etc.
Audiences
Batch
Interactive
Channels
Email
SMS
Extracts
Data onboarding (Google Ads, Facebook, etc.)
etc.
Web Adapters
Realtime
Test publishing smart assets
Test Realtime decision to validate response and correct responses
Test queue listeners
Test sending events
Confirm events pushed into database
Conclusion
Using a parallel installation is a good approach to validating the upgrade process for doing in place upgrades and ensuring that everything works as expected before performing an in place upgrade. You can migrate over to the parallel environment as well vs. following it up with an in place upgrade. The second option will give you the ability to fall back to the v6 deployment; however, this is not recommended. If you do fall back to the v6 deployment, then you may need to bring data from the new offer history tables back to the original system. This may require that you adjust some of the ID values to bring in the new information without causing the generation of IDs to cause duplicates.