宣言型設定リファレンスガイド
ローカルモードで実行される Anypoint Flex Gateway は、2 つの設定モデルをサポートします。
-
Kubernetes で一般的なリソースベースモデルは、詳細な定義に適しています。各リソースは、設定の
kind の値が次のいずれかになります。-
ApiInstance -
Service -
PolicyBinding -
Configuration
-
-
インラインモデルは簡潔な定義に適していますが、汎用性が低くなります (たとえば、自動ポリシーはリソースベース定義でしか適用できません)。
インライン定義では、設定の
kind の値は ApiInstance のみとなり、この下でサービスとポリシーの両方を定義します。
それぞれの例は「例」を参照してください。
このリファレンスガイドでは、リソースベース設定またはインライン設定に適用可能なリソースについて説明します。
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
| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
必須 |
なし |
他のリソース (ポリシーバインドなど) の対象リファレンスとして使用される API インスタンス識別子。 |
|
省略可能 |
|
|
|
必須 |
なし |
プロトコル、ホスト、ポート、パス (省略可能) を含むプロキシアドレス URL。ベースパスを指定する場合は、どの |
|
省略可能 |
空 |
指定されたサービスとルートのマップ。 |
|
必須 |
なし |
サービスアドレス (およびポート)。サポートされる形式: |
|
省略可能 |
空 |
この API インスタンスに設定されているサービスへのルートの配列。空である場合は、サービスへのデフォルトルートが確立され、すべてのトラフィックがルーティングされます。 |
|
省略可能 |
空 |
このルートの設定。空の場合は、空の |
|
省略可能 |
空 |
アップストリームサービスに要求を転送するために先頭に追加するパス。たとえば、「destinationPath: /api/v1」と指定した場合、この API インスタンスへの要求で「/orders」のようなパスを指定すると、要求は「/api/v1/orders」のように上流にルーティングされます。 |
|
省略可能 |
空 |
このルートのルールの配列。「ポリシーバインド」の「spec.rules」を参照してください。 |
|
省略可能 |
空 |
この API インスタンスに適用するポリシーの配列。 |
|
必須 |
なし |
ポリシー名。 |
|
省略可能 |
|
ポリシーが定義される名前空間。提供ポリシーの場合、この項目の値は |
|
省略可能 |
空 |
ポリシーの設定。「ポリシーバインド」の「spec.config」を参照してください。 |
|
省略可能 |
空 |
このポリシーを 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: <api instance name>
namespace: <optional api instance namespace>
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>
| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
必須 |
なし |
ポリシーバインドの識別子。 |
|
省略可能 |
|
|
|
必須 |
なし |
ポリシーがバインドされる API インスタンスの識別子。 |
|
省略可能 |
|
対象が定義される名前空間。 |
|
必須 |
なし |
ポリシー名。利用可能なパッケージのリストを参照してください。 |
|
省略可能 |
|
ポリシーが定義される名前空間。提供ポリシーの場合、この項目の値は |
|
省略可能 |
空 |
ポリシーの設定。この項目のコンテンツは、指定されたポリシーに依存します。利用可能なパッケージのリストを参照してください。 |
|
省略可能 |
50 |
ポリシー実行チェーン全体におけるポリシーの読み取り順序。 |
|
省略可能 |
空 |
ポリシーが特定の要求に適用されるかどうかを決定するためのルールの配列。これらのルールは OR 形式でチェックされます。最初に True となったルールに従ってポリシーを要求に適合します。各ルールの属性は、AND 形式で適用されます。パスとホストが定義されている場合は、両方が一致しなければルールは True にはなりません。 |
|
省略可能 |
|
要求のパスと一致する正規表現。 要求を上流にルーティングする場合は、この正規表現のキャプチャグループを使用して、パスを置き換えます。 「path: /api(/.*)」と指定すると、/api/orders というパスが指定された要求は、/orders として上流にルーティングされます。 複数のキャプチャグループを指定でき、その場合は、取得されたすべてのサブ文字列が連結されてパスが置き換えられます。 |
|
省略可能 |
|
要求のホストと一致する正規表現。 |
|
省略可能 |
|
要求のメソッドと一致する正規表現。 |
|
省略可能 |
空 |
ヘッダー名と要求に含まれる必要がある値の正規表現のマップ。 各エントリのキーは想定されるヘッダー名で、値はヘッダー値と一致する正規表現です。 |
ポリシーバインドの例
次のリソースは、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
サービス
apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: <service name> namespace: <namespace name> spec: address: <service address including port>
| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
必須 |
なし |
サービス識別子。 |
|
省略可能 |
|
|
|
必須 |
なし |
プロトコル、ホスト、ポートを含むサービスアドレス URL。サポートされる形式: |
サービスの例
次のリソースは、サービス識別子を記述するメタデータを使用して 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
| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
必須 |
なし |
設定エンティティ。 |
|
省略可能 |
|
設定エンティティを特定するための名前空間値。 |
|
必須 |
なし |
ゲートウェイの特性を定義する設定オブジェクト。オブジェクトには |
ログ記録
logging オブジェクトは、メッセージログポリシーを介してランタイムおよびアクセスログの配信を設定します。ログは、サポートされている Fluent Bit v1.8 出力に配信されます。
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
name: <value>
namespace: <namespace name>
spec:
logging:
outputs:
- name:
type:
parameters:
<param-name>: <param-value>
runtimeLogs:
logLevel: <value>
outputs: <value>
accessLogs:
outputs: <value>| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
必須 |
なし |
後でランタイムとアクセスログの設定で参照する、この出力の名前。 |
|
必須 |
なし |
Fluent Bit でサポートされる出力種別。Fluent Bit 出力種別については、 Fluent Bit 出力のドキュメント を参照してください。 |
|
必須 |
なし |
特定の Fluent Bit 出力種別のパラメーターのマップ。Fluent Bit 出力種別のパラメーターについては、 Fluent Bit 出力のドキュメント を参照してください。 |
|
省略可能 |
空 |
アクセスログをリダイレクトする出力名のリスト。 |
|
省略可能 |
|
ログの詳細を指定するパラメーター。サポートされる |
|
省略可能 |
空 |
ランタイムログをリダイレクトする出力名のリスト。 |
値を空白のままにすると、デフォルト値が設定に適用されます。
上記のパラメーターに加えて、Flex Gateway にはログ出力用の変数が用意されています。設定されている場合、変数はログ内のそれぞれの出力の 1 つとして表示されます。
| 変数 | 説明 | 出力 |
|---|---|---|
|
ログに記録されたイベントの日時 |
特定の時刻 (例: |
|
ログに記録されたイベントが発生した Flex Gateway サービス |
|
|
ログに記録されたイベントの |
|
|
ログ種別 |
|
ログの例
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 の共有ストレージサービスを引き続き使用できますが、メモリ内実装が使用されます。
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
name: shared-storage-redis
spec:
sharedStorage:
redis:
address: <redis instance host:port>
username: <redis user username>
password: <redis user password>
db: <redis database name>
| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
必須 |
なし |
|
|
省略可能 |
空 |
Redis ユーザー名。 |
|
省略可能 |
空 |
Redis ユーザーパスワード。 |
|
省略可能 |
0 |
使用する Redis データベース番号。 |
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
例
インライン設定の例
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