Note: If you are already on 24.1.x and are upgrading to 24.3 - you do not need to follow the instructions in this KB. This KB is for those upgrading to 24.1.x or 24.3.x from 23.3; 23.1; 22.4; or 22.3.
When upgrading to Trust Protection Platform (TPP) 24.1 or 24.3, you should follow the same decision-making strategies, preparation tasks and installation procedures you use for typical TPP server upgrades. See Upgrading Venafi Platform.
However, please note that when upgrading to TPP 24.1 or 24.3, you will see two differences from the typical upgrade process: (1) an enhancement to the TPP 24.1/24.3 installer called PreFlightTool that reports the platform's readiness to upgrade, and (2) an automated temporary suspension in operations during the upgrade's final migration processes.
The following is more information about these two additional processes.
TPP 24.1 Installation Program Scans for Potential Upgrade Issues
As part of the TPP 24.1 installation program, the PreFlightTool scans your system's current configuration and reports its readiness for the upgrade. The purpose is to alert you about potential issues or incompatibilities before proceeding with the upgrade, so you can either fix them or understand the implications in consultation with Venafi.
The tool performs the following checks:
- Message Bus: Provides information about the Message Bus requirements
- DN Length Check: Provides a list of objects that exceed the maximum DN length limit. Any objects in this list must be addressed before upgrading.
- Duplicate Objects Check: Identifies a list of duplicate objects according to the relations table. Any objects in this list must be addressed before upgrading.
- DB Disk Space: Provides an estimate of the additional disk space required for the database to accommodate the upgrade and migration.
- Obsolete CAs: Identifies any obsolete Certificate Authorities (CAs) present in the system.
- Obsolete Applications: Detects any obsolete applications installed.
- Third-party Attributes: Checks for attributes that are not part of the shipping product.
Integrated in the TPP 24.1 and 24.3 installation program, the PreFlightTool generates a summary of these checks, and you can save the results to review or share with the Venafi support team if you need assistance resolving any identified issues.
Temporarily Paused Operations During Final Migration
After upgrading a standalone TPP server or after upgrading the last TPP server in a cluster, there is a specific stage during the upgrade to TPP 24.1 or 24.3 where operations are temporarily paused. This pause occurs during the "Config Data Migration" task, which is one of the migration tasks that runs after a standalone TPP server or the last TPP server in a cluster has been upgraded to TPP 24.1 or 24.3. See About rolling upgrades.
Key points about the pause:
- The pause only happens during the "Config Data Migration" task and not during the entire upgrade process.
- The duration of the pause depends on the amount of data to be migrated. It is estimated based on the data size, but the exact time can vary. For a system with 1.3 million objects, the pause is estimated to be around 6-8 minutes.
- During the pause, if a user tries to access the Aperture console, they will see a loading screen until the migration task is completed.
- If the "Config Data Migration" task fails, the system will roll back to the pre-migration state (running on the old version), and the task will retry after a certain interval (1-5 minutes). Users may experience intermittent pauses during this period.
- The pause is necessary to ensure data consistency during the migration and to prevent any conflicts between the old and new versions.
Although you can't use TPP Admin Web Console (Aperture) during the pause, you can run PreFlightTool from the command line to view the status of the last 20 migrations.
PreFlightTool is available as part of the "Venafi Trust Protection Platform 24.X.zip" file at download.venafi.com. After running the installation, PreFlightTool is located on the TPP server at \Program Files\Venafi\Utilities.
------------------------------------------------------------------------------------------------------
More information and examples
PreFlightTool runs automatically during the 24.x MSI installation. The following screen displays.
- 'Check Now' means to run PreFlightTool directly from the MSI.
- 'Ignore & Continue' means to proceed with the installation without running PreFlightTool.
- 'Install Later' means to exit the installer.
Note: PreFlightTool does not automatically run during silent MSI installations.
PreFlightTool Checks
The following checks are available in PreFlightTool.
Message Bus
A functioning Message Bus is very important to the success of your TPP deployment. This node is informational and direct you to important information.
DN Length Check
This node will indicate any objects that exceed the maximum legal DN length. Any items listed in this node must be addressed prior to proceeding with the upgrade.
Query powering this task:
SELECT co.[parent], co.[name] FROM [dbo].[config_objects] co
WHERE (len([parent]) + len([name])) > 254
AND NOT EXISTS (SELECT TOP 1 1 FROM [dbo].[config_object_rels] rels where co.Id=rels.Id AND rels.ParentId = (SELECT Id from [dbo].[config_objects] ico where ico.[Parent]='\VED' AND ico.[Name]='Intermediate and Root Certificates'))
Duplicate Objects Check (added in 24.1.2)
This node will indicate any duplicate objects according to the relations table. Any items listed in this node must be addressed prior to proceeding with the upgrade.
The first step to troubleshooting this issue would be to run this query:
select * from config_objects co where [id] in (
select id from config_object_rels where [ParentID] = {ParentID} and [Distance] = 1)
and co.[Name] = '{Object Name}';
With the data in the screenshot the query would be:
select * from config_objects co where [id] in (
select id from config_object_rels where [ParentID] = 1153008 and [Distance] = 1)
and co.[Name] = 'Certificates';
If one of the duplicate objects is in the Recycle Bin (\ved\bin\...), then simply purge the item from the Recycle Bin. For any other path, please contact Support.
DB Diskspace
This node provides information such as the amount of extra diskspace required for migration and the estimated time to complete the ‘Config Data Migration’ task.
Obsolete CAs
If previously obsoleted certificate authority objects are found in your environment, this node indicates the names of the objects to be migrated to the 'Out of Band CA' certificate authority type.
Obsolete Applications
If there are previously obsoleted applications objects in your environment, this node indicates the names of objects to be migrated to the 'Basic App' application type.
3rd-Party Attributes
If a custom configuration schema was added to your environment through customer or third-party development, this node indicates the involved attributes. It is important to reach out to your Venafi account team before proceeding with your migration, as these attributes may require special attention.
Summary
Overview of all nodes on a single screen.
Viewing migration status
To give some visibility while the ‘Config Data Migration’ task is running, PreFlightTool can be launched to show the last 20 migration events.
Note: PreFlightTool is located in ‘\Program Files\Venafi\Utilities.’
(added in 24.1.1) The log mode can be invoked at any time by launching PreFlightTool with the log option.
"\Program Files\Venafi\Utilities\PreFlightTool.exe" log
Migration Overview
Upon upgrading the first Venafi server, the upgrade wizard initiates the addition of the following tables to the database:
- cv2_objects
- cv2_contains
- cv2_policies
- config_parentdns
- config_n_stringattribute
- maintenance
Additionally, the following views are added:
- v_config_objects
- v_config_contains
- v_config_policies
- v_config_contains_string
When the Venafi Platform Service starts on the last upgraded Venafi server, the main data migrations begin.
The main migration tasks are:
- Add Post-Quantum OIDs
- Repair certificate secret normalized data if data is found missing redux
- SSH Migrate Vault ID columns to 64 bit
- SSH Certificates SecretStore Associations maintenance
- Rearrange Roots Tree
- Cleanup Obsolete Classes and Attributes
- Config Data Migration
- Config Post Data Migration
- Remove obsolete discovery statistics task
While these migration tasks are running, all Trust Protection Platform services remain fully available, except for the ‘Config Data Migration’ task. During the running of this task, system operations are automatically suspended. After the migration is complete, operations automatically resume.
Config Data Migration
This stage will suspend operations on all Venafi servers while data migration is taking place. Here are some important items to be aware of:
- Data from the following tables will be migrated to new table structures:
- config_objects
- config_contains
- config_policies
- The migration will temporarily require additional space in the database. Based on internal testing the migration will require approximately 40% more space used by the above tables.
- The speed of the migration will depend on the number of rows in the above tables. Based on Venafi internal testing, we expect around 40,000 rows to be migrated per second.
- The migration will not start unless the Venafi Platform Service is running on all Venafi servers and the Message Bus is healthy. For more information on the Message Bus, see Working with Message Bus.
Automated Migration Steps
- A message is sent on the Message Bus to tell all servers to suspend operations.
- The maintenance table is updated to indicate the suspended operations state.
- Config attributes are updated to the new syntax format and properties.
- Data is migrated to the new table structure.
- Indexes are created.
- Foreign key relationships are adjusted.
- Old tables are renamed with the old prefix. (These tables are dropped in the ‘Config Post Data Migration’ task.)
- New tables are renamed to match the old tables.
- Database statistics gathered on the config related tables.
- Operations are resumed on all TPP servers.
Comments