Creating Event Broker Services in a Customer-Controlled Container

After you have requested a private region for your Customer-Controlled Containers, and deployed the Mission Control Agent to it, you can create event broker services managed by Solace Cloud in Customer-Controlled Containers in your private region. Creating an event broker service in a Customer-Controlled Container requires you to download and deploy an event broker bundle on your container host.

If you don't want to host and manage your own Customer-Controlled Containers, you can create an event broker service in a Kubernetes cluster.

This document explains the following:

Considerations for Deploying Event Broker Services to a Customer-Controlled Container

Be aware of the following considerations when deploying event broker services to Customer-Controlled Containers:

Certificate Requirements for Event Broker Services in Customer-Controlled Containers

Solace never receives or stores your private key. The certificate files remain on your container host and are used directly by the event broker service.

Event broker services deployed to Customer-Controlled Containers require a server certificate for both management and client TLS connections. You must prepare the server certificate and place it in the designated location before deploying the event broker service.

Solace Cloud supports two certificate configurations:

  • DNS name with CA-issued certificate (recommended): Use a DNS name that resolves to your event broker service address with a certificate issued by a public or private CA. This configuration provides the best client experience because clients can verify the certificate without additional configuration.

  • IP address with self-signed certificate: Use an IP address with a self-signed certificate. Clients connecting to the broker must be configured to trust the self-signed certificate or disable certificate verification.

Regardless of the configuration you choose, you must prepare the following files and place them in the certs/ directory of your event broker bundle:

  • certs/certificate.pem: A single PEM file containing your server certificate, any intermediate certificates, and the private key (in that order). For self-signed certificates, include the self-signed certificate and private key. The certificate and private key must be in PEM format (DER-encoded files are not supported). The private key must be an RSA key (ECDSA keys are not supported).

  • certs/passphrase: A text file containing the passphrase for an encrypted private key. If your private key is not encrypted, create an empty file.

For more information, see Managing TLS Certificates for Event Broker Services in Customer-Controlled Containers.

Connectivity Requirements for Event Broker Services in Customer-Controlled Containers

Your Customer-Controlled Container must have outbound connectivity to the following endpoints to allow the Mission Control Agent to manage your event broker services.

Connection Port Description

Insights Agent to Datadog

443

Required for monitoring metrics. TLS encrypted traffic between the Insights Agent and Datadog servers. For the list of Datadog endpoints and IP addresses, see Getting the IP Addresses for Monitoring Traffic.

Container host to Solace Container Registry

443

Required to download container images. TLS encrypted traffic to gcr.io (storage.googleapis.com). You require container registry credentials downloaded from the Cloud Console, unless you mirror images to a local registry.

These connectivity requirements are in addition to the Mission Control Agent connectivity requirements described in Connectivity Requirements for the Mission Control Agent in a Customer-Controlled Container.

Registering the Event Broker Service with Solace Cloud

Before deploying the event broker service to your Customer-Controlled Container, you must register it with Solace Cloud. Registering the event broker service creates the event broker configuration and generates the event broker bundle.

To register an event broker service using the Cloud Console, perform these steps:

  1. Log in to the Solace 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 Solace Cloud Console.

  2. On the navigation bar, select Cluster Manager .

  3. Select the environment where you want to create the event broker service. For more information, see Selecting Environments.

  4. On the Services page, click Create Service.

  5. In the Service Name field, enter a unique name for the event broker service.

  6. In the Cloud list, select Private Cloud.

  7. In the Region list, select the private region containing your Customer-Controlled Containers.

  8. Complete the remaining fields:

    • Broker Release: Select the event broker release to use.

    • Service Type: Select Standalone. The form defaults to HA Group, but only standalone class event broker services are supported in Customer-Controlled Containers.

  9. Click Create Service.

After the service is registered, the Cloud Console displays instructions for deploying the event broker and provides a link to download the event broker bundle.

Downloading the Event Broker Bundle

After registering the event broker service with Solace Cloud, you can download the event broker bundle. The event broker bundle contains everything you need to deploy the event broker service in a Customer-Controlled Container in your private region, including:

  • Docker Compose files

  • Environment and secrets files (event-broker.env, init-config.env, event-broker-console.js, and if monitoring is enabled datadog.env)

  • Certificate directory (certs/) for your server certificate

  • Monitoring configuration

The event broker bundle references specific, pinned image versions for the event broker service. Monitoring agent images use the latest tag that may receive updates. You must download container registry credentials from the Cloud Console to pull images from the Solace Container Registry. If you mirror images to a local registry, registry credentials are not required.

To download the event broker bundle, perform these steps:

  1. Log in to the Solace 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 Solace Cloud Console.

  2. On the navigation bar, select Cluster Manager .

  3. On the Services page, locate the event broker service you registered with Solace Cloud. The event broker service shows a pending status.

  4. Click on the event broker service to open the Service Details page.

  5. Click Download Event Broker Bundle.

  6. If you haven't already downloaded container registry credentials for your private region, navigate to User & Account > Account Details > Private Regions, click More Actions for your private region, and select Download Container Registry Credentials. Configure Docker to use the downloaded credentials.

  7. On your container host, extract the broker bundle using the following command:

    tar -xzf event-broker-<serviceId>.tar.gz && cd event-broker-<serviceId>

    Replace <serviceId> with the service ID shown in the downloaded file name.

Preparing TLS Server Certificates

After downloading the event broker bundle, and before deploying the event broker service to a Customer-Controlled Container, you must place your server certificate files in the certs/ directory within the extracted event broker bundle.

To prepare the certificate:

  1. On your container host, navigate to the directory where you extracted the event broker bundle.

  2. Locate the certs/ directory.

  3. Create a file named certificate.pem in the certs/ directory containing the following, in order:

    • Your server certificate

    • Any intermediate CA certificates

    • The private key

  4. Create a file named passphrase in the certs/ directory:

    • If your private key is encrypted, add the passphrase to this file.

    • If your private key is not encrypted, create an empty file.

Renewing TLS Server Certificates

When your TLS server certificate approaches expiration, you can renew it by replacing the certificate files and redeploying. For more information, see Managing TLS Certificates for Event Broker Services in Customer-Controlled Containers.

Creating an Event Broker Service in a Customer-Controlled Container

After downloading the event broker service artifact and preparing your TLS server certificate, you can create your event broker service in your Customer-Controlled Container.

Do not manually edit the bundle files. Any changes you make are overwritten when you download a new bundle during an upgrade.

To deploy the event broker service, perform these steps:

  1. Navigate to the directory where you extracted the event broker bundle.

  2. Run the following command to start the event broker service:

    docker compose up -d
  3. Verify that the containers are running:

    docker compose ps -a

    You should see the event broker service and monitoring agent in a running state. The bundle also runs cert-check and init-config containers that exit after completing their initialization tasks.

The event broker service is not accessible until you confirm the event broker service in the next step, Confirming the Event Broker Service Address.

The Insights Agent shares the broker's network namespace. If the event broker service container restarts on its own (for example, after a crash), run docker compose restart datadog to restore monitoring. After a host reboot, no action is needed because all containers restart together.

Confirming the Event Broker Service Address

After the event broker service is running in the Customer-Controlled Container, you must confirm the DNS name or IP address where the event broker service is reachable. Confirming the address allows the Mission Control Agent to connect to the event broker service, create the Message VPN, apply the initial event broker service configurations, and close plaintext SEMP access.

To confirm the event broker service address, perform these steps:

  1. Log in to the Solace 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 Solace Cloud Console.

  2. On the navigation bar, select Cluster Manager .

  3. On the Services page, select the event broker service you deployed to open the Service Details page. The page opens on the Deploy the event broker step.

  4. Enter the DNS name or IP address in the Event broker address (IPv4 or FQDN) field where the event broker service is reachable, and click Validate.

  5. After the Address validated message appears, click Next: Initializing the event broker.

The Mission Control Agent connects to the broker and completes the post-creation initialization. Initialization can take a few minutes. When complete, the event broker service status updates to reflect the progress.

You can't change the address of the event broker service after you confirm the address with Solace Cloud.

Verifying the Event Broker Service

After initialization completes, verify that your event broker service is operational. To verify the event broker service is functional, perform these steps:

  1. Log in to the Solace 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 Solace Cloud Console.

  2. On the navigation bar, select Cluster Manager .

  3. On the Services page, locate your event broker service. The Status column shows:

    • Running: The event broker service is operational and ready to accept client connections.

    • Pending: The initialization is still in progress or waiting for input.

  4. Click on the event broker service to view its details and connection information.

Once the event broker service shows a Running status, your event broker service is ready. You can now connect client applications using the connection details provided in the Cloud Console.

For information about configuring and managing your event broker service, see Using Broker Manager with Event Broker Services.

Deleting an Event Broker Service in a Customer-Controlled Container

Deleting an event broker service deployed to a Customer-Controlled Container is similar to deleting an event broker service deployed to Kubernetes, however there are extra steps required to remove the Customer-Controlled Containers. For more information, see Deleting Event Broker Services in a Customer-Controlled Container