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. Verify system requirements.

    Before upgrading or migrating, review the System Requirements for the target Universal Orchestrator version.

    • Newer Universal Orchestrator versions may require a newer .NET runtime.

    • Operating system, runtime, or dependency requirements may differ from your currently installed version.

    • Container images may be built on newer base images with updated runtime requirements.

    Confirm that the target host (or container environment) meets the requirements before proceeding with any upgrade or migration steps.

  2. 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\

      By default has a single subfolder:

      plugins.

      Service name (Windows Services / services.msc):

      Keyfactor Orchestrator Service (no parentheses)

  3. Record the service account.

    Open Windows Services / services.msc and look at Log On As. Note if it’s a gMSA.

  4. Check the authentication method.

    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 the appsettings.json configuration file before upgrading. Some of the upgrade methods will not retain customizations.

  5. Record Keyfactor Command connect identity.

    Record the identity under which the orchestrator is registered in Keyfactor Command. View this on the Orchestrator Management page of the Keyfactor Command Management Portal.

  6. Collect secrets.

    Collect any secrets you may need to re-enter, such as passwords or client secrets.

    These values cannot be retrieved from the existing installation because they are stored in encrypted form.

  7. Inventory plugins and extensions.

    Inventory your plugins and extensions along with 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.

  8. Check extension and certificate store type compatibility.

    Verify that the extensions you are currently using are compatible with the target Universal Orchestrator version. If upgrading extensions, review whether existing certificate store types in Keyfactor Command must be updated or recreated to match the newer extension version.

    • Legacy Windows Orchestrator plugins are not compatible with Universal Orchestrator extensions. Identify equivalent Universal Orchestrator extensions in the Keyfactor GitHub integrations catalog:

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

    • Newer Universal Orchestrator versions may require newer extension versions. Verify that the extension versions you plan to use are compatible with the target orchestrator version.

    • Newer extension versions may introduce changes to certificate store type configuration requirements in Keyfactor Command. Review the documentation for each extension to determine whether existing certificate store types must be updated or recreated.

      Only the following fields of an existing certificate store type in use can 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 the extension to the new type in the extension’s manifest.json.

      Important:  Create or update certificate store type definitions in Keyfactor Command before upgrading the Universal Orchestrator.
    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.