Quarkus - Zookeeper Client

Stateful client to Apache ZooKeeper (https://zookeeper.apache.org/).

ZooKeeper is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services.

Installation

If you want to use this extension, you need to add the io.quarkiverse.quarkus-zookeeper:quarkus-zookeeper extension first. In your pom.xml file, add:

<dependency>
    <groupId>io.quarkiverse.quarkus-zookeeper</groupId>
    <artifactId>quarkus-zookeeper</artifactId>
</dependency>

Usage

This extension produces an application scoped bean for the ZooKeeper client, which can be directly injected into a managed bean:

@ApplicationScoped
public class ZookeeperService implements AsyncObserverExceptionHandler {

    private static final Logger LOG = Logger.getLogger(ZookeeperService.class);

    @Inject ZooKeeper client;

    public void onZKEvent(@ObservesAsync WatchedEvent event) {
        LOG.infof("Receiving [%s]", event.getState());
    }
}

As shown by the example, it also provides a binding between ZooKeeper watched events and an asynch CDI bus.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

Whether to enable health checks.

Environment variable: QUARKUS_ZOOKEEPER_HEALTH_ENABLED

boolean

true

Set the value to true to enable SASL authentication.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_SASL_ENABLED

boolean

false

Specifies the context key in the JAAS login file.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_CLIENTCONFIG

string

Client

SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd";

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_SASL_CONFIG_STRING

string

Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_SERVER_PRINCIPAL

string

Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_CLIENT_USERNAME

string

zookeeper

Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_CLIENT_CANONICALIZE_HOSTNAME

boolean

true

Realm part of the server principal. By default it is the client principal realm.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_AUTH_SERVER_REALM

string

Specifies the file path to a JKS containing the local credentials to be used for SSL connections.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SSL_KEY_STORE_LOCATION

string

Specifies the password to unlock the file.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SSL_KEY_STORE_PASSWORD

string

Specifies the file path to a JKS containing the remote credentials to be used for SSL connections.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SSL_TRUST_STORE_LOCATION

string

Specifies the password to unlock the file.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SSL_TRUST_STORE_PASSWORD

string

Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SSL_KEY_STORE_TYPE

string

Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SSL_TRUST_STORE_TYPE

string

Connection timeout in millis.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_CONNECTION_TIMEOUT_MILLIS

int

30000

Request timeout in millis.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_REQUEST_TIMEOUT_MILLIS

int

5000

This switch controls whether automatic watch resetting is enabled. Clients automatically reset watches during session reconnect by default, this option allows the client to turn off this behavior by setting zookeeper.disableAutoWatchReset to true.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_DISABLE_AUTOWATCH_RESET

boolean

false

If you want to connect to the server secure client port, you need to set this property to true on the client. This will connect to server using SSL with specified credentials. Note that it requires the Netty client.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_SECURE

boolean

false

Specifies which ClientCnxnSocket to be used. Possible values are org.apache.zookeeper.ClientCnxnSocketNIO and org.apache.zookeeper.ClientCnxnSocketNetty . Default is org.apache.zookeeper.ClientCnxnSocketNIO . If you want to connect to server’s secure client port, you need to set this property to org.apache.zookeeper.ClientCnxnSocketNetty on client.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_CLIENT_CNXN_SOCKET

string

org.apache.zookeeper.ClientCnxnSocketNIO

In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send data on the order of kilobytes. If incoming data length is more than this value, an IOException is raised. This value of client side should keep same with the server side(Setting System.setProperty("jute.maxbuffer", "xxxx") in the client side will work), otherwise problems will arise.

Environment variable: QUARKUS_ZOOKEEPER_CLIENT_JUTE_MAX_BUFFER

int

1048575

Comma separated host:port pairs, each corresponding to a zk server.

Environment variable: QUARKUS_ZOOKEEPER_SESSION_CONNECTION_STRING

string

required

Session timeout in milliseconds.

Environment variable: QUARKUS_ZOOKEEPER_SESSION_TIMEOUT

int

30000

Whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can’t find any majority servers but there’s partitioned server it could reach, it connects to one in read-only mode.

Environment variable: QUARKUS_ZOOKEEPER_SESSION_CAN_BE_READ_ONLY

boolean

false