Upgrade using the Python 3 runtime and dual-compatible Python syntax in custom scripts

Follow this upgrade path to transition to use the Python 3 runtime. To decide if you need to make any changes, see Plan your Splunk Enterprise upgrade path for the Python 3 migration.

Splunk Enterprise versions 7.x and lower don't support Python 3. If you choose to write your private apps to only be compatible with Python 3, then you might experience breaking changes if you install your app before upgrading to Splunk Enterprise version 8.0 or later, or if the previous version of the app has Python 2 syntax in Splunk Web-dependent scripts and templates.

This upgrade path has three parts:

1. Pre-upgrade steps
2. Upgrade Splunkbase apps and validate
3. Upgrade Splunk Enterprise

Pre-upgrade steps

Before you migrate to Python 3 during your upgrade to Splunk Enterprise version 8.1, take the following steps. Using a test environment is optional. If you don't use a test environment, this process might impact performance. See Performance considerations in the Splunk Platform Upgrade Readiness App manual for more information.

Prepare for upgrade with the Splunk Platform Readiness app

1. Optional: In a test environment, install all your production apps and replicate any custom scripts you included in your production environment outside of an app context.
2. Install the Splunk Platform Upgrade Readiness App and run it, preferably on your test instance. See About the Splunk Platform Upgrade Readiness App in the Splunk Platform Upgrade Readiness App manual for more information.
3. Review the test results for your private apps and follow the instructions in the Upgrade Readiness App to resolve any issues. Rewrite Python scripts to be compatible with both Python 2 and Python 3. See Writing scripts compatible with Python 2 and Python 3 in the Python 3 Migration manual for more information.
4. Review the test results for the apps you downloaded from Splunkbase and check for file paths that contain content you have customized or extended. Follow the instructions in the Upgrade Readiness App to resolve the issues.

Manually prepare for upgrade

If you choose not to use the Upgrade Readiness App, manually check your Splunk Enterprise deployment for issues. Confirm you've met these upgrade readiness requirements in your private apps and extensions before you continue:

1. Optional: In a test environment, install all your production apps and replicate any custom scripts you included in your production environment outside of an app context.
2. Remove all Advanced XML.
3. If you are running SplunkWeb Legacy Mode, disable it by editing %SPLUNK_HOME%\etc\system\local\web.conf to remove the appServerPorts and httpport attributes.
4. Rename any files named test.py to a non-reserved name.
5. Adjust custom Mako templates to be Python 2 and Python 3 compatible.
6. Adjust custom CherryPy endpoints in apps to be Python 2 and Python 3 compatible.
7. Rewrite all remaining Python code to be dual-compatible with Python 2 and 3 either by using the Python SDK or by leveraging the Six or Future libraries. Keep a list of the files you rewrite so that you can test them when you upgrade.
   For more information about these upgrade requirements, see Python 3 migration with the Splunk platform in the Python 3 Migration manual.

Upgrade Splunkbase apps and validate

Only after you have completed all the preparation steps, upgrade to Splunk Enterprise 8.1 in a test environment, following the three-phase Splunk Enterprise upgrade process. For more information, see Splunk Enterprise upgrade process.

To reduce performance impact, upgrade to Splunk Enterprise 8.1 in a test environment first to test for breaking changes. Don't upgrade in your production environment directly.

Follow these steps to validate the upgrade in your test environment:

1. Upgrade your installed Splunkbase apps to versions that are dual-compatible with Splunk Enterprise 7.x and 8.x, since these should be compatible for both Python 2 and Python 3. Test for any breaking changes. If the developer hasn't provided a version of the app that is compatible with Splunk Enterprise version 8.1, update it yourself or remove the app. If the developer has provided separate versions of the app for Splunk Enterprise 7.x and 8.x, follow any upgrade instructions provided by the developer. If none are provided, assume the app is written for Python 3 only, and choose one of the following options:
   • Upgrade the app to the Splunk Enterprise 8.x compatible version only after upgrading your instance to Splunk Enterprise 8.1, and note any potential breaking changes in Splunk Web.
   • If there are many Splunkbase apps that are Python 3-only and might cause unplanned downtime, take your deployment offline for maintenance during the Splunk Enterprise upgrade. At this time, remove the apps, take your deployment offline, upgrade the apps to the versions compatible with Splunk Enterprise 8.x, and then take your deployment back online.
2. Test your Splunk Web-dependent Python scripts by accessing all views that rely on custom CherryPy endpoints or Mako templates. Ensure that they function as expected.
3. Test the functionality of your dual-compatible Python scripts. If you prefer, you can run each dual-compatible script with Python 3 instead. Consult the list of files you rewrote, and, one at a time, go to the configuration file responsible for invoking each script and add python.version=python3 to the stanza that invokes the script. Test for errors using the following table:

   Script type	File	Restart required?	How to test
   Custom search commands	commands.conf	Yes	Run the command and check that it works as expected.
   Modular inputs	inputs.conf	Yes	Enable the input and check that data arrives as expected.
   Scripted inputs	inputs.conf	Yes	Enable the input and check that data arrives as expected.
   Custom alert actions	alert_actions.conf	No	Run the custom alert action and verify that it works as expected.
   Scripted lookups	transforms.conf	Yes	Verify the lookup is working as expected.
   Custom REST endpoints	restmap.conf	No	Access the endpoint and check that it responds as expected.
   Scripted authentication	authentication.conf	No. Go to Settings > Access controls > Authentication method and click Reload authentication configuration.

4. If you use scripted authentication, check that the Python interpreter path specified in your scriptPath setting is the canonical path, $SPLUNK_HOME/bin/python. If you enter a custom path to another interpreter, scripted authentication will use the interpreter you specify rather than the interpreter you choose in the python.version setting.
5. If you encountered any errors, adjust the Python files and test them again.
6. Once you're satisfied that all your scripts are working as expected, specify the global Python 3 runtime in your test environment.
   1. Go to $SPLUNK_HOME/etc/system/local/server.conf and set python.version=python3.
   2. Restart Splunk Enterprise.
   3. Test any Python scripts that are on a critical path, such as scripted authentication, to ensure they continue to work.

Upgrade Splunk Enterprise

Upgrade your production environment to version 8.1 on your search heads, indexers, and forwarders, following the three-phase Splunk Enterprise upgrade process. For more information, see Splunk Enterprise upgrade process. As you upgrade the components of your deployment, follow this order of operations:

1. Upgrade to Splunk Enterprise 8.1.
2. Note any potential breaking changes, such as apps that aren't compatible yet with Splunk Enterprise version 8.1 at time of upgrade.
3. Install any apps that are only compatible with Python 3 and Splunk Enterprise 8.x.
4. Over time, set your scripts to run Python 3 only. Go to the appropriate script .conf file and set python.version=python3, as covered when validating apps.
5. (Optional) Specify the global Python 3 runtime in your production environment. Go to $SPLUNK_HOME/etc/system/local/server.conf and set python.version=python3.
6. Start Splunk Enterprise.