Using NodePort

You can expose the event broker services within a Kubernetes cluster to external traffic using NodePort. Since traffic needs to be routed to the cluster, you must front the cluster with a load balancer when using NodePort. Using NodePort opens one TCP port on all worker nodes for each event broker service exposed. Kubernetes transfers traffic going to this port to the pod behind that NodePort service.

With this option, you must:

  • configure the Mission Control Agent to deploy the Kubernetes cluster with the Kubernetes NodePort service
  • ensure each event broker service has its own NodePort service that can receive traffic from any of the worker nodes

  • manually provision a single load balancer in front of the Kubernetes cluster with a single address that receives traffic for the cluster.

    Typically, a network administrator provisions the load balancer within your private network. The load balancer forwards traffic to a default NodePort range of 30000-32767 (use the --service-node-port-range setting to use the API server to modify the range), which the Kubernetes cluster uses for its Target Pool. Configure the load balancer's Target Pool to contain a list of the worker nodes within the Kubernetes cluster to ensure that the load balancer routes traffic reliably. You must map the network load balancer to an IP address which clients outside of the Kubernetes cluster can reach.

  • set up the Mission Control Agent with a k8s.serviceHostname, and configure it with a hostname that resolves to the load balancer.

    The Mission Control Agent uses the k8s.serviceHostname as the hostname for the event broker services, and does not generate a hostname via a DNS Agent when the k8s.serviceHostname is set. The hostname is typically the CNAME that Solace creates in the message.solace.cloud domain that resolves to the load balancer.

Applying the preceding configuration means Kubernetes exposes external ports that are no longer the Solace Cloud defaults but are instead ports Kubernetes chooses randomly. To see the port assignments, select an event broker service in the Cloud Console and navigate to Manage > Management Settings > Network Access > Port Configuration.

The preceding configuration also requires an external network load balancer that forwards all TCP traffic using a single address over the NodePort range to the worker nodes. In this configuration, all event broker services share the same hostname.

Providing public access to your private network is optional, and requires an Internet gateway to route a public IP address to the appropriate private network IP address. If your network blocks external traffic from the Internet, you must allowlist the Solace Home Cloud IP address. If you use an HTTP/HTTPS proxy server, you must provide its details (URL, username, and password) during deployment of the Mission Control Agent.

Diagram showing NodePort configuration with an external load balancer, worker nodes, and event broker services.

If you must use a NodePort with an external network load balancer, the following are the advantages and disadvantages over using an integrated load balancer:

Advantages

  • All services are available over the same endpoint so you can use only one public IP address to expose multiple event broker services publicly.
  • The setup is easier to implement for on-premises environments because a tight load balancer integration with Kubernetes is not required.

Disadvantages

  • The TCP ports that the client connects to are arbitrarily chosen by Kubernetes over the NodePort range.

    You can't specify custom TCP ports for event broker services created from the Cloud Console, and trying to do so has no effect. Instead, the generated NodePort numbers are shown in the Connect tab for the event broker service in Cluster Manager within the Cloud Console.

  • You are responsible for manually configuring the load balancer, whereas typically they are created dynamically.
  • You can have only one event broker service per port.
  • When worker nodes are decommissioned or commissioned (including when the VM IP addresses change), you must update the load balancer manually to have the Target Group match the worker nodes that currently exist.
  • If you are upgrading from a cluster that you did not configure for public connectivity, you will be unable to create public endpoints.

For more information, see type: NodePort in the Kubernetes documentation.

Using an External Load Balancer with NodePort

When fronting a NodePort deployment with an external network load balancer, you can configure the load balancer to accept traffic on different frontend ports and forward the traffic to the corresponding NodePort ports on the Kubernetes worker nodes.

For example, you could configure the load balancer to accept traffic on default ports that Solace uses (for example, SMF: 55443, REST: 9443, MQTT: 8883, AMQP: 5671).

Configuring the load balancer in this way introduces a port mismatch that affects how Solace Cloud stores and presents connection information. The following sections describe the Solace Cloud-specific behaviors and requirements to be aware of when using this deployment pattern, including:

Port Mismatch and Connection Information

Solace Cloud internally records the NodePort values Kubernetes assigns to the connection endpoints for the event broker service. Solace Cloud uses these values to generate connection strings that the Cloud Console shows and the Event Management Agent returns.

When an external load balancer remaps these ports to standard well-known ports, the auto-generated connection information reflects the original NodePort values rather than the load balancer's frontend ports. Clients connecting through the load balancer must use the load balancer's frontend address and port, not the connection the Cloud Console shows.

Requirement to Use Fixed NodePort Values

To ensure consistency between the load balancer configuration and the stored connection details for the event broker service, assign fixed (static) NodePort values in your Kubernetes service definitions rather than relying on ports that Kubernetes randomly assigns from the default range (30000–32767).

Aligning the fixed NodePort values with your load balancer's frontend port mappings helps reduce confusion when referencing connection details in the Cloud Console. See your Kubernetes provider's documentation for instructions on assigning specific NodePort values in the service definitions.

Management Port (943) Consideration

Do not remap the management port (943) and its corresponding NodePort at the load balancer frontend.

The management port (943) must remain accessible using its original NodePort value to preserve management access to the event broker service. Remapping the management port at the load balancer causes incorrect URLs, resulting in broken links and failed authentication flows.

Event Management Agent Considerations

If you are using Event Portal, the Event Management Agent uses the stored NodePort connection details to communicate with on-premises event broker services. Management-plane connectivity between the Event Management Agent and the event broker service may be affected if the NodePort values that Solace Cloud stores do not match the reachable ports (due to load balancer remapping).

After updating NodePort values in your Kubernetes service definitions, you can refresh the stored connection information in the Cloud Console by disabling and then enabling any messaging protocol on the affected event broker service service within the Cloud Console. This forces the console to re-read the event broker service's current connection endpoints.

You can enable and disable ports for an event broker service in the Cloud Console from the Port Configuration tile, in the Network Access section of the Management tab of Cluster Manager for the selected event broker service.