Kubernetes クラスターでの Flex Gateway の使用開始

Kubernetes クラスターまたは Kubernetes クラスターに基づく OpenShift クラスターで Anypoint Flex Gateway の使用を開始します。Anypoint Platform に接続する Flex Gateway デプロイメントをセットアップし、そのデプロイメントを使用してトラフィックを API にルーティングします。このガイドでは、次のタスクの概要について説明します。

トークンを使用した接続モードでの Flex Gateway のダウンロード、登録、デプロイメント
API Manager でのゲートウェイで実行されるシンプルな API の作成
API Manager で設定する基本認証ポリシーを使用した API の保護

Flex Gateway デプロイメントプロセスでは、自分で作成する、または Kubernetes プロフェッショナルがプロビジョニングする有効な Kubernetes クラスターが必要です。

Kubernetes クラスターのセットアップには、このガイドには記載されていないスキルや専門知識のレベルが求められます。Kubernetes のクラスター設定は、サービスプロバイダーやプラットフォームによって大きく異なります。クラスター設定に関する質問がある場合は、Kubernetes サービスプロバイダーのドキュメントを参照するか、 Kubernetes ドキュメントを使用してください。

Kubernetes クラスターはないが、クラスターを作成せずに Flex Gateway をすぐに試してみたい場合は、(Docker の) 「Flex Gateway の使用開始」を参照してください。このガイドでは Docker のみを使用するため、クラスター設定は必要ありません。

始める前に

このガイドの手順を開始する前に、次の前提条件を満たしていることを確認します。

自分の Anypoint Platform 組織のユーザー名とパスワード。Anypoint Platform アカウントを持っていない場合は、Anypoint Platform でトライアル組織を作成してください。

Docker のインストール。

ターミナルウィンドウから docker --version を実行して、このツールがインストールされているかどうかを調べます。Docker をインストールする必要がある場合は、 Docker Desktop をお試しください。

Helm バージョン 3.0.0 以降が必要です。

ターミナルウィンドウから helm version を実行して、このツールがインストールされているかどうかを調べ、そのバージョンを確認します。インストールまたはアップグレードするには、 Helm Web サイトを使用します。

Kubernetes kubectl コマンドラインツール。

ターミナルウィンドウから kubectl version --output=yaml を実行して、このツールがインストールされているかどうかを調べます。インストールされていない場合、 Kubernetes ドキュメントを参照して、使用可能なインストールツールから kubectl を見つけます。

curl コマンドラインツール。

ターミナルウィンドウから curl --version を実行して、このツールがインストールされているかどうかを調べます。インストールされていない場合、パッケージマネージャーを使用してマシンにダウンロードします。

クラスターの要件

Kubernetes クラスターのホストは、一般的なクラウドベースサービス (Amazon Elastic Kubernetes Service (EKS)、Azure Kubernetes Service (AKS)、Google Kubernetes Engine (GKE) など) を含む、いずれかのサポートされている Kubernetes プロバイダーになります。

ロールベースのアクセス制御 (RBAC) を有効にする Kubernetes クラスターに Flex Gateway をデプロイする場合、Flex Gateway で使用されるカスタムリソース定義 (CRD) のインストールを許可するクラスターレベルの権限が必要です。 OpenShift では、cluster-admin ロールによってこのレベルのアクセスが提供されます。

このガイドの手順を完了するには、Kubernetes クラスターを作成するか、Flex Gateway デプロイメントの既存の Kubernetes クラスターを使用する必要があります。このガイドでは、Helm を使用して Flex Gateway を Kubernetes クラスターにデプロイし、Anypoint Platform に接続します。

このガイドのデモ目的で使用される小規模な Kubernetes クラスターには次の最小要件が適用されます (本番環境の要件には適用されません)。

1 つ以上のノード。
LoadBalancer 種別の Service リソースの作成のサポート。

この要件により、このガイドの使用時にデプロイメントエラーを回避できます。ただし、ゲートウェイをデプロイするときに Service 種別をカスタマイズすることもできます。Flex Gateway では、ClusterIP、NodePort、LoadBalancer (デフォルト)、ExternalName サービスがサポートされています。「Helm chart for Flex Gateway (Flex Gateway の Helm チャート)」の service.type キーを参照してください。

デプロイメント手順に必要な計算リソースが次の値 (EKS t3.micro インスタンス種別に相当) を超えることはほとんどありません。
- vCPU: 2 vCPU
- メモリ: 1 GiB
- ネットワーク: 最大 5 ギガビット
- 最大 ENI: 2
- 最大 IP: 4

クラスターのデプロイメント手順の準備ができているかどうかを調べるには、デプロイメントを開始する前にクラスターを確認する必要があります。このチェックでは、一連の kubectl コマンドを実行する必要があります。

ステップ 1: Flex Gateway イメージをダウンロードする

Docker を使用して、Docker Hub リポジトリから Flex Gateway イメージをダウンロードします。

この手順は、「ステップ 2: Flex Gateway を登録する」で Flex Gateway を Anypoint Platform に登録するための前提条件です。登録は、「ステップ 4: Flex Gateway をデプロイして接続する」で Helm を介してゲートウェイをデプロイするときに行う必要があります。

ターミナルウィンドウで次のコマンドを実行して、Docker が実行されていることを確認します。
```
docker info
```
このコマンドの実行後にエラーが発生した場合は、Docker のトラブルシューティングに関する情報を参照してください。
ターミナルウィンドウで次のコマンドを実行します。
```
docker pull mulesoft/flex-gateway:latest
```
このコマンドが成功すると、次のようなメッセージがターミナルウィンドウに出力されます。
```
latest: Pulling from mulesoft/flex-gateway
Digest: sha256:e55555abcdefg1234567zxynwo33333fadjf
Status: Image is up to date for mulesoft/flex-gateway:latest
docker.io/mulesoft/flex-gateway:latest
```
このコマンドの実行時に権限の問題が発生した場合は、sudo を使用してください。

ステップ 2: Flex Gateway を登録する

Anypoint Runtime Manager で生成された一時トークンを使用して、ターミナルウィンドウから Flex Gateway イメージを登録します。この手順では、名前付きゲートウェイの登録プロパティが含まれるローカル registration.yaml ファイルが生成されます。これらのプロパティは、「ステップ 4: Flex Gateway をデプロイして接続する」で Helm チャートに組み込まれます。

ターミナルウィンドウから、Flex Gateway 登録ファイル (registration.yaml) のディレクトリを準備します。
1. ディレクトリを作成します。
  mkdir flex-registration
2. 新しいディレクトリに移動します。
  cd flex-registration
Anypoint Platform にログインし、[Runtime Manager] を選択します。
Runtime Manager から、Flex Gateway を登録する手順を見つけます。
1. サイドナビゲーションパネルで、[Flex Gateways] をクリックします。
2. [Add Gateway (ゲートウェイを追加)] をクリックします。
3. 次のいずれかの環境を選択します。
  - Kubernetes
  - OpenShift
4. 開いたページで、[Register your gateway (ゲートウェイを登録)] セクションでコマンドを見つけます。
  
  Kubernetes の例:
  
  強調表示されたコマンドブロックには、一意の組織 ID と一時トークンが含まれています。
ターミナルウィンドウで、Runtime Manager から ./flex-registration ディレクトリにコマンドブロックをコピーします。

Runtime Manager によって必要な組織およびトークン値が提供されます。
コマンドを実行する前に、コマンドブロックの最後の <gateway-name> をゲートウェイの一意の名前 (my-gateway など) に置き換えます。

ゲートウェイに指定する名前は、Anypoint Platform 組織および環境のスコープ内で一意である必要があります。この登録ステップは一度完了すれば済みます。名前付きゲートウェイおよび組織ごとに複数回行う必要はありません。
ターミナルウィンドウから、編集したコマンドを実行します。

コマンドが成功すると、./flex-registration ディレクトリに registration.yaml が生成され、次のメッセージがターミナルウィンドウに表示されます。
```
Starting registration, please be patient.
Registration completed, the configuration files were written
in directory "/registration". For security, modify the file permissions
to restrict production scenario access to the user running flex.
```
ターミナルウィンドウのメッセージの /registration は、Docker コンテナ内のディレクトリを表しています。

このコマンドの実行時にファイル権限の問題が発生した場合は、sudo を使用してください。コマンドを実行する前にトークンの期限が切れた場合、400 Bad Request (400 不正な要求) エラーが発生します。その場合、[Runtime Manager] ページを更新して、新しいトークンを生成し、ページに表示される変更済みのコマンドを実行する必要があります。

ステップ 3: Helm チャートのリポジトリを追加する

Flex Gateway チャートリポジトリを追加します。Flex Gateway の Helm チャートのプロパティについての詳細は、 ArtifactHUB を参照してください。

Helm チャートの flex-gateway という名前の Helm リポジトリを追加します。
```
helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm
```
このコマンドにより、リポジトリが追加されます。その名前の Helm リポジトリがすでにマシンに存在する場合はこのプロセスはスキップされます。
- 新しいリポジトリの場合、コマンドで次のメッセージが返されます。
  "flex-gateway" has been added to your repositories
- リポジトリがすでに存在する場合、コマンドで次のメッセージが返されます。
  "flex-gateway" already exists with the same configuration, skipping
helm repo up を実行します。

コマンドで次のメッセージが返されます。
```
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "flex-gateway" chart repository
Update Complete. ⎈Happy Helming!⎈
```
マシンに複数の Helm リポジトリがある場合、ターミナルウィンドウのメッセージにすべてのリポジトリがリストされます。

ステップ 4: Flex Gateway をデプロイして接続する

Helm を使用して Flex Gateway をクラスターのノードにデプロイし、Anypoint Platform に接続します。デプロイしたら、Runtime Manager を使用して、ゲートウェイが存在していて、Anypoint Platform に接続されていることを確認します。

始める前に:

「クラスターを確認する」の手順に従って、Kubernetes クラスターが使用可能であることを確認します。まだ「クラスターの要件」を確認していない場合は確認します。これらの前提条件は、デプロイメントエラーを回避するのに役立ちます。

Kubernetes クラスターの準備ができていることを確認したら、ゲートウェイをデプロイして接続します。

接続モードでゲートウェイをデプロイするための Helm コマンドを実行します。
```
helm -n gateway upgrade -i --create-namespace \
--wait ingress flex-gateway/flex-gateway \
--set gateway.mode=connected \
--set-file registration.content=registration.yaml
```
このコマンドにより、gateway 名前空間と ingress リリースが作成されます (これらが存在しない場合)。Helm リポジトリ名と Helm チャート名のコマンド構文は、<helm-repo-name>/<helm-chart-name> です。

Helm チャートのデフォルトのデフォルトはローカルモードであるため、コマンドで --set gateway.mode=connected を使用します。

このコマンドが成功すると、ingress リリースへのアップグレードを示すメッセージが出力されます。
```
Release "ingress" does not exist. Installing it now.
NAME: ingress
LAST DEPLOYED: Mon Mar 20 21:36:19 2023
NAMESPACE: gateway
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
同じ名前空間、リポジトリ、チャート名でこのコマンドを実行するたびに、ingress リリースの REVISION 値が 1 ずつ増加します。たとえば、2 回コマンドを実行すると、新しいリビジョン番号が表示されます (REVISION: 2)。LAST DEPLOYED には、そのリビジョンの日付が反映されます。

UPGRADE FAILED 応答を受信した場合は、この問題に関するトラブルシューティング情報を参照してください。
ゲートウェイを実行するポッドの状況を確認する場合は、次の kubectl コマンドを実行します。
```
kubectl get pods -n gateway
```
出力に、ポッドが gateway 名前空間で正常に実行されているかどうかが示されます。
```
NAME                       READY   STATUS        RESTARTS   AGE
ingress-57bc75cb46-dmkdq   1/1     Running       0          35s
```
Runtime Manager に戻ります。
1. [Add a Flex Gateway (Flex Gateway の追加)] ページのサイドナビゲーションパネルから [← Flex Gateway] を選択します。
2. [Flex Gateways] ページの登録済みゲートウェイに移動します。
  
  ページの検索項目を使用して、ゲートウェイのリストを絞り込むことができます。
3. ゲートウェイの状況が [Connected (接続済み)] であることを確認します。
  
  状況は [Disconnected (切断済み)] の場合、クラスター設定が正しくないか、ネットワークの問題が発生している可能性があります。詳細は、「トラブルシューティング」を参照してください。

ステップ 5: シンプルな API をパブリッシュして Flex Gateway にデプロイする

Anypoint API Manager でシンプルな API を作成してゲートウェイにデプロイします。

Runtime Manager で、ゲートウェイの [View APIs (API を表示)] メニューオプションをクリックし、その [View APIs (API を表示)] ページに移動します。

または、Anypoint Platform メニューから API Manager に移動することもできます。
開いたページから、[Add API (API を追加)] をクリックし、([Add new API (新しい API を追加)] が存在する場合はそれをクリックして) API Manager の [APIs / Add API (API/API を追加)] ページに移動します。
[APIs / Add API (API/API を追加)] から、[Runtime (ランタイム)] 設定から始まる API 設定の各ページを処理していき API を設定します。
1. [Runtime (ランタイム)] 設定ページから、ランタイムとして [Flex Gateway] を選択します。
2. ページの [Select a gateway (ゲートウェイを選択)] 領域で各自のゲートウェイを見つけて選択します。
  
  必要に応じて、検索項目を使用して見つけます。
3. [Next (次へ)] をクリックして [API] ページを開きます。
[APIs / Add API (API/API を追加)] に関連付けられた [API] 設定ページで、API 参照名とアセットタイプを指定します。
1. [Create new API (新しい API を作成)] をクリックします。
  
  残りの手順では、Anypoint Exchange の新しい HTTP API を作成してテストするためのステップについて説明します。ただし、このページから Exchange の既存の API を選択することもできます。そのプロセスについては、API Manager ドキュメントの「新しい API を追加する」を参照してください。
2. my-api などの API 参照名を入力します。
3. アセットタイプに HTTP API を選択します。
4. [Next (次へ)] をクリックして [Endpoint (エンドポイント)] 設定ページを開きます。
[APIs / Add API (API/API を追加)] に関連付けられた [Endpoint (エンドポイント)] ページで、API のエンドポイントをセットアップします。
1. [Scheme (スキーム)] には、デフォルトの [HTTP] 設定を使用します。
  
  このガイドでは、シンプルな HTTP API に焦点を絞っています。HTTPS 設定についての詳細は、「接続モードでの Flex Gateway の TLS コンテキストの設定」を参照してください。
2. [Implementation URI (実装 URI)] 項目に次の URI をコピーします。
  https://jsonplaceholder.typicode.com/
3. [Port (ポート)] 項目に「80」と入力します。
  
  このガイドの例では、API Manager のデフォルトポート 8081 ではなく HTTP ポート 80 を使用します。これは、作成されたサービスは受信ポート 80 をポッドの対象ポート 80 にマップするためです。「Helm chart for Flex Gateway (Flex Gateway の Helm チャート)」の service.http.port キーを参照してください。
4. [Next (次へ)] をクリックして [Review (確認)] ページを開きます。
[APIs / Add API (API/API を追加)] に関連付けられた [Review (確認)] ページで、次の作業を行います。
1. API 設定を確認します。
2. 必要に応じて、[Edit (編集)] を使用して設定を変更します。
3. 設定が正しい場合、[Save & Deploy (保存してデプロイ)] をクリックします。
  
  ゲートウェイ内のポート 80 のすべての受信 HTTP 要求は、jsonplaceholder サービスにプロキシされます。
ターミナルウィンドウから、API インスタンスをテストします。
1. 外部 IP アドレスを取得し、それを使用して IP が実装 URI にリダイレクトされていることを確認します。
  kubectl -n gateway get services
  コマンドで次の例のような結果が返されます。
  NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress LoadBalancer 10.100.145.109 <123456.aws.com> 80:30524/TCP,443:31710/TCP 7d7h
  EXTERNAL-IP 値 <123456.aws.com> はサンプルで、実際の値ではありません。
2. <your_external_ip> を前のステップの各自の EXTERNAL-IP に置き換えて、次の curl コマンドを実行します。
  curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
  このコマンドは API への GET 要求を実行し、結果として成功コードを出力します。
  200
  次のように、よりシンプルな curl コマンドを実行して、サービスの /users エンドポイントから JSON オブジェクトの配列を返すこともできます。
  $ curl http://<your_external_ip>:80/users

ステップ 6: 基本認証ポリシーを使用して API を保護する

API Manager を使用して、基本認証ポリシーを API に追加します。

API Manager で、サイドナビゲーションパネルから [API Administration (API 管理)] を選択します。
「ステップ 5: シンプルな API をパブリッシュして Flex Gateway にデプロイする」で作成した API の名前 (my-api など) を見つけてクリックします。
使用する API の [Policies (ポリシー)] ページに移動します。
1. サイドナビゲーションパネルから [Policies (ポリシー)] を選択します。
2. [Policies (ポリシー)] ページで、[Add policy (ポリシーを追加)] をクリックします。
開いたページの [Security (セキュリティ)] で [Basic Authentication - Simple (基本認証 - シンプル)] という名前のポリシーを見つけます。

同様の名前の LDAP のポリシーを選択しないように注意してください。
[Next (次へ)] をクリックします。
基本認証ポリシーを設定します。
1. [User Name (ユーザー名)] に、実際のユーザー名ではなく「user」と入力します。
  
  項目に値が事前入力されている場合は、その値を保持することも、推奨値に変更することもできます。
2. [User Password (ユーザーパスワード)] に「pw」と入力します。
  
  項目に値が事前入力されている場合は、その値を保持することも、推奨値に変更することもできます。
3. [Apply (適用)] をクリックします。
API インスタンスをテストします。
1. kubectl を使用して、次のステップで使用できるように外部 IP アドレスを再度取得します。
  kubectl -n gateway get services
2. <your_external_ip> を前のステップで返された EXTERNAL-IP に置き換えて、次の curl コマンドを認証パラメーターなしで実行します。
  curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users'
  URI に認証パラメーターがないため、コマンドで 401 が返されます。
  401
3. <your_external_ip> を前のステップで返された EXTERNAL-IP に置き換えて、次の curl コマンドを認証パラメーター付きで実行します。
  curl -s -o /dev/null -w "%{http_code}\n" --request GET 'http://<your_external_ip>:80/users' -u user:pw
  このコマンドは、結果として成功を示す 200 状況コードを出力します。
  200
  user パラメーターと password パラメーター (user:pw) は、ポリシーの適用時に指定した値と一致する必要があります。正しい認証パラメーターを入力していないと、次のエラーが発生します。
  401
  エラーに対処するには、正しい認証パラメーターを使用してコマンドを実行するか、API ゲートウェイの API のポリシー設定ページに戻ってポリシー設定を編集し、curl コマンドを再実行します。
  
  ログイン情報を編集するページは、次のようになります。

トラブルシューティング

コマンドの実行時にエラーが発生した場合は、トラブルシューティング情報を確認してください。

Docker コマンドの問題 | Helm コマンドの問題

Docker コマンドの問題

docker コマンドで返されるエラーのトラブルシューティング

Docker デーモンエラー
Reg Facade エラー (400 Bad Request (400 不正な要求))

Docker デーモンエラー

Docker が開始されていない場合、docker コマンドで次のようなエラーメッセージが返されます。

Error response from daemon: Bad response from Docker engine

ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
       Is the docker daemon running?

このエラーが発生した場合、Docker を開始します。

Reg Facade エラー (400 Bad Request (400 不正な要求))

docker run を使用してゲートウェイを登録するときに、次のエラーが発生する可能性があります。

[flexctl][error] reg facade call returned error response:
HTTP/1.1 400 Bad Request

このエラーの理由は、エラーメッセージ内で確認できます。一般的な原因は次のとおりです。

an active target with the same name already exists in this organization and environment (同じ名前のアクティブな対象がすでにこの組織および環境に存在します)

この問題を回避するには、登録コマンドを実行するときにゲートウェイの一意の名前を指定します。その名前の前の登録が成功している場合でも、同じ名前を再利用することはできません。このエラーが発生すると、コマンドによって空の registration.yaml が生成されて、再登録できなくなります。そのため、ゲートウェイをクラスターにデプロイするときにこのファイルを使用しようとすると、エラーが発生します。
no valid registration token was found (有効な登録トークンがありませんでした)

この問題を回避するには、Kubernetes の [Add a Flex Gateway (Flex Gateway の追加)] ページを更新して、コマンドの新しいトークンを生成し、登録コマンドを再実行します。

Helm コマンドの問題

Kubernetes および OpenShift クラスターの helm コマンドで返されるエラーのトラブルシューティング

アップグレードに失敗する: 例外エラー
Kubernetes クラスターに到達できない
アップグレードに失敗する: タイムアウト
CRD をインストールできない

アップグレードに失敗する: 例外エラー

Flex Gateway のデプロイメント中に registration.yaml ファイルを Helm コマンドに渡すときにこのファイルが無効であると、次のエラーになります。

Error: UPGRADE FAILED: execution error at (flex-gateway/templates/deployment.yaml:4:10):
registerSecretName, registration.content or registration.secretName is required!

このエラーが発生した場合は、registration.yaml ファイルが空でないことを確認してください。ファイルが空である場合、新しい一意の名前でゲートウェイを登録して、新しい registration.yaml を生成し、登録ステップの手順を再実行します。登録コマンドの例については、「Flex Gateway を登録する」を参照してください。

アップグレードに失敗する: タイムアウト

問題によっては、次のタイムアウトエラーが発生する前に、(コマンドの --wait フラグが原因で) 最大 5 分間 Helm アップグレードコマンドがハングする可能性があります。

Error: UPGRADE FAILED: timed out waiting for the condition

通常、このエラーは、クラスター設定に誤りがあるか、クラスター設定ツールでこのプロセスがサポートされていないことを意味します。原因 1 つとして、LoadBalancer 種別の Service リソースの生成の失敗が考えられます。さらにトラブルシューティングするには、次のコマンドを実行します。

```
kubectl -n gateway describe deployment
```
```
kubectl -n gateway describe service
```

Kubernetes クラスターに到達できない

helm を使用して Flex Gateway をデプロイしようとしているときに Kubernetes クラスターが実行されていない場合、次のエラーが発生する可能性があります。

Error: Kubernetes cluster unreachable:
the server could not find the requested resource

クラスターを実行するサービスを開始します。

次のように、Kubernetes クラスターホストでクラスターが実行されていることを確認します。

kubectl cluster-info

クラスターが実行されている場合、コマンドで次のような結果が返されます。

Kubernetes control plane is running at https://34.30.50.119
GLBCDefaultBackend is running at https://34.30.50.119/api/v1/namespaces/kube-system/services/default-http-backend:http/proxy
KubeDNS is running at https://34.30.50.119/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://34.30.50.119/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

クラスターが設定されていない場合、コマンドで次のような結果が返される可能性があります。

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
error: the server doesn't have a resource type "services"

詳細は、「クラスターの要件」を参照してください。

CRD をインストールできない

必要なアクセス権がない場合、次のようなエラーが発生します。

Error: failed to install CRD crds/apiinstance.yaml:
customresourcedefinitions.apiextensions.k8s.io is forbidden:
User "user1" cannot create resource "customresourcedefinitions"
in API group "apiextensions.k8s.io" at the cluster scope