Migrating from SwaggerHub On-Premise 1.x to 2.x

SwaggerHub On-Premise 2.x uses a different installation method than 1.x versions. You may also need to contact your sales representative for an upgraded license. As a result, 1.x instances cannot be upgraded to 2.x directly and migration from 1.x to 2.x is a multi-stage process:

  1. Do a fresh install of 2.x

  2. Backup your 1.x data

  3. Import your data into the 2.x installation

  4. Configure new DNS name (if your 2.x instance uses a different DNS name than your 1.x instance)

These steps are described in detail below.

Considerations

  • The described procedure can migrate data from versions 1.20.1–1.29.x.

    Customers migrating from earlier versions must first upgrade to the latest 1.x release (but without the Ubuntu 20 migration).

  • We strongly recommend using the same DNS name for the SwaggerHub On-Premise 2.x instance as was used for the 1.x instance. Otherwise, you will need to take extra steps to reflect the new DNS name.

  • Before the migration, read about the differences between 1.x and 2.x.

What is migrated?

What is NOT migrated:

  • Admin Center settings: authentication method, SSL certificates, SSH users, and others. You will need to configure v. 2.x installation manually to match the settings used in 1.0.

    Note: Some configuration settings were removed in v. 2.x because those things can be configured at the cluster level or operating system level. See the list of removed settings.

  • Custom codegen templates (currently not supported in v. 2.x)

  • Terms and conditions (currently not supported in v. 2.x)

  • License (v. 2.x uses a new license format)

Requirements

  • Admin access to the 1.x instance.

  • If installing 2.x to a Kubernetes cluster: kubectl access to the cluster.

  • If installing 2.x on a VM: SSH access to the VM, with root or sudo privileges.

1. Install SwaggerHub On-Premise 2.x

If you have not already done so, install SwaggerHub On-Premise 2.x to your cluster or a standalone VM. Configure the settings in the 2.x Admin Console to match the settings used in 1.x.

Note: There is no need to run create-admin-user on the 2.x instance before the migration. The admin user will be migrated from the 1.x instance along with other user accounts.

2. Create a backup of 1.x data

  1. In SwaggerHub On-Premise 1.x, create a database backup.

  2. Download the created backup.

  3. Rename the backup file to backup.tar.gz for simplicity.

Important

After you create the backup, take the 1.x instance offline or restrict access to it so that no new data is created while the migration is in progress.

3. Import data into 2.x

  1. If SwaggerHub 2.x is deployed to a Kubernetes cluster:

    • Set the namespace for subsequent kubectl commands:

      $ kubectl config set-context --current --namespace=swaggerhub

    • Verify that the namespace was changed:

      $ kubectl config view | grep namespace:

      You should see:

          namespace: swaggerhub

    If SwaggerHub 2.x is installed on a VM:

    • Copy the backup file (backup.tar.gz) to an existing temporary directory on the VM:

      $ scp backup.tar.gz username@VM:/var/tmp

    • Connect to the VM over SSH as an administrative user. The commands below need to be run on the VM.

  2. Copy the backup file (backup.tar.gz) to a temporary directory in the swaggerhub-operator container:

    $ kubectl cp /path/to/backup.tar.gz $(kubectl get pods | grep swaggerhub-operator | awk '{print $1}'):/tmp/backup.tar.gz

  3. Run this command to import data into SwaggerHub 2.x from the 1.x backup:

    $ kubectl exec -it deploy/swaggerhub-operator -- cmd import-backup /tmp/backup.tar.gz

    Type yes to confirm and continue.

  4. Data import will take some time, especially if the data set is large.

    The output would look like this:

    WARNING: This will permanently erase existing data in your SwaggerHub installation.
Are you sure you want to continue? (yes/no) yes
Starting migration. This may take a few minutes...
Stopping SwaggerHub services
Restoring MongoDB
Creating collections...
Creating indexes...
Loading content...
Uploading core content
Uploading swaggerhub content
Loading configs...
Loading initial data...
Loading plugins configurations...
Restoring Postgres
Starting SwaggerHub services
Migrating docs branding images
Migration completed successfully

After the migration has completed:

  1. Re-deploy SwaggerHub from Admin Console, re-fresh the SwaggerHub UI (not Admin Console) in a browser and log in again.

  2. Log in to SwaggerHub using the admin credentials from 1.x and verify that all data (organizations, APIs, projects, and so on) is present and all functionality is working as expected.

4. Handle DNS name change (if needed)

Note

These steps are needed only if the 2.x instance uses a different DNS name than the 1.x instance.

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

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

    Note

    In VM (embedded cluster) installations, the namespace (-n argument) is default and can be omitted.

  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.

See Also

In this section:
© 2024
Publication date: