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.

Important:  Universal Orchestrator version 26.2.1 introduced support for orchestrator pooling. As a result, in-place upgrades from version 25.x or earlier to version 26.2.1 or later are not supported. A clean reinstall is required.

Quick Decision Guide

Situation Recommended Path

Upgrading from Universal Orchestrator 26.2 or later to a newer version, using the same install directory

 In place upgrade

Upgrading to Universal Orchestrator 25.4.1 or earlier

 In place upgrade

Upgrading from Universal Orchestrator 25.x or earlier to 26.2 or later

 Clean reinstall (required)

Changing the install path or service account on Universal Orchestrator 26.2 or later

 Clean reinstall
Changing the authentication method (any version) Clean reinstall (required)

Running Universal Orchestrator in a container

 Update the image tag and extension version in your container configuration
Migrating from the legacy Windows Orchestrator Side-by-side migration (preferred), then remove the legacy orchestrator. Alternatively, uninstall the legacy orchestrator and then install Universal Orchestrator.
Important:  If you uninstall and reinstall an orchestrator (for example, during an upgrade), Keyfactor recommends using the same orchestrator name for the new installation. Keyfactor Command uses the name to recognize the orchestrator as the same one when it starts again, which allows it to continue servicing the certificate stores associated with that orchestrator without reconfiguration. If you use a different name, Keyfactor Command treats it as a new orchestrator, and you must reconfigure the certificate stores.

Using the same name isn’t enough if you also switch authentication methods. In that case, Keyfactor Command treats the orchestrator as a different orchestrator even though the name is unchanged, and you must reconfigure the certificate stores.

These requirements don’t apply if the orchestrator you are reinstalling is already on version 26.2 or later (for example, when you upgrade from 26.2 to a later version). Starting in release 26.2, certificate store jobs are handled by an orchestrator pool rather than by a single named orchestrator, so the orchestrator name no longer affects store assignments.

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.

    In Windows Services (services.msc), locate the Keyfactor Orchestrator Service and check the Log On As column. Record the service account and whether it is 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. Not all upgrade methods 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 the secrets you will need to re-enter. Which ones apply depends on your configuration:

    Important:  Secrets cannot be retrieved from the existing installation. Make sure you have them before you continue. If you don’t, ask the account owner or your identity provider administrator, or retrieve them from the system your organization uses to manage secrets, such as a PAMClosed PAM (Privileged Access Management): Controls privileged access by vaulting credentials, enforcing least-privilege/just-in-time access, rotating secrets, and auditing sessions. Across Keyfactor products, PAM protects diverse sensitive operations and secrets—for example certificate stores and CA credentials—via built-in or third-party providers; external integrations are delivered as custom PAM extensions (several published on Keyfactor’s public GitHub). solution. Store them according to your organization’s security policy.

  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. Not all upgrade methods 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

Select the appropriation upgrade path for your situation (see Quick Decision Guide).

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)

A clean reinstall of the Universal Orchestrator removes the existing installation, so what you need to reconfigure afterward depends on what you change. If you reinstall with the same orchestrator name and the same authentication method, Keyfactor Command recognizes the orchestrator and keeps its certificate store associations, schedules, and store credentials. If you change the orchestrator name or the authentication method, Keyfactor Command treats the new installation as a different orchestrator, and you must reconfigure these items. In every case, you must re-enter the orchestrator’s own secrets.

Use the steps below to record what you’ll need, even if you expect Keyfactor Command to retain it.

  1. Prepare by gathering information about the installed Universal Orchestrator and its configured certificate stores:

    1. Record the service account.

    2. Check the authentication method.

    3. Record Keyfactor Command connect identity.

    4. Collect secrets.

    5. Inventory plugins and extensions.

    6. Perform a certificate store search for the orchestrator. The easiest way to do this is to visit the Orchestrator Management page, select the orchestrator, and choose View Certificate Stores. If you are using version 26.2.1 or later, this will show you the certificate stores in the orchestrator pool to which the orchestrator is assigned. If you are using an earlier version, this will show you the certificate stores associated with the specific orchestrator.

      Review and record the settings and schedule information for each certificate store. If you change the authentication method, some of this information is cleared.

      If you have a large number of certificate stores, you can use a GET /CertificateStores APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request with one of these queries to return the data:

      • Prior to 26.2: AgentId -eq '[GUID of your orchestrator]'
      • 26.2 or Later: OrchestratorPoolId -eq '[GUID of your orchestrator pool]'
      Important:  If you change the authentication method, Keyfactor Command clears the credentials it uses to connect to each certificate store. Before you reinstall, make sure you have these credentials so you can enter them again. If you don’t, get them from the store’s administrator or from the system your organization uses to manage secrets, such as a PAM solution. Store them according to your organization’s security policy.

  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). Include the following parameters in the installation command to keep the new installation separate from the existing one and to preserve the orchestrator’s identity in Keyfactor Command:

    • Different installation location: -Destination (Windows) or --destination (Linux)

    • Different service name suffix: -ServiceSuffix (Windows) or --service-suffix (Linux)

    • Same orchestrator name: -OrchestratorName (Windows) or --orchestrator-name (Linux).

      This preserves your certificate store associations unless you also change the authentication method. If the orchestrator you’re reinstalling is already on version 26.2 or later, the name doesn’t affect store assignments. For details, see Quick Decision Guide.

  3. Stop the older Universal Orchestrator service (see Start the Universal Orchestrator Service).
  4. In the Keyfactor Command Management Portal, approve the new orchestrator, if needed. If you configured auto-registration this will not be needed.
  5. In the Management Portal, link the certificate store records to the appropriate orchestrator pool and update the certificate store records with the appropriate credential and schedule information.
  6. Validate that the certificate store inventory and management tasks are occurring as expected.

  7. Once all the certificate stores that use the old orchestrator have been updated to use the new orchestrator, uninstall the old version using the uninstall script:

    • Windows: uninstall.ps1
    • Linux: uninstall.sh
Note:  Keyfactor recommends trying a migration first on a small number of orchestrators with validation before migrating a large batch.

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 Approve or Disapprove 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.