宣言型設定リファレンスガイド

ローカルモードで実行される Anypoint Flex Gateway は、2 つの設定モデルをサポートします。

  • Kubernetes で一般的なリソースベースモデルは、詳細な定義に適しています。各リソースは、設定の ​kind​ の値が次のいずれかになります。

    • ApiInstance

    • Service

    • PolicyBinding

    • Configuration

  • インラインモデルは簡潔な定義に適していますが、汎用性が低くなります (たとえば、自動ポリシーはリソースベース定義でしか適用できません)。

    インライン定義では、設定の ​kind​ の値は ​ApiInstance​ のみとなり、この下でサービスとポリシーの両方を定義します。

gateway configuration models

それぞれの例は​「例」​セクションを参照してください。

このリファレンスガイドでは、リソースベース設定またはインライン設定に適用可能なリソースについて説明します。

API インスタンス

apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: <api instance name>
  namespace: # optional namespace name
spec:
  address: <proxy address including port and path>
  services: # optional map of upstream services
    <name>:
      address: <service address>
      routes: # optional array of routes to service
        - config: # optional route configuration
            destinationPath: <optional base path to upstream service>
          rules: # optional route rules
  policies: # optional array of policies
    - policyRef:
        name: <name of the policy>
        namespace: <optional namespace of the policy>
      config: # optional policy configuration
      rules: # optional policy rules
パラメーター 必須または省略可能 デフォルト値 説明

metadata.name

必須

なし

他のリソース (ポリシーバインドなど) の対象リファレンスとして使用される API インスタンス識別子。

metadata.namespace

省略可能

default

spec.address

必須

なし

プロトコル、ホスト、ポート、パス (省略可能) を含むプロキシアドレス URL。ベースパスを指定する場合は、どの ​rules.path​ 属性にも指定されていないパスでなければなりません。サポートされる形式: protocol://host:port/path​ (​path​ は省略可能で、​protocol​ は ​http​ または ​https​)。

spec.services

省略可能

指定されたサービスとルートのマップ。

spec.services[name].address

必須

なし

サービスアドレス (およびポート)。サポートされる形式: protocol://host:port​ (​protocol​ は ​http​ または ​https​)。

spec.services[name].routes

省略可能

この API インスタンスに設定されているサービスへのルートの配列。空である場合は、サービスへのデフォルトルートが確立され、すべてのトラフィックがルーティングされます。

spec.services[name].routes[#].config

省略可能

このルートの設定。空の場合は、空の ​destinationPath​ でデフォルトの設定が適用されます。

spec.services[name].routes[#].config.destinationPath

省略可能

アップストリームサービスに要求を転送するために先頭に追加するパス。たとえば、「destinationPath: /api/v1」と指定した場合、この API インスタンスへの要求で「/orders」のようなパスを指定すると、要求は「/api/v1/orders」のように上流にルーティングされます。

spec.services[name].routes[#].rules

省略可能

このルートのルールの配列。「ポリシーバインド」の「​spec.rules​」を参照してください。

spec.policies

省略可能

この API インスタンスに適用するポリシーの配列。

spec.policies[#].policyRef.name

必須

なし

ポリシー名。

spec.policies[#].policyRef.namespace

省略可能

metadata.namespace​ の値

ポリシーが定義される名前空間。提供ポリシーの場合、この項目の値は ​default​ である必要があります。

spec.policies[#].config

省略可能

ポリシーの設定。「ポリシーバインド」の「​spec.config​」を参照してください。​policies[#].config​ 項目で環境変数を使用するには、​ポリシーバインドの環境変数​を参照してください。

spec.policies[#].rules

省略可能

このポリシーを API インスタンスに適用するためのルールの配列。 「ポリシーバインド」の「​spec.rules​」を参照してください。

API インスタンスの例

次のリソースは、インスタンス識別子を記述するメタデータを使用して ​ApiInstance​ を指定しています。​metadata.name​ 値は、他のリソース (ポリシーバインドなど) の対象リファレンスとして使用されます。​spec.services.routes.config.destinationPath​ 値は、​rules​ の下に指定されているパスの先頭に ​/v1/apps​ を追加し、ベースパスのように機能します。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: hello-flex-gateway-instance
spec:
  address: http://0.0.0.0:8080
  services:
    json:
      address: https://<upstream address>:443/
      routes:
        - rules:
            - path: /api(/users/.*)
            - path: /api(/comments/.*)
          config:
            destinationPath: /v1/apps

ポート共有

次の ​ApiInstance​ リソースは、2 つの異なる API インスタンスがポート 8080 でリスンする API ポート共有を示しています。

---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: httpbin-example
spec:
  address: http://0.0.0.0:8080/api/httpbin/
  services:
    upstream:
      address: https://<upstream address>:443
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: json-example
spec:
  address: http://0.0.0.0:8080/api/json/
  services:
    upstream:
      address: https://<upstream address>:443

両方のサービスはポート 8080 でリスンします。次に例を示します。

curl http://localhost:8080/api/httpbin/get -v
curl http://localhost:8080/api/json/users/1 -v

ポートを共有する API のベースパスは競合しない必要があります。たとえば、次のパスの組み合わせは許可されません。

http://0.0.0.0:8080/cats
http://0.0.0.0:8080/cats/dogs

ポートには TLS が適用されます。そのため、ポートを共有するすべての API インスタンスに同じ TLS ポリシーが適用されます。

ポリシーバインド

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: <policy binding name>
  namespace: <namespace name>
spec:
  targetRef:
    name: <name of api instance or upstream service>
    namespace: <optional namespace of api instance or upstream service>
  policyRef:
    name: <policy name>
    namespace: <optional policy namespace>
  config: # optional policy configuration
  order: # optional policy read order
  rules: # optional policy rules
  - path: <path regular expression>
    methods: <methods regular expression>
    host: <host regular expression>
    headers: <headers map>
      <header-name>: <header value regular expression>
パラメーター 必須または省略可能 デフォルト値 説明

metadata.name

必須

なし

ポリシーバインドの識別子。

metadata.namespace

省略可能

default

spec.targetRef.name

必須

なし

ポリシーがバインドされる API インスタンスまたはアップストリームサービスの識別子。

spec.targetRef.namespace

省略可能

metadata.namespace​ の値

対象が定義される名前空間。

spec.policyRef.name

必須

なし

ポリシー名。利用可能なパッケージのリストを参照してください。

spec.policyRef.namespace

省略可能

metadata.namespace​ の値

ポリシーが定義される名前空間。提供ポリシーの場合、この項目の値は ​default​ である必要があります。

spec.config

省略可能

ポリシーの設定。この項目のコンテンツは、指定されたポリシーに依存します。利用可能なパッケージのリストを参照してください。​config​ 項目で環境変数を使用するには、​ポリシーバインドの環境変数​を参照してください。

spec.order

省略可能

50

ポリシー実行チェーン全体におけるポリシーの読み取り順序。

spec.rules

省略可能

ポリシーが特定の要求に適用されるかどうかを決定するためのルールの配列。これらのルールは OR 形式でチェックされます。最初に True となったルールに従ってポリシーを要求に適合します。各ルールの属性は、AND 形式で適用されます。パスとホストが定義されている場合は、両方が一致しなければルールは True にはなりません。

spec.rules[#].path

省略可能

.*

要求のパスと一致する正規表現。

要求を上流にルーティングする場合は、この正規表現のキャプチャグループを使用して、パスを置き換えます。

「path: /api(/.*)」と指定すると、/api/orders というパスが指定された要求は、/orders として上流にルーティングされます。

複数のキャプチャグループを指定でき、その場合は、取得されたすべてのサブ文字列が連結されてパスが置き換えられます。

spec.rules[#].host

省略可能

.*

要求のホストと一致する正規表現。

spec.rules[#].methods

省略可能

.*

要求のメソッドと一致する正規表現。

spec.rules[#].headers

省略可能

ヘッダー名と要求に含まれる必要がある値の正規表現のマップ。

各エントリのキーは想定されるヘッダー名で、値はヘッダー値と一致する正規表現です。

ポリシーバインドの例

次のリソースは、​route​ ポリシーを API インスタンスにバインドして、​rules​ で指定されたトラフィックを ​Service​ 設定スニペットで指定されたプロキシアドレスにルーティングします。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: hello-flex-gateway-route
  namespace: e-commerce
spec:
  targetRef:
    name: hello-flex-gateway-instance
  policyRef:
    name: route
    namespace: default
  config:
    destinationRef:
      name: json
      namespace: e-commerce
  rules:
  - path: /api/json(/.*)

次のリソースは、​http-basic-authentication-flex​ ポリシーを API インスタンスにバインドし、要求に ​config.username​ と ​config.password​ で定義されている基本ログイン情報を含めることを必須にします。このポリシーには読み取り順序に ​2​ の値が与えられます。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: hello-flex-gateway-auth
  namespace: e-commerce
spec:
  targetRef:
    name: hello-flex-gateway-instance
    namespace: e-commerce
  policyRef:
    name: http-basic-authentication-flex
    namespace: default
  config:
    username: chris
    password: admin
  order: 2

ポリシーバインドの環境変数

ポリシーバインドリソースとインラインポリシーバインドの両方で ​config​ 項目の環境変数がサポートされます。使用可能な環境変数は環境に応じて異なります。

環境変数を参照するには、次のようにプレフィックス ​$​ を付けて環境変数を指定します。

- policyRef:
    name: http-basic-authentication-flex
  config:
    username: $USERNAME
    password: $PASSWORD

API を使用した

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: <service name>
  namespace: <namespace name>
spec:
  address: <service address including port>
パラメーター 必須または省略可能 デフォルト値 説明

metadata.name

必須

なし

サービス識別子。

metadata.namespace

省略可能

default

spec.address

必須

なし

プロトコル、ホスト、ポートを含むサービスアドレス URL。サポートされる形式: protocol://host:port​ (​protocol​ は ​http​ または ​https​)。

サービスの例

次のリソースは、サービス識別子を記述するメタデータを使用して ​Service​ を定義しています。​metadata.namespace​ 値は ​ApiInstance​ 設定で指定されている名前空間と一致します。​spec.address​ は、API 実装のアドレスです。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: json-example
  namespace: e-commerce
spec:
  address: https://<upstream address>:443/

設定

Configuration​ エンティティを作成することによって目的のゲートウェイ状態を定義します。 Configuration​ エンティティは、Flex Gateway 自身のいくつかのランタイム設定 (​ログ​や​共有ストレージ​など) を指定します。定義には以下が含まれます。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging: # logging configuration
  sharedStorage: # shared storage configuration
パラメーター 必須または省略可能 デフォルト値 説明

metadata.name

必須

なし

設定エンティティ。

metadata.namespace

省略可能

default

設定エンティティを特定するための名前空間値。

spec

必須

なし

ゲートウェイの特性を定義する設定オブジェクト。オブジェクトには ​logging​、​sharedStorage​、​tls​ があります。

ログ記録

logging​ オブジェクトは、メッセージログポリシーを介してランタイムおよびアクセスログの配信を設定します。ログは、サポートされている Fluent Bit v2.0 出力に配信されます。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <value>
  namespace: <namespace name>
spec:
  logging:
    outputs:
    - name: <output-name>
      type: <output-type>
      parameters:
        <param-name>: <param-value>
    runtimeLogs:
      logLevel: <value>
      outputs: <value>
    accessLogs:
      outputs: <value>
パラメーター 必須または省略可能 デフォルト値 説明

logging.outputs[#].name

必須

なし

後でランタイムとアクセスログの設定で参照する、この出力の名前。

logging.outputs[#].type

必須

なし

Fluent Bit でサポートされる出力種別。Fluent Bit 出力種別については、 Fluent Bit 出力のドキュメント​ を参照してください。

logging.outputs[#].parameters

必須

なし

特定の Fluent Bit 出力種別のパラメーターのマップ。Fluent Bit 出力種別のパラメーターについては、 Fluent Bit 出力のドキュメント​ を参照してください。

logging.accessLogs.outputs

省略可能

アクセスログをリダイレクトする出力名のリスト。

logging.runtimeLogs.logLevel

省略可能

info

ログの詳細を指定するパラメーター。サポートされる ​logLevel​ の種別は冗長レベルの高い順にリストされており、​debug​、​info​、​warn​、​error​、​fatal​ です。

logging.runtimeLogs.outputs

省略可能

ランタイムログをリダイレクトする出力名のリスト。

値を空白のままにすると、デフォルト値が設定に適用されます。

上記のパラメーターに加えて、Flex Gateway にはログ出力用の変数が用意されています。設定されている場合、変数はログ内のそれぞれの出力の 1 つとして表示されます。

変数 説明 出力

date

ログに記録されたイベントの日時

特定の時刻 (例: 17/11/2022-09:48:27AM​)

logger

ログに記録されたイベントが発生した Flex Gateway サービス

flex-gateway-agent​、​flex-gateway-envoy​、または ​flex-gateway-fluent

level

ログに記録されたイベントの ​Loglevel

debug​、​info​、​warn​、​error​、または ​fatal

kind

ログ種別

runtimeLog​ または ​accessLog

ログの例

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: logging
spec:
  logging:
    outputs:
    - name: log-to-file
      type: file
      parameters:
        path: /var/log
        file: log.txt
        format: template
        template: |
          [{date}][{logger}][{level}][{kind}] {message}
    runtimeLogs:
      logLevel: info
      outputs:
      - log-to-file
    accessLogs:
      outputs:
      - log-to-file

共有ストレージ

sharedStorage​ オブジェクトは、共有ストレージのゲートウェイを設定します。本番ワークフローでは Redis​ (最小バージョン 4.0.0) を使用する必要がありますが、その定義は省略可能です。Redis が定義されていない場合、ポート 4000 の共有ストレージサービスを引き続き使用できますが、メモリ内実装が使用されます。

必要に応じて、Redis とトランスポート層セキュリティ (TLS) を使用して、機密データを保護し、不正なアクセスを防止して、サービスの信頼性を維持できます。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
 name: shared-storage-redis
spec:
 sharedStorage:
   redis:
     address: <string> // REQUIRED
     username: <string> // OPTIONAL
     password: <string> // OPTIONAL
     db: <string> // OPTIONAL
     tls: // OPTIONAL
       trustedCA: <string> // OPTIONAL
       certificate: // OPTIONAL
         keyPassphrase <string> // OPTIONAL
         key: <string> // REQUIRED
         crt: <string> // REQUIRED
       alpn: <array> // OPTIONAL
       skipValidation: <boolean> // OPTIONAL
       minversion: <string> // OPTIONAL
       maxversion: <string> // OPTIONAL
       ciphers: <array> // OPTIONAL
パラメーター 必須または省略可能 デフォルト値 説明

sharedStorage.redis.address

必須

なし

host:port​ 形式の Redis インスタンスアドレス。

sharedStorage.redis.username

省略可能

Redis ユーザー名

sharedStorage.redis.password

省略可能

Redis ユーザーパスワード

sharedStorage.redis.db

省略可能

0

使用する Redis データベース番号

sharedStorage.redis.tls

省略可能

Redis TLS 設定

sharedStorage.redis.tls.trustedCA

省略可能

なし

サーバー証明書を確認する時に使用するルート認証機関

sharedStorage.redis.tls.certificate

省略可能

なし

サーバーに提供するクライアント証明書

sharedStorage.redis.tls.keyPassphrase

省略可能

none

証明書鍵パスフレーズ。指定された場合、DEK-Info ヘッダーが含まれる非公開キー形式を使用します。未指定の場合、非公開キーは暗号化できません。

sharedStorage.redis.tls.certificate.key

必須

なし

証明書の非公開キー部分

sharedStorage.redis.tls.certificate.crt

必須

なし

証明書の公開キー部分

sharedStorage.redis.tls.skipValidation

省略可能

false

true の場合、サーバーによって提供されたすべての証明書が受け入れられます。

sharedStorage.redis.tls.minversion

省略可能

1.2

許容される最小 TLS バージョン

sharedStorage.redis.tls.maxversion

省略可能

1.3

許容される最大 TLS バージョン

sharedStorage.redis.tls.alpn

省略可能

空のリスト

サポートされているアプリケーションレベルプロトコルの優先リスト (h2、http/1.1 など)。

sharedStorage.redis.tls.ciphers

省略可能

TLS/Redis では、以下を除いて ​TLS ポリシー​と同じ暗号化がサポートされます。

  • TLS_RSA_WITH_NULL_SHA

  • TLS_PSK_WITH_AES_256_CBC_SHA

  • TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA

  • TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA

  • TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256

Redis 共有ストレージ例

Redis ストレージサービスは、オブジェクトストアインターフェースと Redis バックエンド間のブリッジとして機能する、REST API オブジェクトストアの実装です。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
 name: shared-storage-redis
spec:
 sharedStorage:
   redis:
     address: redis.e-commerce.svc:6379
     username: ecomm-user
     password: ecomm-pwd-123
     DB: 7
Redis と TLS の共有ストレージ例

必要に応じて、Redis と TLS を使用してデータを保護し、安全な通信を確保できます。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: internal.redis.com:6379
      tls:
        skipValidation: false
        minVersion: "1.1"
        maxVersion: "1.3"
        alpn:
          - h2
          - http/1.1
        ciphers:
          - TLS_AES_128_GCM_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_RSA_WITH_3DES_EDE_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA
          - TLS_RSA_WITH_AES_256_CBC_SHA
          - TLS_RSA_WITH_AES_128_CBC_SHA256
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        trustedCA: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

        certificate:
          keyPassphrase: "****"
          key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----

          crt: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
ローカル共有ストレージの例

ローカルストレージサービスは、データをメモリに保存する REST API オブジェクトストアの実装です。Flex Gateway を停止または再起動すると、すべてのデータが失われます。

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
 name: rtm-config
 namespace: sales
spec:
 sharedStorage:
   local:
     enabled: true

インライン設定の例

apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: api-example
spec:
  address: http://0.0.0.0:8080
  services:
    api-example:
      address: https://<your url>:443/
      routes:
        - rules:
            - path: /api(/users/.*)
            - path: /api(/comments/.*)
          config:
            destinationPath: /v1/apps
  policies:
    - policyRef:
        name: http-basic-authentication-flex
      config:
        username: chris
        password: admin

リソースベース設定の例

---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: ingress-http
spec:
  address: http://0.0.0.0:8080
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Service
metadata:
  name: json
spec:
  address: https://<your url>:443/
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-http-route
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: route
  config:
    destinationRef:
      name: json
  rules:
  - path: /api(/users/.*)
  - path: /api(/comments/.*)
---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-http-authentication
spec:
  targetRef:
    name: ingress-http
  policyRef:
    name: http-basic-authentication-flex
  config:
    username: chris
    password: admin