Migrating to Starburst Enterprise 433-e or higher#

Starburst Enterprise platform (SEP) 433-e uses Starburst Ranger which includes changes to RBAC policies that require migration. If you use Apache Ranger as a role-based access control system alongside SEP, follow this guide to migrate to 433-e and higher.

Overview#

The Starburst Ranger CLI tool now includes the migrate command, which is used to upgrade the Starburst service definition in Ranger and migrate existing policies automatically.

The following migration guide details the required actions for upgrading Ranger to ensure compatibility with SEP 433-e or higher. Contact Starburst Support with questions or feedback.

Before beginning the migration process using Starburst Ranger, it is highly recommended to do the following:

  • Create a backup of the Ranger database. Doing so allows you to recover any lost Ranger policies, if an unexpected error occurs while the migration command is running.

  • Update your SEP cluster to 433-e or higher and complete the Ranger migration. Starburst Ranger versions 2.3.0-e.11 and higher are not compatible with SEP versions lower than 433-e. Once the migration is complete, upgrade Starburst Ranger to 2.3.0-e.11 or higher.

Complete Ranger migration#

To migrate the Ranger database, follow these steps:

Step 1: Make sure the Starburst Ranger CLI is installed

SEP images do not include the Starburst Ranger CLI by default. If you have not installed it yet, install the Ranger CLI.

Step 2: Run the migrate command

Run the following command to connect to your Ranger database and perform the automated migration:

starburst-ranger-cli migrate --properties=ranger-access-control.properties [--p=<key>=<value>]

If the connection fails, ensure that the ranger-access-control.properties file exists and includes complete and accurate connection information.

Use the --p= option to set or override environment variables in your ranger-access-control.properties file.

Step 3: Ensure a successful migration

After the command executes, the end of the output should be a JSON value with information pertaining to the execution of the command, the success of the execution, and any errors:

{
  “executed”: 1,
  “success”: true,
  “errors”: []
}

Any entries in the error field indicate an unsuccessful execution. Refer to the following steps to troubleshoot:

  • Analyze the error to determine the appropriate steps to take to resolve the error.

  • In Starburst Ranger services, check the number of Ranger policies before and after the migration to determine if any policies were lost.

  • If any Ranger policies were lost, revert to the Ranger backup, and retry the migration.

  • If the error persists, contact Starburst Support.

Once the migration is complete, upgrade Ranger to 2.3.0-e.11 or higher.

Migration recovery#

The migrate command runs a number of API calls non-atomically. This means that in some cases where an API call fails due to timeout or some other reason, it can cause policy corruption. To recover from a migration failure:

  1. Restore your Ranger database using the backup.

  2. Resolve the issue that caused the migration to fail.

  3. Repeat the migration.