English

SINETStream ユーザガイド

設定ファイル

1. 概要
 1.1 設定ファイルの配置場所
 1.2 設定値の優先順位
2. 共通のパラメータ
 2.1 基本的なパラメータ
 2.2 API のパラメータ
 2.3 SSL/TLS に関するパラメータ
 2.4 暗号化に関するパラメータ
3. メッセージングシステム固有のパラメータ
4. 注意事項
 4.1 Python APIとJava APIの違い
 4.2 未対応

1. 概要

SINETStream API では、 メッセージングシステムに接続するためのパラメータなどを設定ファイルに記述することにより、 API に指定するパラメータを簡略化できる。 設定ファイルには、サービス名とそれに結び付いたパラメータを記述する。 API でサービス名を指定することで、設定ファイルに記述されているパラメータが読み込まれる。

コンフィグサーバが稼働している環境では、 SINETStream APIでコンフィグ名を指定することにより あらかじめ管理者が設定した設定ファイルをコンフィグサーバから取得できる。

設定ファイルにパスワードやデータ暗号鍵などの秘匿情報を記述するときに 公開鍵暗号をつかって暗号化することもできる。

コンフィグサーバの利用

コンフィグサーバを利用するには二通りの方法がある。

  1. コンフィグサーバのWeb UIから設定ファイルをダウンロードする。
  2. コンフィグサーバのWeb UIからアクセス情報をダウンロードして、SINETStream APIから設定ファイルを取得する。

1つ目の方法は、 ユーザがエディタを起動して設定ファイルを記述する代わりに 管理者が用意した設定ファイルをダウンロードするだけの違いである。

2つ目の方法は、 事前にコンフィグサーバ認証情報をダウンロードしておき、 SINETStream実行時にコンフィグサーバから設定ファイルをダウンロードする方法である。

ダウンロードしたコンフィグサーバ認証情報は $HOME/.config/sinetstream/auth.json (Windows 10 では C:\Users\{userXX}\.config\sinetstream\auth.json) に置く。

秘匿情報の公開鍵暗号による暗号化

公開鍵で暗号化された秘匿情報を復号するときに秘密鍵が必要になる。

制限: 公開鍵暗号方式はRSAのみ対応

秘密鍵をPEM形式(PKCS#1)で ~/.config/sinetstream/private_key.pem に置いておくと、 設定ファイル中の暗号化された秘匿情報を復号するときに参照される。

注意: 秘密鍵ファイルのファイルパーミッションは、他人が読み書きできないよう設定すること。

秘匿情報は

{パラメータ}: !sinetstream/encrypted {公開鍵で暗号化された設定値}

の形式で記述する。暗号化方式はSINETStream独自のフォーマットである。

復号化して得られた平文は

{パラメータ}: {復号化された設定値}

として扱われる。

バイナリデータと添付ファイル

パラメータの値としてASCIIではなくバイナリデータを指定したい場合は、 YAMLのバイナリ型の書式にしたがい !!binary のあとにつづけてパラメータの値をBase64エンコードした文字列を指定する。 パラメータとしてファイルをそのまま指定する場合も同じように !!binary のあとにつづけてコンテンツをBase64エンコードした文字列を指定する。

{パラメータ}: !!binary {Base64でエンコードされたコンテンツ}

補足:

設定ファイルのフォーマット

設定ファイルのフォーマットは YAML である。 設定ファイルは設定ファイル自体のパラメータを記述ヘッダー部分(header:)とサービスを記述するコンフィグ部分(config:)からなる。

header:
  ヘッダ記述ブロック
config:
  サービス記述ブロック1
  サービス記述ブロック2
  ...

ヘッダ部分が存在しない場合は従来フォーマット(コンフィグ部のみ)だとみなす。

ヘッダを記述するブロックは以下のようになっている。

  {ヘッダパラメータ1}: {設定値1}
  {ヘッダパラメータ2}: {設定値2}
  ...

設定ファイルのヘッダ部

ヘッダパラメータには以下のものがある。

設定ファイルのコンフィグ部

コンフィグ部分はサービス記述ブロック(各ブロックはYAMLの連想配列の1エントリとして記述される)からなる。

サービスを記述するブロックは以下のようになっている。

{サービス名}:
  type: {メッセージングシステムのタイプ}
  brokers:
    - {ホスト名1}:{ポート番号1}
    - {ホスト名2}:{ポート番号2}
  {その他のパラメータ1}: {設定値1}
  {その他のパラメータ2}: {設定値2}

type にはメッセージングシステムのタイプを指定する。 brokers にはメッセージングシステムのブローカーのアドレスを指定する。

その他のパラメータとして指定できる値はメッセージングシステムによって異なる。 例えば以下のような値が指定できる。

1.1 設定ファイルの配置場所

設定ファイルは以下の順序で検索され、最初に見つかったファイルのみが読み込まれる。

  1. カレントディレクトリの .sinetstream_config.yml
  2. $HOME/.config/sinetstream/config.yml
    • Windows 10 では C:\Users\{userXX}\.config\sinetstream\config.yml

設定ファイルのカスケードは不可。 例えば .sinetstream_config.yml に パラメータ1:値1 が、 $HOME/.config/sinetstream/config.yml に パラメータ2:値2 が書かれているとき、パラメータ2:値2 は読み込まれない。

1.2 設定値の優先順位

設定ファイルに記述されたパラメータと API に指定されたパラメータが競合する場合や、 共通のパラメータとメッセージングシステム固有のパラメータが競合する場合は、 以下の優先順位で最初に見つかった値が使用される。

  1. API に指定されたメッセージングシステム固有のパラメータ値
  2. API に指定された共通のパラメータ値
  3. 設定ファイルに記述されたメッセージングシステム固有のパラメータ値
  4. 設定ファイルに記述された共通のパラメータ値

2. 共通のパラメータ

メッセージングシステムの種類によらず共通で指定できるパラメータを以下に示す。

2.1 基本的なパラメータ

2.2 API のパラメータ

SINETStream API を呼び出すときに指定するパラメータのデフォルト値を設定する。 API にパラメータを指定しなかった場合は、設定ファイルに記述した値がデフォルト値として使用される。

value_serializer/value_deserializer は value_type よりも優先される。

value_deserializer と value_type を指定し、value_serializer を指定しなかった場合、 MessageReader では value_deserializer が有効になり、MessageWriter では value_type が有効になる。

Python API の制限: SINETStream v1.* では、value_serializer/value_deserializer の指定はAPIのパラメータでのみ指定可能で設定ファイルには記述できない。

設定例

メッセージの圧縮/展開を有効にする例を以下に示す。

service-comp-1:
  type: mqtt
  brokers: mqtt.example.org
  data_compression: true

圧縮アルゴリズムにzstdを使って圧縮レベルを10にする例を以下に示す。

service-comp-2:
  type: mqtt
  brokers: mqtt.example.org
  data_compression: true
  compression:
    algorithm: zstd
    level: 10

2.3 SSL/TLS に関するパラメータ

SSL/TLS に関するパラメータはメッセージングシステムによって名称が異なるが、 SINETStream ではそれらを共通の tls パラメータによって統一的に記述できる。 ここで指定したパラメータは、SINETStream 内部でメッセージングシステム固有のパラメータにマッピングされる。

tls の子要素となるマッピングに指定できる値を以下に示す。

※ trustStore, trustStoreType, trustStorePassword, keyStore, keyStoreType, keyStorePassword, keyfilePassword は Java APIのみで指定できるパラメータである。Python API では指定できない。

設定例

tls パラメータに真偽値を指定する例を以下に示す。 この場合、設定値はメッセージングシステム固有のデフォルト値が使用される。

service-tls-1:
  type: mqtt
  brokers: mqtt.example.org
  tls: true

tls パラメータにマッピングを指定する例を以下に示す。

service-tls-2:
  type: kafka
  brokers:
    - kafka-1:9092
  tls:
    ca_certs: /etc/sinetstream/ca.pem
    certfile: certs/client.pem
    keyfile: certs/client.key

優先順位

SINETStream の tls パラメータを使用せず、メッセージングシステム固有のパラメータを直接指定することもできる。

一つのサービスに対して tls パラメータとメッセージングシステム固有のパラメータを両方指定した場合は、以下の優先順位で最初に見つかった値が使用される。

  1. API に指定されたメッセージングシステム固有のパラメータ
  2. API に指定された tls パラメータ
  3. 設定ファイルに記述されたメッセージングシステム固有のパラメータ
  4. 設定ファイルに記述された tls パラメータ

2.4 暗号化に関するパラメータ

SINETStream では、バックエンドの SSL/TLS による通信の暗号化とは別に、 メッセージ内容を暗号化することができる。 これにより、ブローカーに蓄積されたメッセージを第三者に見られても情報を保護することができる。

crypto の子要素となるマッピングに指定できる値を以下に示す。

設定例

crypto を設定する例を以下に示す。

service-aes-1:
  type: kafka
  brokers:
    - kafka0.example.org:9092
  crypto:
    algorithm: AES
    key_length: 256
    mode: EAX
    key_derivation:
      algorithm: pbkdf2
      iteration: 10000
    password: secret-000

3. メッセージングシステム固有のパラメータ

バックエンドのメッセージングシステム固有のパラメータを透過的に指定することができる。

4. 注意事項

4.1 Python API と Java API の違い

以下のパラメータは Python API でのみ有効である。Java API で指定しても無視される。

以下のパラメータは Java API でのみ有効である。Python API で指定しても無視される。

4.2 未対応

SINETStream v1.* は、以下のパラメータをサポートしていない。