Configuring Custom Hostnames for an Event Broker Service

Each event broker service (or its connection endpoints) has a unique, randomly generated hostname, such as mr1egxydp8fguv.messaging.solace.com. You may want to configure custom hostnames, giving you a personalized name for the host in the messaging.solace.com domain. You can access the event broker service using the custom hostnames you've assigned, including its initial generated hostname. A custom hostname is useful for migration, improving client application integration (for example, using names that are simpler to remember or align with your hostname naming conventions), or application partitioning. For more information, see Use Cases for Using Custom Hostnames.

You can configure up to five additional hostnames to use as custom hostnames for an event broker service in addition to the generated one.

You can use different hostnames for different connection endpoints. This allows you to have different hostnames that client applications use depending on whether they connect via the public Internet or private IP addresses. Regardless of whether the endpoint is public or private, the hostname must be unique and exist within the messaging.solace.com domain. Connection endpoints are created as part of the port configuration process when you create or modify an event broker service. For more information about endpoints, see Configuring Client and Management Ports and Changing the Port Configuration for Event Broker Services.

When you create an event broker service, its initial, generated hostname (or connection endpoint) is assigned the Default status. If there is more than one connection endpoint, the public endpoint is assigned the Default status. After you assign a hostname as Default, the URL of that hostname:

  • becomes the primary URL that is used to access Broker Manager
  • is shown as the hostname in the Status or Connect tabs in Cluster Manager.

You can choose to assign a custom hostname you create as Default. The following shows the Default status indicator on the hostname:

You can also use a custom domain name rather than have your hosts use the messaging.solace.com domain. For example, you could have a custom domain, such as example.com. If you want to use a custom domain name, it has specific configuration requirements, requires a custom TLS certificate to be used as part of your deployment, and may affect connectivity of existing event broker services. For more information, see Configuring Custom Domain Names for Event Broker Services.

Use Cases for Using Custom Hostnames

The following are the most common uses cases for using custom hostnames:

Hostname Migration

You may need to migrate a hostname from one event broker service to another. For example, when an event broker service is deleted (or about to be deleted), its custom hostname can be used for another the event broker service so that previous client applications can connect using the same custom hostname. Any connections from the client applications need to be re-established with the new event broker service, but the configuration for the connection doesn't need to change. For example, you could have a name such as myfirstservice.messaging.solace.com that you use. If you needed to create another event broker service, you could simply move the hostname to the new event broker service without the need to change the configuration any of your client applications – provided you also copied over the client event broker service configuration (such as client usernames, authentication, certificates, and client profiles).

In addition, you can create different hostnames that are accessible using private IP addresses or public Internet. This permits you to have a different hostname based on the connectivity from the public Internet or from a private network (via private IP addresses).

Application Partitioning

If you need to spread the load of clients connected to an event broker service, you can use multiple hostnames to spread the load (horizontally-scaling) or evenly partition the load. For example, you could configure your applications to perform a round-robin of specific hostnames to distribute the load across a set of event broker services, where each hostname maps to a different event broker service.

You can configure another hostname to use as a custom hostname using the PubSub+ Cloud Console or use the REST API for PubSub+ Cloud. For more information, see the following sections.

Configuring Custom Hostnames in the PubSub+ Cloud Console

In the PubSub+ Cloud Console, you can configure custom hostnames for an existing event broker service provided the calling application or your user profile is assigned the proper permission or role, respectively. The hostname you add can be used as a custom hostname to access the event broker service.

You can specify a custom name provided you have the permissions and follow the guidelines found in Considerations for Using Custom Hostnames. Specifically, you can:

Considerations for Using Custom Hostnames

The following are considerations when you use custom hostnames:

Considerations for Custom Hostnames

The following are naming conventions for custom hostnames:

  • Hostnames must be alphanumeric characters (including dashes (-) as long as it’s not at the beginning or end of the name). The length of the hostname cannot be longer than 255 characters.
  • A hostname must be globally unique within the domain. A validation error occurs if a hostname is not unique.

  • Separate hostnames can be created for a private or public endpoints and are accessible via the configured hostname provided the correct ports are used.

Considerations When Moving of Hostnames between Event Broker Services

When you add, move, or delete the hostname, there's a period of time before the operation completes. The initial, generated hostname  for each connection endpoint or service can't be deleted show a Lock img.img-inline icon beside it. You also can't delete a hostname that has been assigned the Default status.

Permissions Required to Use Custom Hostnames

The following permissions are required to add, update, or delete custom(alternate) hostnames:

  • For calling applications that use the REST API, they must have one or both of the following:
    • the Update Services permission (under My Service) to configure hostnames for services the user owns
    • the Update Services (under Organization Services) to configure hostnames for event broker services owned in the account (or Workspace)
  • For users in the PubSub+ Cloud Console, they must be assigned the Mission Control Manager role.

Considerations for Using Custom Hostnames with Single-Sign On Enabled Event Broker Services

After adding a hostname, you may need to manually update your identity provider (IdP) with the your custom hostname to continue using single sign-on (SSO) for event broker management if you set it as Default. The need depends on how you have set up the rules on your IdP.

To re-enable SSO for management of your event broker service, follow these steps:

  1. Add the new URI of the hostname to your identity provider. You must have the Administrator role in the account for PubSub+ Cloud and you can copy it from the Manage Brokers dialog window. See Retrieving the URI for an Event Broker Service for more information.
  2. Update the SSO configuration on the event broker service which contains the URI for the custom hostname. For more information, see Updating the SSO configuration for an Event Broker Service.
  3. Test the SSO configuration and confirm that the URI for the custom hostname is used to access PubSub+ Broker Manager. For more information, see Testing SSO for an Event Broker Service.

Adding a Custom Hostname

You can add a custom hostname to access an existing event broker service. That hostname is not used to access PubSub+ Broker Manager unless it is assigned as Default. That name however can be used by client connections to access the event broker service.

To add a custom hostname to an existing event broker service, perform these steps:

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
  2. Select Cluster Manager from the navigation bar.
  3. On the Services page, click the event broker service for which you want to add a hostname. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.

  4. Select the Manage tab and then click Advanced Options.

  5. On the Hostnames tile, click Add.

  6. In the Add New Hostname dialog, in the Hostname field, enter in a name using these rules:

    • the name can contain only alphanumeric characters or dashes (-)

    • the length of the name cannot be more than 255 characters

    • the name must be unique in the domain

  7. In the Select the endpoint to assign the hostname to list, select the name of the endpoint to assign. The type of endpoint available is based what endpoints are configured for the event broker service.

    This step is available for event broker service deployed in Kubernetes clusters for Customer-Controlled Regions, Public Regions, and Dedicated Regions.

  8. Click Validate and Add Hostname. If the name is not validated, return step 5 and try another name.

The hostname you added appears beneath the default hostname assigned to your event broker service. If you want to assign the new hostname you created as Default, see Setting a Hostname as Default.

You can test the new hostname you've created using the Try Me! tab for your event broker service by entering the hostname in the Broker URL field found in the Advanced options. 

Setting a Hostname as Default

You can set the Default status to another generated hostname or a custom hostname. The hostname that is set as Default becomes the primary URL that is used to access Broker Manager and shown as the hostname to connect to the event broker service in the PubSub+ Cloud Console. You can only set one hostname with the Default status at one time.

If you are using a hostname with a custom domain name, you must set it as the Default or your custom fully-qualified domain name will not work.

To set a hostname as Default, perform these steps:

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
  2. In Cluster Manager, on the Services page, click the event broker service you want to assign a default hostname for.
  3. Select the Manage tab and then click Advanced Options.
  4. On the Hostnames tile, beside the hostname, click Actions and then select Set as Default.
  5. The Default indicator appears beside the selected hostname.

Moving a Custom Hostname

You can move a hostname from one event broker service to another event broker service. When you move a hostname, you can also choose whether to move it to the public or private endpoint if the endpoint exists on the target event broker service. When you move a custom hostname, only the hostname is migrated—not the settings. You are responsible for migrating any required event broker service settings when you move a hostname so that client applications can connect using the same hostname as expected.

These settings can include:

  • authentication settings (including any client certificates)
  • client profiles
  • ACL profiles
  • client usernames

To move a hostname from one event broker service to another, perform these steps:

  1. In Cluster Manager, on the Services page, click the event broker service that you want to move a hostname from.
  2. Select the Manage tab and then click Advanced Options.
  3. On the Hostnames tile beside the hostname that you want to move, click Actions , and then in the drop-down list, select Move.
  4. In the Move Hostname dialog, choose the event broker service that you want to move the hostname to from the Select the service your wish to move it to drop-down list.

  5. In the Select the endpoint to assign to hostname, select the name of the endpoint to assign. The type of endpoint available is based on what endpoints are configured for the event broker service.

    This step is available for event broker service deployed on Kubernetes for Customer-Controlled Regions, Dedicated Regions, and Public Regions.

  6. Click Move Hostname.

In the Hostnames tile, a Moving tag appears beside the hostname that is moving until the operation competes. The process may take a few minutes.

Deleting a Custom Hostname

You can remove a custom hostname from an event broker service. It's important to note that you can't remove the system-generated hostnames that's assigned to the event broker service, and you can't delete a hostname that is set as Default. To delete a custom hostname, you must remove Default status first. See Setting a Hostname as Default for more information.

Deleting a hostname impacts the connectivity of clients that use the deleted hostname. Don't delete an existing hostname if you don't want connectivity to be impacted.

To remove a hostname from an event broker service, perform these steps:

  1. In Cluster Manager, on the Services page, click the event broker service that you want to delete a hostname from.
  2. Select the Manage tab and then click Advanced Options.
  3. On the Hostnames tile beside the hostname you want to remove, click Actions and then select Delete.

  4. In the Delete Hostname confirmation dialog, click Delete Hostname to confirm that you want to delete the host name.

In the Hostnames tile, a Deleting tag appears beside the hostname that you are deleting until the operation completes. The process may take a few minutes.

Copying the FQDN for the Hostname

You can copy a hostname from an event broker service to your clipboard to paste elsewhere. The copied name is the fully-qualified domain name (FQDN), such as mr-1egxydp8fguv.messaging.solace.com.

To copy the  FQDN of the hostname to the clipboard, perform these steps:

  1. In Cluster Manager, on the Services page, click the event broker service that you want to copy the hostname from.
  2. Select the Manage tab and then click Advanced Options.
  3. On the Hostnames tile, beside the hostname that you want to copy, click Actions and then select Copy to Clipboard.

The FQDN is copied to your clipboard is available for you to paste.