Migrating VM-Based Event Broker Services Using the Clone API (Beta)

To migrate an event broker service, you can use the PubSub+ Cloud REST APIs to create a clone of the event broker service. After you create the cloned service and verify its configuration, you can use custom hostnames to migrate and cutover your service.

During migration, any messages in the queue on the VM-based event broker service are not preserved. If this is not acceptable for your migration, see Use Replication for Migration (Controlled Availability).

Considerations for Migrating Using the PubSub+ Cloud REST API

To migrate, you use a combination of PubSub+ Cloudv2 REST APIs and operations in the PubSub+ Cloud Console.

You don't need to create an application to call the REST API commands. You can use the v2 REST API reference pages to run the commands. For more information about how to use the reference, see Using the API Token inThis Reference in the PubSub+ Cloud API Reference.

  • You require a user account in PubSub+ Cloud with the Mission Control Manager or Administrator role, and access to PubSub+ Broker Manager. For more information, see Roles and Permissions.
  • Your account must also have enough available services to create new event broker services. The number of services that you can create in your account are based on your service limits. Solace has provided additional temporary licenses to enable migration of VM-based event broker services. If you require more services or have reached your service limits, see Increasing Your Capacity or Number of Event Broker Services.
  • Your client applications must connect to the VM-based event broker service using a custom hostname as an alternate hostname (not the initial, generated name hostname created for the event broker service). This is a requirement to perform the cutover. We recommend that you use one custom hostname, but you can choose to have multiple custom hostnames configured. If you have multiple custom hostnames, the migration time increases because the time required to move each custom hostnames takes several minutes. For more information about custom hostnames, see Adding a Hostname with Custom Domain Name.
  • When the event broker service that you clone has deletion protection is enabled (locked is true), the new event broker service also has deletion protection enabled. If service creation fails during the clone process, deletion protection is disabled ('locked' is false) and allows you to delete it.
  • If you use the REST API to clone your VM-based event broker service, the following broker and service configuration are not cloned:
    • Bridge configuration
    • Event mesh configuration (Dynamic Message Routing (DMR) configuration)
    • Distributed tracing configuration
    • Single sign-on (SSO) configuration (OAuth profiles)
    • Event Broker Service SSO (for management access)
    • Server certificates
    • Any client certificates other than those used for REST delivery points (RDPs)
    • No service connection endpoints are cloned. You can choose to specify the service connection to create when you clone the service. If you choose not to specify the parameters for the service connection endpoint, a private or public service connection endpoint is created based whether the service is created in a Public Region, Dedicated Region, or Customer-Controlled Region. For more information, see Configuring Client and Management Ports.

By default, certificate authorities are not cloned, but you can configure the API to clone the certificate authorities to the Target service.

Event Broker Service Migration Steps

These recommended migration steps:

  • minimize the time downtime for client applications connected to the event broker service
  • ensure that if there is an unexpected issue during migration, that you can migrate back to your VM-based event broker service

You can use these high-level steps when using the REST API to clone an event broker service to perform your migration:

The steps below refer to the VM-based event broker service that you migrate from as the Source service. The new Kubernetes-based event broker service where you migrate to is referred to as the Target service.

  1. Use the PubSub+ Cloud REST API to clone your VM-based event broker service (Source service). For more information, see Using the PubSub+ Cloud REST API to Clone a VM-Based Event Broker Service.
  2. Validate that the copy of event broker service (Target service) matches your VM-based event broker service (Source service). Here are few recommended things to check prior to migration:
    • Validate that client services can authenticate using the same configured authentication (client username and client profiles) and the configured ACLs
    • Validate that your Event Broker Service SSO configuration is available if you have it configured.
    • Validate the required client certificates have been installed on the event broker services (the default is not to copy the certificates to the Target service).
    • Validate that client applications can access the event broker service and can receive and publish messages.
    • Validate that the public or private endpoints are configured and that your ports are configured correctly.

  3. Move the custom hostnames from the Source service to the Target service to migrate (cutover). For more information, see Moving a Custom Hostname.

  4. Validate that the client applications operate as expected. We recommend that you lock the new Target service to avoid accidental deletion.

    • After you complete your validation (for example confirm that client applications can send and receive messages), proceed to the next step.
    • If the migration was not successful, move the custom hostname back to the Source service, re-check your configuration on the Target service, and run step 3 again. Contact Solace if required.

  5. After you have finished validating the functionality and stability of the Target service, delete the Source service.

Using the PubSub+ Cloud REST API to Clone a VM-Based Event Broker Service

Before cloning your event broker service, we recommend that you confirm that the Kubernetes-based region (datacenter) has the service classes that you require. Your account must also have enough available services to create new event broker services.

You should be comfortable using REST APIs in PubSub+ Cloud. For more information, see Using the PubSub+ Cloud REST API. The steps below show you how to use to run REST API commands without any development experience to perform the migration:

  1. Create an API token in the PubSub+ Cloud Console. For more information, see Creating API Tokens . On the API Token Management page, you must have at least these permissions enabled to complete this procedure:

    •  My Services
      • Get My Services with Viewer Credentials
      • Get My Services with Management Credentials
      • Create Services
    • Organization Services
      • Get Services with Viewer Credentials
      • Get Services with Management Credentials
    • Cloud Services
      • Get Datacenters

  2. Determine the unique identifier of the VM-based event broker service (Source service) you want to clone. You can get the unique identifier using one of the following methods:

    • In Cluster Manager, select the service and get the unique identifier for the event broker service from the last segment in the URL. For example, 9c5vurtex4b is the identifier from the URL https://console.solace.cloud/services/9c5vurtex4b.

    • Use the Get list of services REST endpoint to find the unique identifier (id) of the VM-based event broker service.

      We recommend that you run the Get list of services endpoint with the expand parameter set to serviceConnectionEndpoints to get the list of ports configured on the source service. You can use these values to configure the service connection endpoint when you clone your event broker service.

      For example, on the Get list of services page, paste the API token in the Bearer field from Step 1 and then click Try It! to run the command. If you wanted to find your VM-based service named My-First-Service, you can find that string in the name object and its corresponding id object is the unique identifier for the service, which is k0zvt9d6g6c as shown:

  3. Use the Get a list datacenters API to determine the unique identifier of the Kubernetes-based datacenter where you intend to migrate your VM-based service.

    Verify that datacenter that you choose supports the service class that you require. For example, if you require the Enterprise 5K service (this is the ENTERPRISE_5K_STANDALONE from serviceClassId), then confirm that the datacenter that you select has it listed in the supportedServiceClasses array.

    You can only clone services to Kubernetes-based datacenters (or regions). You can filter the list of Kubernetes-based datacenters that are available in your account using one of the following values in the provider fields:

    • k8s to filter for your Customer-Controlled Regions
    • gcp, eks, or aks to filter for public Kubernetes-based regions

      Don't use a VM-based datacenter such as azureor aws as filters. Use only one of the specified Kubernetes-based regions as filters. For more information, see the documentation for Get a list of datacenters.

    For example, you can use the Get a list of datacenters page to find datacenters using Amazon Elastic Kubernetes Service (EKS) using these steps:

    • Paste the API token in the Bearer field from Step 1.
    • Enter eks as a filter in the Provider field.
    • Click Try It! to run the endpoint.

    From the response, find the datacenter your want based on the name object (in this case EKS - US EAST (N. Virgina)). The unique identifier you require is the corresponding id object.

  4. Use the Create a clone of an existing event broker service API to create a Kubernetes-based event broker service (Target service). Specify as parameters the unique identifier of the event broker service to clone from Step 2 and the identifier of the datacenter from Step 3.

    Optionally, you can specify advanced parameters when you create a clone. You can use the following fields:

    • name—When a string is not specified, the default is to use the name of the Source service and append "- Clone" to it.
    • serviceConnectionEndpoints—Configuration for the service connection endpoint. You can get the list of ports from the Source service from the step 2 and use the same values to configure the ports. When this parameter is not specified, a default endpoint is created based on the ownership model of the region where the Target service is created.  For more information, see Port Configuration Considerations.
    • serviceCloneAttributes—The configuration to copy from the Source service, which can include service configuration, broker configuration, and certificate authorities. The default is to clone only the service configuration and the broker configuration from the Source service. For more information about the types of configuration you can clone, see REST API docs.

    For example, on the Create a clone of an existing event broker service page, paste the API token in the Bearer field from Step 1, click Try It! to run the command after you enter the following values in the following fields:

    • id—A  PATH PARAM where you enter the identifier of the service to clone from Step 2.
    • datacenterId—A BODY PARAM where you enter the identifier of the datacenter from Step 3.
    • name—A BODY PARAM where you enter the name for the cloned service. For example, if you My-Migrated-Service, that is the name.

After the POST command returns an response code of 202, the service creation process takes a few minutes. If an error is returned, take appropriate action and re-run the previous steps as required.

You cannot clone services to VM-based datacenters (or regions).

After service creation completes for the Target service, you can navigate to it using Cluster Manager in the PubSub+ Cloud Console. If required, manually configure the Target service to match your Source service, which includes:

  • Bridge configuration
  • Event mesh configuration (Dynamic Message Routing (DMR) configuration)
  • Distributed tracing configuration
  • Single sign-on (SSO) configuration (OAuth profiles)
  • Event Broker Service SSO (for management access)
  • Install server certificates or any other client certificates other than those used for REST delivery points (RDPs)
  • Configure the service endpoints if required

Deleting the VM-Based Event Broker Service

After you have validated that your client applications operate as expected after the migration, you can delete your VM-based (Source service) event broker service. 

After you delete the event broker service, it cannot be recovered.

  1. In Cluster Manager, on the Services page, select the VM-based event broker service that you want to delete and confirm the following:

    • Select the Status tab and validate that there are no active connections on your VM-based event broker service.

    • Select the Configuration tab and confirm the Deployment Type is VM-Based

  2. Click Manage and disable Deletion Protection if necessary. For more information, see Using Deletion Protection.

  3. Click Service and select the VM-based event broker service that you want to delete.

  4. Click Actions, and then select Delete Service. For more information, see Deleting Event Broker Services.

After a few minutes, your VM-based service is deleted and is no longer accessible.