api-gateway コマンドは API Gateway を実装します。spnhub コマンドのパラメータはコマンドラインオプションと環境変数のいずれかで指定できます。
パラメータには以下のものがあります。
api-gateway コマンドは起動時とリロードシグナル受信時に構成情報をインベントリ から読み込みます。具体的には以下の順に読み込みます。リロードシグナルは SIGUSR1 です。
1. レルムの読み込み
全てのレルムを読み込みます。
API Gateway はレルムごとに内部が分離されており、マルチテナントのシステムを容易に実装できます。
| name required | string^[a-z0-9][a-z0-9-]*$ レルムの名前。URN の一部として使用される。
文字列は小文字英字、数字、ハイフンのみを含むことができる。
ただし、ハイフンで始まることはできない。
名称 "master" は予約されており、使用できない。
|
| title required | |
| description | |
| urn | string <urn> レルムのURN。形式は urn:chip-in:realm:{realm-name} である。
|
| cacert required | string realm 配下の SPN hub で mTLSにおけるクライアント証明書を発行したCA局の証明書(PEM形式)の文字列
|
| signingKey required | string >= 24 characters realm 配下のAPI Gateway でセッショントークンの署名に使用されるパスワード。
使用できる文字は英字、数字、ハイフン、アンダースコアのみである。
|
| sessionTimeout | integer セッショントークンの有効期限。単位は秒で、デフォルトは 2592000 秒 (30日)。
|
| administrators | Array of strings レルムの管理者のユーザID。ユーザの管理はインベントリでは行わない。認証サービス内でのみ管理され、ここではそのIDのみを参照する。
|
| expiredAt | string <date-time> レルムの有効期限。ISO8601形式で指定する。
この日時を過ぎると、レルムの disabled フラグは true となり、関連するリソースへのアクセスが制限される。
|
| disabled required | boolean レルムが無効化されているかどうかを示すフラグ。
true の場合、レルムは無効化されており、関連するリソースへのアクセスが制限される。
false の場合、レルムは有効であり、通常の操作が可能である。
|
- disabled が True のものは無視します。
- リロードにおいては、一覧の前後を比較し、追加削除を行います。
2. ゾーンの読み込み
レルムごとにゾーンを読み込みます。ゾーンは DNS 権威サーバの管理単位です。
| zone required | string <hostname> ゾーンの名前。FQDN のサフィックスとして使用される。
文字列は小文字英字、数字、ハイフン、ピリオドのみを含むことができる。
|
| title required | |
| description | |
| realm | |
| urn | string <urn> ゾーンのURN。形式は urn:chip-in:zone:{realm-name}:{zone-name} である。
|
| dnsProvider | string ゾーンのDNSレコードを管理するためのDNSプロバイダのURN。
|
| acmeCertificateProvider | string ゾーンのSSL/TLS証明書を自動的に取得するためのACME証明書プロバイダのURL
|
DNS 連携
ゾーンに dnsProvider が設定されている場合、ゾーンに所属する仮想ホストに対してDNSレコードが自動的に作成さます。
また、lets encrypt などの自動証明書発行サービスを使用して、仮想ホストに必要なSSL/TLS証明書を自動的に取得します。
3. サブドメインの読み込み
ゾーンごとにサブドメインを読み込みます。
サブドメインは、ゾーン内でドメインを作成するために使用されます。
| name required | string^([a-z0-9][a-z0-9-]*|@)$ サブドメインの名前。ゾーン名と結合して FQDN を得ることができる。
文字列は小文字英字、数字、ハイフンのみを含むことができる。
ただし、先頭がハイフンであってはならない。
たとえば、 stg というサブドメイン名でゾーンの名前が example.com の場合、
stg.example.com というサブドメインを構成し、www.stg.example.com, login.stg.example.com というような
FQDN の仮想ホストを収容することができる。
特別なサブドメイン名 "@" は、ゾーンのFQDNそのものを表し、ゾーン直下の仮想ホストを収容する。
|
| fqdn | string <hostname> サブドメインの完全修飾ドメイン名(FQDN)。
たとえば、 stg.example.com のように、ゾーン名と結合して得られる。
このFQDNは、サブドメイン内の仮想ホストのFQDNのベースとなる。
|
| zone | string <urn> このサブドメインが属するゾーンのURN。
ゾーンは、サブドメインのFQDNのサフィックスとして使用される。
たとえば、 stg.example.com の場合、ゾーンは example.com となる。
|
| urn | string <urn> サブドメインのURN。形式は urn:chip-in:subdomain:{realm-name}:{zone-name}:{subdomain-name} である。
|
| title required | |
| description | |
| destinationRealm | |
| shareCookie | boolean Default: false このフラグが指定されると、配下の仮想ホストの間でセッション Cookie が共有される。
すなわち、仮想ホストから発行せれるセッション Cookie の domain 属性にはサブドメインのFQDNが指定される。
デフォルトでは Cookie に Domain 属性は設定されない。
サブドメイン配下の仮想ホストのアクセスログ間でセッションによる串刺しが可能になり、シングルサインオンも実装される。
OIDCやSAMLによるシングルサインオンとは異なり、認証サーバへのリダイレクトは不要となる。
|
disabled が True のものは無視されます。
4. 仮想ホストの読み込み
仮想ホストを読み込みます。
仮想ホストは、サブドメインの下にFQDNを持ち、特定のサービスやアプリケーションを識別するために使用されます。
| name required | string^([a-z0-9][a-z0-9-]*|@)$ 仮想ホストの名前。指定したサブドメインの名前と結合して FQDN を得ることができる。
文字列は小文字英字、数字、ハイフンのみを含むことができる。
たとえば、 www という仮想ホスト名でサブドメインの FQDN が example.com の場合、FQDN は www.example.com となる。
特別なホスト名 "@" はサブドメインのFQDN そのものを仮想ホストの FQDN とすることを表す。
|
| title required | |
| description | |
| realm | |
| urn | string <urn> 仮想ホストのURN。形式は urn:chip-in:virtual-host:{realm-name}:{virtual-host-name} である。
|
| subdomain required | string この仮想ホストが属するサブドメインのURN。
仮想ホストのFQDNは、仮想ホストの名前とサブドメインの名前を結合して得られる。
たとえば、 www という仮想ホスト名でサブドメインの FQDN が stg.example.com の場合、FQDN は www.stg.example.com となる。
サブドメインは自身のレルムに属するものかサブドメインの貸出先に自身のレルムが指定されているものでなくてはならない。
|
| routingChain required | string この仮想ホストに紐づくルーティングチェーンのURN。
ルーティングチェーンは、リクエストの処理を行うためのルールの集合であり、リクエストを適切なマイクロサービスに転送するためのロジックを定義する。
|
| accessLogRecorder | string アクセスログを記録するサービスのURN。デフォルトでは標準出力に出力される。
|
| accessLogMaxValueLength | integer Default: 512 アクセスログの項目の値の最大長。デフォルトは 512 で、512文字を超える場合は切り捨てられる。
|
| object アクセスログ出力のフォーマット。1行1オブジェクトのJSON形式で出力される。
以下の属性は常に出力される。
| 属性名 |
値 |
| timestamp |
ログの時刻 |
| category |
"access-log" で固定 |
| host |
仮想ホストのFQDN |
|
| certificate | |
| key | string この仮想ホストのサーバ証明書の秘密鍵。PEM形式の秘密鍵を指定する。
秘密鍵は、HTTPS通信を行うために必要であり、仮想ホストが提供するサービスのセキュリティを確保する。
|
| disabled | boolean 仮想ホストが無効化されているかどうかを示すフラグ。
true の場合、仮想ホストは無効化されており、仮想ホストは削除され、アクセスは拒否される（TLSの場合、SSL_ERROR_HANDSHAKE_FAILURE を返し、平文の場合、400 Bad Request が返す）。
false の場合、仮想ホストは有効であり、アクセスが可能である。
|
disabled が True のものは無視されます。
5. ルーティングチェーンの読み込み
レルムごとにルーティングチェーンを読み込みます。
ルーティングチェーンは、API Gateway 内で HTTP リクエストの処理を行うためのルールの集合であり、リクエストを適切なマイクロサービスに転送するためのロジックを定義できます。
| name required | string ルーティングチェーンの名前。URN の一部として使用される。
文字列は小文字英字、数字、ハイフン、アンダースコアのみを含むことができる。
|
| realm | |
| urn | |
| title required | |
| description | |
| Array of objects ルーティングチェーンのルールのリスト。各ルールは、リクエストを処理するための条件とアクションを定義する。
ルールは、リクエストのパスやヘッダなどを照合し、適切なアクションを実行するために使用される。
|