Pulsar Client

When you use the Pulsar Spring Boot Starter, you get the PulsarClient auto-configured.spring-doc.cn

By default, the application tries to connect to a local Pulsar instance at pulsar://localhost:6650. This can be adjusted by setting the spring.pulsar.client.service-url property to a different value.spring-doc.cn

The value must be a valid Pulsar Protocol URL

You can further configure the client by specifying any of the spring.pulsar.client.* application properties.spring-doc.cn

If you are not using the starter, you will need to configure and register the PulsarClient yourself. There is a DefaultPulsarClientFactory that accepts a builder customizer that can be used to help with this.

1. TLS Encryption (SSL)

By default, Pulsar clients communicate with Pulsar services in plain text. The following section describes how to configure Pulsar clients to use TLS encryption (SSL). A pre-requisite is that the Broker has also been configured to use TLS encryption.spring-doc.cn

The Spring Boot auto-configuration does not currently support any TLS/SSL configuration properties. You can instead provide a PulsarClientBuilderCustomizer that sets the necessary properties on the Pulsar client builder. Pulsar supports both Privacy Enhanced Mail (PEM) and Java KeyStore (JKS) certificate formats.spring-doc.cn

Follow these steps to configure TLS:spring-doc.cn

  1. Adjust the Pulsar client service url to use the pulsar+ssl:// scheme and TLS port (typically 6651).spring-doc.cn

  2. Adjust the admin client service url to use the https:// scheme and TLS web port (typically 8443).spring-doc.cn

  3. Provide client builder customizer(s) that sets the relevant properties on the builder.spring-doc.cn

You can find more information on the above in the official Pulsar TLS Encryption documentation.spring-doc.cn

2. Authentication

To connect to a Pulsar cluster that requires authentication, you need to specify which authentication plugin to use and any parameters required by the specified plugin. When using Spring Boot auto-configuration, you can set the plugin and the plugin parameters via configuration properties (in most cases).spring-doc.cn

You need to ensure that names defined under spring.pulsar.client.authentication.param.* exactly match those expected by your auth plugin (which is typically camel cased). Spring Boot will not attempt any kind of relaxed binding for these entries.spring-doc.cn

For example, if you want to configure the issuer url for the AuthenticationOAuth2 auth plugin you must use spring.pulsar.client.authentication.param.issuerUrl. If you use other forms, such as issuerurl or issuer-url, the setting will not be applied to the plugin.spring-doc.cn

Using environment variables for auth parameters is typically problematic because the case sensitivity is lost during translation. For example, consider the following issuerUrl auth parameter set via an environment variable:spring-doc.cn

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

When Spring Boot loads this property it will use issuerurl (lower-cased) rather than the expected issuerUrl (camel-cased). You can get around this limitation by using the value of the env var as the value of the related auth property in your application.yml. Continuing the example above:spring-doc.cn

spring:
  pulsar:
    client:
      authentication:
        param:
          issuerUrl: ${SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL}

When not using Spring Boot auto-configuration, you can use the org.apache.pulsar.client.api.AuthenticationFactory to create the authentication and then set it directly on the Pulsar client builder in a client customizer that you provide to the client factory.spring-doc.cn

The following listings show how to configure each of the supported authentication mechanisms.spring-doc.cn

Click here for Athenz 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationAthenz
        param:
          tenantDomain: ...
          tenantService: ...
          providerDomain: ...
          privateKey: ...
          keyId: ...
This also requires TLS encryption.
Click here for Token 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken
        param:
          token: some-token-goes-here
Click here for Basic 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationBasic
        param:
          userId: ...
          password: ...
Click here for OAuth2 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2
        param:
          issuerUrl: ...
          privateKey: ...
          audience: ...
          scope: ...
Click here for Sasl 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationSasl
        param:
          saslJaasClientSectionName: ...
          serverType: ...
Click here for mTLS (PEM)
Because this option requires TLS encryption, which already requires you to provide a client builder customizer, it is recommended to simply add the authentication directly on the client builder in your provided TLS customizer. You can use the org.apache.pulsar.client.api.AuthenticationFactory to help create the authentication object as follows: 
Authentication auth = AuthenticationFactory.TLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem");

See the official Pulsar documentation on mTLS (PEM).spring-doc.cn

Click here for mTLS (JKS)
Because this option requires TLS encryption, which already requires you to provide a client builder customizer, it is recommended to simply add the authentication directly on the client builder in your provided TLS customizer. You can use the org.apache.pulsar.client.api.AuthenticationFactory to help create the authentication object as follows: 
Authentication auth = AuthenticationFactory.create(
        "org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls",
        Map.of("keyStoreType", "JKS", "keyStorePath", "/path/to/my/keystore.jks", "keyStorePassword", "clientpw"));

See the official Pulsar documentation on mTLS (JKS).spring-doc.cn

You can find more information on each of the support plugins and their required properties in the official Pulsar security documentation.spring-doc.cn

3. Automatic Cluster-Level Failover

The Pulsar Spring Boot Starter also auto-configures the PulsarClient for automatic cluster-level failover.spring-doc.cn

You can use the spring.pulsar.client.failover.* application properties to configure cluster-level failover.spring-doc.cn

The following example configures the client with a primary and two backup clusters.spring-doc.cn

application.yml
spring:
  pulsar:
    client:
      service-url: "pulsar://my.primary.server:6650"
      failover:
        delay: 30s
        switch-back-delay: 15s
        check-interval: 1s
        backup-clusters:
          - service-url: "pulsar://my.second.server:6650"
            authentication:
              plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken
              param:
                token: "my-token"
          - service-url: "pulsar://my.third.server:6650"
In addition to the client configuration, there a few prerequisites on the broker that must be satisfied in order to use this feature.

When not using Spring Boot auto-configuration, you can provide a client customizer that configures the client for cluster-level failover.spring-doc.cn