Managing Client Connections
If you configure clients with one or more failover clusters, you can use Management Center to force selected clients to disconnect from one cluster and connect to another without any downtime. For example, you may connect clients to another cluster to do the following:
-
Prepare for planned maintenance on the primary cluster.
-
Balance the load across multiple clusters.
-
Shift the clients’ connection back from a failover cluster to its primary cluster.
| Moving clients from one cluster to another is most useful when your clusters replicate data across each other. See WAN Replication. |
Filter Lists
Clusters allow or disallow client connections, using rules that are defined in a filter list. You can deploy filter lists to your connected clusters, using the UI or the REST API in Management Center.
When a cluster receives a filter list, it applies the rules to any new or existing client connections.
Management Center supports the following types of filter list:
-
Allow list: Clients that are allowed to connect to the cluster.
-
Deny list: Clients that are not allowed to connect to the cluster.
To adjust the modes see system-properties
Client Address Types
You can filter clients, using the following types:
| Address type | Description | Example |
|---|---|---|
Label (recommended) |
A string that matches the client label in the client’s configuration. This string can include
wildcard characters ( |
|
Instance Name |
A string that matches the client’s name in the client’s configuration. This string can include
wildcard characters ( |
|
IP Address |
IP address of a client (IPv4 or
IPv6) with optional range characters ( |
|
| It’s useful to assign roles to your clients by configuring them with labels. These labels are displayed in Management Center. You can filter clients that have certain labels. |
When a cluster member receives the deployed filter list, it immediately applies the list to all currently connected clients and then uses it for newly connecting clients. Clients on the deny-list connect to another cluster only if they are configured with a failover cluster. Otherwise, clients on the deny-list shut down.
| If some cluster members are not reachable from Management Center, those members keep using the last filter list that they received. |
Client filtering preview
Shows the result of applying filter lists on currently connected clients in real time. Can be hidden by a toggle control (visible by default).
Allowed clients - clients that remain connected.
Denied clients - clients that disconnect.
| Column name | Description |
|---|---|
Name |
Client name. |
UUID |
Client unique identifier. |
IP Address |
Client IP address without hostname. |
Labels |
List of client labels. |
| Column name | Description |
|---|---|
Address |
Client address. |
Host Name |
Canonical client hostname. |
Client Type |
Type of client. This field typically denotes the client’s programming language and indicates whether it is an Enterprise Java client. Although non-Java clients can also connect to Enterprise clusters, the Java client includes Enterprise features that non-Java clients do not. |
Client Version |
Version of the client codebase. |
Deploy confirmation
The deployment of filter lists must be confirmed by clicking the Confirm Deploy button. A summary of client connectivity is shown after the current filter lists have been applied. Preview can be enabled by clicking a toggle control.
| If the current filter lists disconnect all clients, the warning (All clients will be blocked if you apply current client filtering configuration) is displayed on the top of a modal. |
Synchronization of Filter Lists Across Multiple Instances of Management Center
If you have more than one instance of Management Center connected to the same cluster, the cluster synchronizes changes to its filter lists among all Management Center instances. When you create, update, or delete an active filter list, the cluster receives the filter list and sends it to the other connected instances of Management Center. Any existing filter lists on those instances of Management Center are overwritten.
When another Management Center instance deploys a new filter list, the following message is displayed in the app and the Client Filtering Settings and Filter Lists data is automatically refreshed:
Client filtering configuration was updated by another Management Center instance
Reconnecting Clients to the Primary Cluster
If your clients are configured to automatically failover to a secondary cluster, disconnecting a client from its primary cluster using a filter list will make the client to connect to the secondary cluster. When the filter list is deactivated, the client won’t automatically reconnect to the primary cluster because it now has an active connection to the secondary cluster.
To restore the client’s connection to the primary cluster, you must deploy a new filter list to the secondary cluster. This action will disconnect the client from the secondary cluster, allowing it to cycle through the defined clusters in its configuration and reconnect to the primary cluster.
Configuring Client Filtering Modes
By default, the available modes for Client Filtering are ALLOWLIST and DENYLIST. However, the default modes can be customized using the hazelcast.mc.clientFiltering.modes system property.
For instance, if you prefer not to enable the use the DENYLIST mode to block clients from accessing the cluster, you can override the default setting. This customization allows you to tailor client filtering options according to your specific requirements. See System Properties for more details.
Related Resources
See Blue-Green Deployment and Disaster Recovery in the Platform documentation.
