Upgrading or Migrating the Keyfactor Universal Orchestrator

Use this guide to choose between an in-place upgrade, a clean reinstall, or a migration from the legacy Windows OrchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores.. Start with the quick decision guide, then follow the steps for your path.

Quick Decision Guide
Situation Recommended Path
Upgrading the Universal Orchestrator to Universal Orchestrator in the same install directory In-place
Universal Orchestrator to Universal Orchestrator but changing path/service account/auth method, or you want a fresh start Clean reinstall
Containerized Universal Orchestrator Update image tag and extension version in your container config
Migrating from the legacy Windows Orchestrator Side-by-side then remove legacy (preferred), or uninstall legacy then install Universal
Before you Begin

Gather the following information before you begin the upgrade or migration:

  1. Identify the orchestrator type.

    • Universal Orchestrator default path (Windows):

      C:\Program Files\Keyfactor\Keyfactor Orchestrator

      Has multiple subfolders, including extensions.

      Service name (Windows Services / services.msc):

      • Keyfactor Orchestrator Service (Default) (or your custom name in parentheses).

    • Legacy Windows Orchestrator default path:

      C:\Program Files\Keyfactor\Keyfactor Windows Orchestrator\

      Has a single subfolder, by default: plugins.

      Service name (Windows Services / services.msc):

      • Keyfactor Orchestrator Service (no parentheses)

  2. Record the service account (open Windows Services / services.msc and look at Log On As). Note if it’s a gMSA.

  3. Record the Keyfactor Command authentication method and fields.

    • Universal Orchestrator:

      Check the following configuration file (default path):

      • Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\appsettings.json

      • Linux: /opt/keyfactor/orchestrator/configuration/appsettings.json

      Look for these settings:

      • Client certificate authentication: CertPath, AuthCertThumbprint

      • Token authentication: BearerTokenUrl, ClientId

      • Basic authentication: None of the above set

    • Legacy Windows Orchestrator:

      • Check the following configuration file (default path):

        • C:\Program Files\Keyfactor\Keyfactor Windows Orchestrator\KeyfactorWindowsAgent.exe.config

      Look for these settings:

      • Client certificate authentication: CmsCertPath, CmsAuthCertThumbprint (in CmsAgent)

      • Basic authentication: CmsUsername, CmsEncryptedPassword

    Important:  Make a backup of this configuration file before upgrading. Some of the upgrade methods will not retain customizations.
  4. Record the identity used in Keyfactor Command (Orchestrator Management page).

  5. Collect secrets you may need to re-enter (passwords, client secrets, etc.).

    These cannot be retrieved from the existing install—they’re stored encrypted.

  6. Inventory your plugins/extensions and their locations. The default locations for these are:

    • Universal Orchestrator (Windows): C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions

    • Universal Orchestrator (Linux): /opt/keyfactor/orchestrator/extensions

    • Legacy Windows Orchestrator: C:\Program Files\Keyfactor\Keyfactor Windows Orchestrator\plugins

    Important:  Make a backup of any extensions or plugins you're using before upgrading. Some of the upgrade methods will not retain customizations.

  7. Check extension compatibility & certificate store types.

    • Legacy Windows Orchestrator plugins are not compatible with Universal Orchestrator extensions. Look for Universal Orchestrator equivalents from the Keyfactor Git Hub:

      https://keyfactor.github.io/integrations-catalog/content/orchestrator

    • Newer Universal Orchestrator versions may require newer extension versions. Check Keyfactor Git Hub for compatibility.

    • New extensions may have different configuration requirements for the certificate store type definitions in Keyfactor Command. Review the documentation of each extension you will be using to determine if there are any changes needed.

      Only these fields of a certificate store type in use may be edited: Name, Short Name, Supported Job Types, Entry Parameters.

      If other fields must change, create a new certificate store type (using a different Short Name), then map your extension to it via the manifest.json.

      Important:  Create or update the certificate store type definition in Keyfactor Command before upgrading.
      Copy
      Example manifest.json capability mapping (renaming F5-*-REST to F5-*-REST2)
      {
        "extensions": {
          "Keyfactor.Orchestrators.Extensions.IOrchestratorJobExtension": {
            "CertStores.F5-CA-REST2.Inventory": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.Bundle.Inventory"
            },
            "CertStores.F5-CA-REST2.Management": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.Bundle.Management"
            },
            "CertStores.F5-CA-REST2.Discovery": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.Bundle.Discovery"
            },
            "CertStores.F5-SL-REST2.Inventory": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.SSLProfile.Inventory"
            },
            "CertStores.F5-SL-REST2.Management": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.SSLProfile.Management"
            },
            "CertStores.F5-SL-REST2.Discovery": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.SSLProfile.Discovery"
            },
            "CertStores.F5-WS-REST2.Inventory": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.WebServer.Inventory"
            },
            "CertStores.F5-WS-REST2.Management": {
              "assemblypath": "F5Orchestrator.dll",
              "TypeFullName": "Keyfactor.Extensions.Orchestrator.F5Orchestrator.WebServer.Management"
            }
          }
        }
      }
Perform the Upgrade

Universal Orchestrator to Universal Orchestrator (In-Place Upgrade)

  • Windows: Run the upgrade.ps1 script from the new version. To do this:

    1. Place the new orchestrator version in a temporary working directory.

    2. Open a Windows PowerShell window using the “Run as administrator” option.
    3. Change directories to the InstallationScripts directory within the directory holding the installation files under your temporary working directory.
    4. Execute the upgrade.ps1 script.
    5. If you have more than one Universal Orchestrator installed, you will be prompted to select which orchestrator to upgrade. If not, you will be prompted to continue the upgrade.

    The upgrade will stop the service, copy configuration files (appsettings.json and the extensions directory) to a temporary location, perform an install of the new version, and copy the saved configuration files back from the temporary directory.

    Since this process backs up and restores the extensions folder automatically, you only need to copy extensions (see post-upgrade steps) if you’re also changing their versions. Backing up before upgrading is still recommended.

  • Linux: Install the newer orchestrator over the existing orchestrator using the --force option to overwrite the current implementation.

Universal Orchestrator to Universal Orchestrator (Clean Reinstall)

  1. Uninstall the current version using the uninstall script:

    • Windows: uninstall.ps1
    • Linux: uninstall.sh

  2. Install the newer version using the standard installation steps (see Install the Universal Orchestrator on Windows or Install the Universal Orchestrator on a Linux Server).

Legacy Windows Orchestrator to Universal Orchestrator (Migration)

Containerized Universal Orchestrator

Update the image tag and reference the appropriate extension version, if applicable, in your container configuration. If you mount extensions, ensure the mount points remain correct.

Post-Upgrade Steps

  1. Extensions: If not handled by upgrade.ps1 or you’re changing versions, copy extensions into the new extensions folder and restart the orchestrator service.

  2. Approve: Review the capabilities that the orchestrator has registered in Keyfactor Command and re-approve it. See Approving or Disapproving Orchestrators.

  3. Create Certificate Stores: If you created a new certificate store type, recreate the affected certificate stores with the new type, then remove the old ones (a store’s type cannot be edited).

  4. Validate: Confirm certificate stores and/or SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. scanning is running as expected.