Pulsar クライアント

Pulsar Spring Boot スターターを使用すると、PulsarClient が自動構成されます。

デフォルトでは、アプリケーションは pulsar://localhost:6650 にあるローカル Pulsar インスタンスへの接続を試行します。これは、spring.pulsar.client.service-url プロパティを別の値に設定することで調整できます。

値は有効な Pulsar プロトコル [Apache] (英語) URL である必要があります

spring.pulsar.client.* (英語) アプリケーションプロパティのいずれかを指定することで、クライアントをさらに構成できます。

スターターを使用しない場合は、PulsarClient を自分で設定して登録する必要があります。これを支援するために使用できるビルダーカスタマイザーを受け入れる DefaultPulsarClientFactory があります。

1. TLS 暗号化 (SSL)

デフォルトでは、Pulsar クライアントは Pulsar サービスとプレーンテキストで通信します。次のセクションでは、TLS 暗号化 (SSL) を使用するように Pulsar クライアントを構成する方法について説明します。前提条件として、ブローカーも TLS 暗号化を使用するように構成されている必要があります。

Spring Boot 自動構成は現在、TLS/SSL 構成プロパティをサポートしていません。代わりに、Pulsar クライアントビルダーで必要なプロパティを設定する PulsarClientBuilderCustomizer を提供できます。Pulsar は、Privacy Enhanced Mail (PEM) と Java KeyStore (JKS) の両方の証明書形式をサポートします。

TLS を構成するには、次の手順に従います。

  1. pulsar+ssl:// スキームと TLS ポート (通常は 6651) を使用するように Pulsar クライアントサービス URL を調整します。

  2. https:// スキームと TLS Web ポート (通常は 8443) を使用するように管理クライアントサービス URL を調整します。

  3. ビルダーに関連するプロパティを設定するクライアントビルダーカスタマイザーを提供します。

上記の詳細については、Pulsar TLS 暗号化 [Apache] (英語) の公式ドキュメントを参照してください。

2. 認証

認証を必要とする Pulsar クラスターに接続するには、使用する認証プラグインと、指定したプラグインに必要なパラメーターを指定する必要があります。Spring Boot 自動構成を使用する場合、(ほとんどの場合) 構成プロパティを介してプラグインとプラグインパラメーターを設定できます。

spring.pulsar.client.authentication.param.* で定義された名前が、認証プラグイン (通常はキャメルケース) で予期される名前と正確に一致することを確認する必要があります。Spring Boot は、これらのエントリに対していかなる種類の緩和バインディングも試行しません。

例: AuthenticationOAuth2 認証プラグインの発行者 URL を構成する場合は、spring.pulsar.client.authentication.param.issuerUrl を使用する必要があります。issuerurl や issuer-url などの他の形式を使用する場合、設定はプラグインに適用されません。

認証パラメーターに環境変数を使用すると、変換中に大文字と小文字の区別が失われるため、通常は問題が発生します。例: 環境変数を介して設定された次の issuerUrl 認証パラメーターを考えてみましょう。

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

Spring Boot がこのプロパティをロードするとき、予想される issuerUrl (キャメルケース) ではなく issuerurl (小文字) が使用されます。この制限は、env var の値を application.yml 内の関連する auth プロパティの値として使用することで回避できます。上記の例を続けると、次のようになります。

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

Spring Boot 自動構成を使用しない場合は、org.apache.pulsar.client.api.AuthenticationFactory を使用して認証を作成し、それをクライアントファクトリに提供するクライアントカスタマイザー内の Pulsar クライアントビルダーに直接設定できます。

次のリストは、サポートされている各認証メカニズムを構成する方法を示しています。

Athenz はこちら 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationAthenz
        param:
          tenantDomain: ...
          tenantService: ...
          providerDomain: ...
          privateKey: ...
          keyId: ...
これには TLS 暗号化も必要です。
トークンはこちら 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken
        param:
          token: some-token-goes-here
基本はこちら 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationBasic
        param:
          userId: ...
          password: ...
OAuth2 はこちら 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2
        param:
          issuerUrl: ...
          privateKey: ...
          audience: ...
          scope: ...
Sasl はこちら 
spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationSasl
        param:
          saslJaasClientSectionName: ...
          serverType: ...
mTLS (PEM) はこちら
このオプションには TLS 暗号化が必要であり、すでにクライアントビルダーカスタマイザーを提供する必要があるため、提供された TLS カスタマイザーでクライアントビルダーに認証を直接追加することをお勧めします。org.apache.pulsar.client.api.AuthenticationFactory を使用すると、次のように認証オブジェクトの作成に役立ちます。
Authentication auth = AuthenticationFactory.TLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem");

mTLS (PEM) [Apache] (英語) に関する Pulsar の公式ドキュメントを参照してください。

mTLS (JKS) はこちら
このオプションには TLS 暗号化が必要であり、すでにクライアントビルダーカスタマイザーを提供する必要があるため、提供された TLS カスタマイザーでクライアントビルダーに認証を直接追加することをお勧めします。org.apache.pulsar.client.api.AuthenticationFactory を使用すると、次のように認証オブジェクトの作成に役立ちます。
Authentication auth = AuthenticationFactory.create(
        "org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls",
        Map.of("keyStoreType", "JKS", "keyStorePath", "/path/to/my/keystore.jks", "keyStorePassword", "clientpw"));

mTLS (JKS) [Apache] (英語) に関する Pulsar の公式ドキュメントを参照してください。

各サポートプラグインとその必要なプロパティの詳細については、Pulsar セキュリティ [Apache] (英語) の公式ドキュメントを参照してください。

3. 自動クラスタレベルフェイルオーバー

Pulsar Spring Boot スターターは、自動クラスターレベルのフェイルオーバー [Apache] (英語) 用に PulsarClient も自動構成します。

spring.pulsar.client.failover.* (英語) アプリケーションのプロパティを使用して、クラスターレベルのフェイルオーバーを構成できます。

次の例では、プライマリクラスターと 2 つのバックアップクラスターを使用してクライアントを構成します。

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"
この機能を使用するには、クライアント構成に加えて、ブローカーで満たす必要のあるいくつかの前提条件 [Apache] (英語) があります。

Spring Boot 自動構成を使用しない場合は、クラスターレベルのフェイルオーバー用にクライアントを構成するクライアントカスタマイザーを提供できます。