Migration from an Existing Installation to Helm

Caution

Changes to the Bitnami catalog were announced recently and will take effect on August 28, 2025. Due to these changes, some SwaggerHub On-Prem users may need to take action. Find out if you are affected and learn about the remediation patch.

Prerequisites

Ensure the following configuration is in place before starting the Helm migration:

  • The latest SwaggerHub 2.x installation. If you're using an earlier version, upgrade your instance according to the instructions in Upgrading to the latest 2.x.

  • A Kubernetes cluster that meets the minimum requirements.

  • External PostgreSQL and MongoDB databases set up that satisfy the database requirements.

    Note

    We do not support internal databases for this Helm installation.

  • (Optional) To enable Enhanced Search, you need an existing Elasticsearch installation (version 8.x).

Upgrading to the latest 2.x

If you're using an earlier version of SwaggerHub, upgrade to the latest 2.x before proceeding. Follow one of the scenarios below depending on the currently installed version:

Note

Use your existing license to perform the upgrade to the latest KOTS version.

Migration process

  1. Prepare configuration values according to the instructions in Helm installation.

    As part of the procedure, create a customized custom-values.yaml file, ensuring its values reflect the existing KOTS settings. You can also obtain a ready values file corresponding with the current KOTS installation from the Admin Console. To do that, follow the path: View files - Helm - SwaggerHub and then download values.yaml.

    Set the database connection strings under .settings.dbs to the latest 2.x instance.

  2. Create a backup of your latest 2.x instance.

    Note

    Any changes applied to the instance between the backup creation and the graceful shutdown will be discarded.

  3. Shut down your SwaggerHub instance gracefully to prevent any database traffic.

  4. Initiate the Helm installation with the standard command:

    helm install swaggerhub oci://registry.replicated.com/swaggerhub/<CHANNEL>/swaggerhub [-n <NAMESPACE>] -f helm-values/swaggerhub/values.yaml

    Note

    You need an updated SwaggerHub license to perform this step. Before proceeding with Helm installation, contact our Sales Team or your account manager to request a new license.

  5. Restore your data using the backup from the latest 2.x instance.

Handle DNS name change (if needed)

Note

Follow these steps only if the Helm installation uses a different DNS name than the initial setup.

  1. Run the bulk-replace command to replace the old DNS name with the new one in all APIs and domains in the new instance:

    $ kubectl exec -it deploy/swaggerhub-operator -n swaggerhub -- cmd bulk-replace old.example.com new.example.com

    Note

    For VM (embedded cluster) installations, you can omit the namespace (-n argument) since the system automatically sets it to default.

  2. Update the SwaggerHub DNS name specified in external tools and CI/CD pipelines:

    • Requests to the Registry API and User Management API.

    • Requests to API mocks.

    • SwaggerHub CLI configuration.

    • Maven plugin configuration.

    • If you use SAML single sign-on, update the Entity ID, Application URL, and Assertion Consumer URL in the SwaggerHub connector in your SAML identity provider.

    • If you use GitHub authentication, update the Application callback URL in the SwaggerHub OAuth application configured in GitHub.

    • If you use Azure API Management integration, update the Redirect URI in the application registered in Azure.

  3. Recreate API mocks by triggering the API Auto Mocking integration in all APIs that use it. You can automate this procedure by using SwaggerHub CLI integration commands or the Registry API integration endpoints.

In this section:
© 2025
Publication date: