Registering an EMS Server in a Control Tower Data Plane

    Procedure
  1. On the TIBCO Control Plane home page, in the left navigation pane, click Data Planes.

  2. On the data planes page, navigate to the desired data plane card and click Go to Data Plane.

  3. Perform one of the following steps:

    • For an unconfigured data plane, click Configure and then click Messaging in the left navigation pane.

    • For a configured data plane, click the Messaging card.

  4. Click Add Messaging Instances.

  5. Based on your registration preference, click Registering an EMS Server or Bulk Registering EMS Servers.

Registering an EMS Server

This is also known as form-based registration, where you can register a single server at a time.

    Procedure
  1. Fill the required details on the Register TIBCO Enterprise Message Service™ wizard.

    Field Name Description
    Server Group Name Normally, for reliability purposes, EMS servers are deployed as multiple processes on multiple host machines, so that if one is down, another can take over. This collection is referred to as a "server group" and is generally identified in the EMS configuration with the property "server name". In the context of a Platform data plane server group registration, these names are used to identify a specific server group and must be unique. They are not required to match the EMS configuration "server name" property, although assuming they pass the uniqueness test, that would be recommended to simplify things like route administration.
    Description Information to help EMS Dashboard users identify this specific server group.
    Client URLs

    A comma-separated list of host-port URLs like those used for an EMS client "FT URL" property (for example, tcp://abc.xyz:1234,tcp://abc.xyz:1235).

    Note: In the case of an FTL-store based EMS server group, all three listen host-ports should be included so that administration and monitoring can report on the health of all three instances.
    Monitor URLs Monitoring and metrics functionality of the EMS Dashboard requires that your EMS server configuration be updated to support monitor listen ports if they are not already present. This allows the Control Plane to monitor health and collect metrics for display in the dashboard. Like the Client URLs, it should include a host-port specification for members of the group, including the standby-only member if using FTL stores (for example, http://host1.xyz:1234,http://host2.xyz:1235,http://host3.xyz:1234).
    Registration User

    Administrator username to be used during the registration process. This user/password information is not stored and is just used during the EMS registration configuration updates. During Dashboard configuration updates, a new data plane gems administrative user and password is generated if the associated Kubernetes secret does not exist. The EMS server is then updated to add a new msg-gems-admin administrative group, and the data plane administrative username is added to that group for dashboard access.

    Note: Changing permissions on the msg-gems-admin group or removing the data plane admin user significantly impairs dashboard functionality.
    Registration Password Password for the registration user.
    Client mTLS Configuration Generally, this option is not required. However, if your EMS server configuration has the property ssl_require_client_cert set to "true", then you must supply client certificates to the msg-gateway pod for it to connect to the server. The certificates must be present before the registration information can be successfully validated. When supplying client certificates, the message gateway shares an emscerts folder with the Hawk domain configuration, and directions for copying the certificate files can be found in the TLS section of the Managing Domains instructions.
    Monitor mTLS Configuration Generally, this option is not required. If your EMS server has separately specified monitoring SSL parameter settings and in that section set the monitor ssl_require_client_cert property to "true", you also need to copy the monitoring client certificates to the emscerts folder prior to validating your EMS server registration information.

  2. Add mutual TLS security information if required. The meanings of the fields are the same for both client and monitoring listens. For more information about TLS, see TIBCO Enterprise Message Service documentation.

    Note: It is common for the monitoring listen to not require mTLS even if the client URL does.
    Field Name Description
    Client/Monitor Certificate The client certificate supplied by your EMS administrator. This information should be the same as your EMS client applications use when connecting to this EMS server group.
    Private Key The associated client private key supplied by your EMS administrator.
    Private Key Password The password if your client private key is encrypted.
    Trusted Certificate The comma-separated list of trusted certificates if your server is using self-signed certificates.
  3. Click Validate Server to complete the validation process. Check that the URLs are reachable and that the registration user and password are valid.

  4. Click Register Server. Adds a new data plane administrative user and msg-gems-admin administrative group to the server configuration.

    Note: It is not recommended to register more than 50 servers. If you try to register more than 50 servers, registration might take a bit of time to complete, during which time existing data plane servers might show as unavailable.
  5. Click Done to complete the registration.

    After registration, you can see each server group has one of the following health indicators:

    • A green check () means that all service instances are available and performing normally.

    • A yellow warning () means that all messaging services are fully available, but some server instances or functionality is degraded.

    • A red cross () means that messaging services are not available.

Advanced considerations

You can override the generated data plane administrator user and password via a Kubernetes secret in the data plane. The secret is called tp-msg-gateway-tibadmin and contains two data fields: EMS_ADMIN_USER and EMS_ADMIN_PASSWORD.

Caution: When changing the secret values, make sure to create the new user and add it to the msg-gems-admin group prior to the secret update, or the Control Plane Dashboard loses server access.

Bulk Registering EMS Servers

This is also known as YAML-based registration, where you can register multiple servers at a time.

  1. Click Upload YAML to upload a pre-prepared YAML file or edit the YAML directly in the text box using the displayed sample as a guide.

    Note: It is recommended to limit the total registrations to 50, otherwise, registration changes might get slow.

  2. The entries for a given server group in the list parallel exactly the form-based flow, where the mapping of the keys to form fields is as follows:

    Field Name Description
    groupName Server Group Name
    description Description
    clientUrl Client URLs
    monitorUrl Monitor URLs
    registrationUser Registration Users
    registrationPass Registration Password
    clientMtls certificate Client Certificate
    privateKey Private Key
    pkPassword Private Key Password
    trusted Trusted Certificate
    monitorMtls certificate Monitor Certificate
    privateKey Private Key
    pkPassword Private Key Password
    trusted Trusted Certificate
  3. Note: Certificate information requires that the actual certificate files have been copied to the data plane Control Tower machine prior to registration. These are only required if the EMS server configuration has the specific ssl_require_client_cert property set to true. If it is not set to true, the message gateway does not require client certificate files to be uploaded, and "mTls" checkbox must not be selected.
  4. After uploading, assuming the YAML syntax is valid, click Validate to perform validation for an individual server or click Validate All to perform a bulk validation for all the servers.

  5. After successful validation, click Register <N> validated servers.

  6. After all the in-progress registrations are complete, click Done to complete the registration.

    After registration, you can see each server group has one of the following health indicators:

    • A green check () means that all service instances are available and performing normally.

    • A yellow warning () means that all messaging services are fully available, but some server instances or functionality is degraded.

    • A red cross () means that messaging services are not available.

Unregistering a Server

To delete the Control Plane server registration, use the three-dots menu and click Delete.

Note: Deleting the server just stops the message gateway from monitoring and administering the EMS server group. The active server configuration is not changed, so this action has no impact on the running EMS server group.