API ゲートウェイ
API ゲートウェイ は、OpenLM Platform のインストールごとに 1 つ、同じ namespace に、OpenLM Platform 本体より先にインストールします。OpenLM の Web UI は https://<your address>/api/... からデータを取得します。API ゲートウェイはこれらのリクエストをすべて受け取り、それを処理する OpenLM Platform のサービスに転送します。
インストールの概要は次のとおりです。
- 内容: Tyk Gateway(オープンソース)をベースにした Helm チャート
openlm/openlm-apigatewayです。 - 用意するもの: Redis、ストレージクラス、シークレット。
- 実行するもの: 2 つの
kubectlコマンド、1 つの values ファイル、1 つのhelmコマンド。所要時間は約 10 分です。 - 確認すること: ゲートウェイの Pod が実行中であること、ジョブが
Bootstrap completed successfullyと出力すること、ルートが一覧表示されること。 - 固定のルール: Helm リリースの名前は常に
openlm-gatewayです。
仕組み
/api への各リクエストは、次の順に処理されます。
- Ingress(または OpenShift のルート)が、
/apiで始まるすべてのパスをゲートウェイに送ります。 - ゲートウェイがそのパスの ルート を検索します。各ルートは、
/api/licensesのような 1 つのパスを、openlm-licensesのような同じ namespace 内の 1 つの OpenLM Platform サービスに対応付けます。 - ゲートウェイはリクエストを転送し、応答を返します。ゲートウェイ自体はサインインを確認しません。確認するのは OpenLM Platform の各サービスです。
ルートはチャートに含まれています。インストールとアップグレードのたびに、短時間で終わる ブートストラップジョブ が、そのチャートバージョンのルートをゲートウェイに読み込みます。ゲートウェイはルートをボリュームに保持するため、再起動後も失われません。作業データは Redis に保持します。
運用担当者向けの詳細
ゲートウェイは次の要素で構成されます。
- ゲートウェイ: Tyk Gateway 5.9.1(オープンソース)、1 つの Deployment
gateway-openlm-gateway-tyk-gatewayです。トラフィックをポート 8080 で、コントロール API を別のポート 9699 で待ち受けます。コントロール API は専用のサービスを持ち、クラスターの外部には公開されません。 - ルート: キーレスの Tyk API 定義で、
listen_pathが/api/<service>、ターゲットがhttp://openlm-<service>/...の形式(短いサービス名)です。このため、ゲートウェイはプラットフォームと同じ namespace で実行する必要があります。 - ブートストラップジョブ:
gateway-bootstrapper-job-<revision>。コントロール API の/helloが正常を返すまで待ち、API 定義を すべて 削除してから、イメージに同梱された定義を作成し、ゲートウェイを再読み込みして、もう一度ヘルスチェックを行います。約 5 分間、最大 3 回まで再試行し、完了の 5 分後に自身を削除します。 - 状態: API 定義はボリューム
tyk-app-claim上のファイルです。ポリシーとミドルウェアはそれぞれ専用のボリュームを持ちます。各ボリュームは 200 MB、ReadWriteOnceで、アンインストールしても保持されます。Redis はゲートウェイの実行時データを保持します。 - シークレット:
APISecretがコントロール API を保護します。ゲートウェイとブートストラップジョブは、同じシークレットからこの値を読み込みます。
始める前に
次の前提条件を確認します。
- OpenLM Platform の namespace が存在すること。例では
openlmを使用します。ゲートウェイと OpenLM Platform が同じ namespace を共有していれば、名前は任意です。 - namespace から到達できる Redis があり、そのホスト、ポート、パスワード、TLS の使用有無がわかっていること。Redis を参照してください。
-
ReadWriteOnceボリュームを提供する ストレージクラス があること:kubectl get storageclass。 - Helm 3 または 4 と、namespace に対する
kubectl(またはoc)のアクセス権があること。 - お使いの環境で
/apiがどのようにゲートウェイに届くかを把握していること。通常は OpenLM Platform の Ingress か、OpenShift のルートが担います。/api を公開する を参照してください。
API ゲートウェイをインストールする
次の手順を順番に実行します。
1. OpenLM の Helm リポジトリを追加する
namespace を設定し、リポジトリを追加して、最新の API ゲートウェイリリースを一覧表示します。
export NS=openlm
helm repo add openlm https://openlm-helm.github.io/helmcharts
helm repo update openlm
helm search repo openlm/openlm-apigateway --devel
--devel が必要ですHelm は、--devel を付けない限り、1.0.0-rc.2 のようなプレリリースバージョンを無視します。このページのコマンドは --devel を使用するため、常に最新の API ゲートウェイリリース(すべての OpenLM Platform リリースに対応するリリース)をインストールします。
このマシンからインターネットにアクセスできない場合は、アクセスできるマシンで helm pull openlm/openlm-apigateway --devel を実行します。このコマンドは unable to find exact version requested; falling back to closest available version と表示することがありますが、問題ありません。.tgz ファイルをコピーし、以降の手順では openlm/openlm-apigateway の代わりにそのファイルを使用します。
2. シークレットを作成する
コントロール API 用と Redis パスワード用に、シークレットを 1 つずつ作成します。
kubectl -n "$NS" create secret generic openlm-gateway-secrets \
--from-literal=APISecret="$(openssl rand -hex 32)"
kubectl -n "$NS" create secret generic openlm-gateway-redis \
--from-literal=password='<your Redis password or access key>'
APISecret は、ゲートウェイのコントロール API を保護します。チャートには既定値がなく、指定しない場合はメッセージを表示して停止します。Redis にパスワードがない場合は、2 つ目のコマンドを省略し、次の手順で passSecret を指定しないでください。
3. values ファイルを作成する
OpenLM Platform の Ingress が /api をゲートウェイに送り、Redis が TLS を使用する標準構成の values ファイルを作成します。
# gateway-values.yaml
storageClassName: <your storage class>
tyk-oss:
global:
secrets:
useSecretName: openlm-gateway-secrets # the Secret from step 2
redis:
addrs: ["<redis host>:<port>"]
useSSL: true # false for a Redis without TLS
passSecret: { name: openlm-gateway-redis, keyName: password }
storage: { database: 0 }
tyk-gateway:
gateway:
hostName: <your address>
ingress: { enabled: false } # /api comes through the platform's Ingress
OpenShift では、/api を公開する の説明に従い、代わりにルートを追加します。
4. インストールする
チャートをインストールします。
helm upgrade --install openlm-gateway openlm/openlm-apigateway --devel \
-n "$NS" -f gateway-values.yaml --wait --timeout 10m
リリース名は必ず openlm-gateway にしてください。OpenLM Platform は /api をサービス gateway-svc-openlm-gateway-tyk-gateway に送り、この名前はリリース名から作られます。
5. 確認する
ゲートウェイの Pod とブートストラップジョブを確認します。
kubectl -n "$NS" get pods | grep -E "gateway"
kubectl -n "$NS" logs -l job-name --tail=200 | grep -E "Bootstrap completed|failed|Error"
出力には次の内容が表示されます。
- ゲートウェイの Pod
gateway-openlm-gateway-tyk-gateway-…が1/1でRunning。 - Pod
gateway-bootstrapper-job-…がCompletedで、ログにBootstrap completed successfullyの行がある。
ジョブは完了の 5 分後に自身を削除します。ルートはいつでも確認できます。ルートを確認する を参照してください。
ルートを確認する
インストールやアップグレードの後、または Web UI のページにデータが表示されない場合は、ルートを確認します。ゲートウェイがすべての OpenLM サービスについてルートを 1 つずつ一覧表示すれば、ルートは揃っています。
ルートを一覧表示するには、ゲートウェイのコントロール API へのトンネルを開いて問い合わせます。
# 1. Open a tunnel to the gateway's control API (leave it running, use a second terminal)
kubectl -n "$NS" port-forward svc/gateway-control-svc-openlm-gateway-tyk-gateway 9699:9699
# 2. Read the secret and ask the gateway
export TYK_SECRET="$(kubectl -n "$NS" get secret openlm-gateway-secrets -o jsonpath='{.data.APISecret}' | base64 -d)"
curl -s localhost:9699/hello # health: "status":"pass"
curl -s -H "x-tyk-authorization: $TYK_SECRET" localhost:9699/tyk/apis \
| jq -r '.[] | [.proxy.listen_path, .proxy.target_url] | @tsv' | sort
出力で次の点を確認します。
/helloが"status":"pass"を返し、Redis がpassであること。- 一覧にルートが 1 行ずつ、パス、サービスの順に表示されること。バージョン 1.0.0-rc.2 は 80 個のルートを読み込みます。失敗しているページが呼び出すパスが一覧にあることを確認してください。
- 一覧が空の場合やパスが欠けている場合は、ブートストラップジョブが完了していません。アップグレード のアップグレードコマンドを、同じバージョンで再実行します。実行のたびに新しいジョブが開始され、すべてのルートが読み込み直されます。
jq がない場合は、最後の行を省略し、出力から "listen_path" を検索します。
外部からの経路全体を確認するには、Web UI にサインインしていくつかのページを開きます。各ページは /api を通じてデータを読み込みます。
/api を公開する
/api をゲートウェイに送るには、次のいずれか 1 つの構成だけを使用します。
| 構成 | 使用する場面 | 設定する内容 |
|---|---|---|
| プラットフォームの Ingress(標準) | プラットフォームの単一の Ingress を使用する Kubernetes | tyk-oss.tyk-gateway.gateway.ingress.enabled: false。ほかの設定は不要です。プラットフォームの Ingress がすでに /api をゲートウェイに送ります。 |
| OpenShift のルート | OpenShift、ROSA、ARO | openShiftRoute.enabled: true、openShiftRoute.host: <your address>、Tyk の Ingress は無効 |
| ゲートウェイの Ingress | プラットフォームの Ingress を使用しないゲートウェイ | Tyk の Ingress を有効にし、ホスト、クラス、TLS シークレットを指定 |
チャートの既定値では、ゲートウェイはプレースホルダーのホスト gateway-domain.com 用の Ingress を作成します。この Ingress を使用しない場合は、tyk-oss.tyk-gateway.gateway.ingress.enabled: false を設定してください。
OpenShift のルート
ルートを作成するには、values ファイルに次の設定を追加します。
openShiftRoute:
enabled: true
host: <your address>
tyk-oss:
tyk-gateway:
gateway:
ingress: { enabled: false }
チャートは、リリースの namespace にルート openlm-gateway を作成します。パスは /api、TLS はルーターで終端(エッジ)、HTTP は HTTPS にリダイレクトされ、タイムアウトは 600 秒です。OpenLM Platform のルートと同じセキュリティヘッダーを設定します: HSTS(1 年、サブドメインを含む)、X-Frame-Options: SAMEORIGIN、X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin、Content-Security-Policy: frame-ancestors 'self'。これらのヘッダーには OpenShift 4.14 以降が必要です。それより古いバージョンでは、openShiftRoute.routeSecurity.enabled: false を設定します。
ルートを確認するには、oc -n "$NS" get route openlm-gateway を実行します。以前に /api のルートを手動で作成した場合は、削除してください。同じホストとパスにルートが 2 つあると、OpenShift は古いほうを使用します。
ゲートウェイの Ingress
ゲートウェイ自体の Ingress を有効にするには、ホスト、クラス、TLS シークレットを指定して次の設定を追加します。
tyk-oss:
tyk-gateway:
gateway:
hostName: <your address>
ingress:
enabled: true
className: <your ingress class>
hosts:
- host: <your address>
paths: [{ path: /api, pathType: ImplementationSpecific }]
tls:
- secretName: <your TLS secret>
hosts: [<your address>]
チャートは ingress-nginx 用のアノテーション(リクエスト本文 100 MB、タイムアウト 600 秒)を設定します。別のコントローラーを使用する場合は、annotations をそのコントローラーの同等の設定に置き換えてください。
Redis
お使いの Redis に合わせて、addrs、useSSL、storage.database を設定します。
| お使いの Redis | addrs | useSSL | storage.database |
|---|---|---|---|
| ネットワーク内、TLS なし | ["<host>:6379"] | false | 空いているデータベース(例: 2) |
| TLS あり | ["<host>:<TLS port>"] | true | 空いているデータベース |
| Azure Managed Redis | ["<name>.<region>.redis.azure.net:10000"] | true | 0 |
| Azure Cache for Redis | ["<name>.redis.cache.windows.net:6380"] | true | 空いているデータベース |
次の点に注意してください。
- Azure Managed Redis: 非クラスター ポリシーで作成します。データベースが 1 つしかないため、
storage.databaseは0です。 - ゲートウェイは OpenLM Platform と Redis を共有できます。Redis に複数のデータベースがある場合は、ゲートウェイ専用のデータベース番号を割り当ててください。
- Redis の証明書がプライベート CA から発行されている場合は、OpenLM サポートにお問い合わせください。テスト用のインストールに限り、
tyk-oss.global.redis.sslInsecureSkipVerify: trueで証明書の検証を省略できます。
設定リファレンス
次の設定を values ファイルで指定します。Tyk の設定はすべて tyk-oss: の下にあり、指定しない設定は既定値のままになります。
| 設定 | 既定値 | 内容 |
|---|---|---|
storageClassName | (なし、必須) | 3 つのボリュームのストレージクラス |
tyk-oss.global.secrets.useSecretName | (空) | キー APISecret を持つシークレットです。2 つのシークレット設定のどちらかが必須です。 |
tyk-oss.global.secrets.APISecret | (空) | useSecretName の代わりに平文で指定する方法 |
tyk-oss.global.redis.addrs | ["openlm-redis.openlm:6379"] | Redis の host:port |
tyk-oss.global.redis.useSSL | false | Redis への TLS 接続 |
tyk-oss.global.redis.passSecret.name, .keyName | (空) | Redis パスワードを格納したシークレットとキー |
tyk-oss.global.redis.storage.database | 2 | Redis のデータベース番号 |
tyk-oss.tyk-gateway.gateway.hostName | gateway-domain.com | お使いのアドレス |
tyk-oss.tyk-gateway.gateway.ingress.enabled | true | ゲートウェイ自体の Ingress |
tyk-oss.tyk-gateway.gateway.replicaCount | 1 | ゲートウェイの Pod 数です。2 つ以上にすると、アップグレード中のダウンタイムがなくなります。 |
tyk-oss.tyk-gateway.gateway.resources | (なし) | CPU とメモリーの要求と制限 |
tyk-oss.tyk-gateway.gateway.nodeSelector, .tolerations, .affinity | (なし) | ゲートウェイの Pod を実行する場所 |
tyk-oss.tyk-gateway.gateway.log.level | warn | debug、info、warn、error のいずれか |
tyk-oss.tyk-gateway.gateway.extraEnvs | 600 秒のタイムアウト | TYK_GW_* 変数として指定する追加の Tyk 設定です。リストを置き換えるとタイムアウトの設定が消えるため、タイムアウトもコピーして含めてください。 |
openShiftRoute.enabled | false | /api 用の OpenShift のルートを作成します |
openShiftRoute.host | (空) | お使いのアドレスです。ルートを有効にする場合は必須です。 |
openShiftRoute.name | openlm-gateway | ルートの名前です。既存のルートを引き継ぐ場合などに使用します。 |
openShiftRoute.routeSecurity.enabled | true | ルートに HSTS とセキュリティヘッダーを付けます |
openShiftRoute.routeSecurity.hstsMaxAge | 31536000 | HSTS の max-age(秒) |
openShiftRoute.routeSecurity.hstsIncludeSubDomains | true | HSTS の includeSubDomains |
bootstrapperJob.image | public.ecr.aws/r3q3q2f4/olm-gateway-bootstrapper:<version> | ルートを含むイメージです。チャートのバージョンごとに固定されています。 |
bootstrapperJob.affinity, .tolerations | (なし) | ジョブを実行する場所です。ジョブには nodeSelector の設定がないため、affinity を使用してください。 |
bootstrapperJob.argocd.enabled | false | Argo CD でチャートをデプロイする場合は true にします。ジョブが PostSync フックとして実行され、アプリケーションは同期状態を保ちます。 |
プライベートレジストリ(エアギャップ環境)
次のイメージをミラーし、チャートからそのコピーを参照するように設定します。
| イメージ | 設定 |
|---|---|
docker.tyk.io/tyk-gateway/tyk-gateway:v5.9.1 | tyk-oss.tyk-gateway.gateway.image.repository と .tag |
busybox:1.32 | tyk-oss.tyk-gateway.gateway.initContainers.setupDirectories.repository |
public.ecr.aws/r3q3q2f4/olm-gateway-bootstrapper:<version> | bootstrapperJob.image(完全な参照) |
ゲートウェイには tyk-oss.tyk-gateway.gateway.imagePullSecrets を設定します。ブートストラップジョブは namespace の default サービスアカウントで実行されるため、そのサービスアカウントにプルシークレットを追加してください。helm test は zalbiraw/alpine-curl-jq を使用しますが、これは helm test を実行する場合だけです。
アップグレード
まず、新しいバージョンの リリースノート を読みます。次に、リリースをアップグレードします。
helm -n "$NS" get values openlm-gateway > gateway-values.yaml # only if you no longer have the file
helm repo update openlm
helm upgrade openlm-gateway openlm/openlm-apigateway --devel \
-n "$NS" -f gateway-values.yaml --wait --timeout 10m
アップグレードのたびにブートストラップジョブが再実行され、すべてのルートが新しいバージョンのルートに置き換わります。アップグレード後に、ルートを確認 してください。
openlm-gateway 0.2.x からのアップグレード
0.2.x までは、チャートの名前は openlm-gateway で、ファイルとして提供されていました。新しいチャートで 同じリリース をアップグレードし、リリース名は openlm-gateway のままにしてください。
まず、お使いのインストールに独自のシークレットがあるかを確認します。
helm -n "$NS" get values openlm-gateway | grep -E "useSecretName|APISecret"
useSecretName、または自分で選んだAPISecretが表示される場合は、アップグレード のコマンドでアップグレードします。オブジェクトは変更されず、ゲートウェイも再起動しません。- 何も表示されない場合、または自分で選んでいない
APISecretが表示される場合は、独自のシークレットが必要です。インストールのステップ 2 のシークレットを作成し、values ファイルにuseSecretName: openlm-gateway-secretsを追加してから、アップグレードします。ゲートウェイが 1 回再起動するため、/apiは数秒間使用できなくなります。短いメンテナンス時間を計画し、古いシークレットでコントロール API を呼び出す独自のスクリプトがあれば更新してください。
アップグレードが "The gateway needs its own APISecret" で停止した場合、クラスターには何も変更されていません。シークレットを作成して、もう一度実行してください。
新しいチャートを新しいリリース名でインストールしないでください。サービス名の異なる 2 つ目のゲートウェイが作成され、/api は引き続き古いゲートウェイに送られます。
運用
シークレットのローテーション、ログの確認、ゲートウェイのアンインストールを行います。
シークレットをローテーションする
ゲートウェイは起動時に両方のシークレットを読み込むため、変更後に再起動します。
kubectl -n "$NS" create secret generic openlm-gateway-secrets \
--from-literal=APISecret="$(openssl rand -hex 32)" --dry-run=client -o yaml | kubectl -n "$NS" apply -f -
kubectl -n "$NS" rollout restart deployment gateway-openlm-gateway-tyk-gateway
Redis パスワードも、openlm-gateway-redis を使って同じ方法でローテーションします。Redis でパスワードを変更し、シークレットを更新して、再起動します。最初の手順から最後の手順までの間、ゲートウェイは Redis に接続できません。
ログを確認する
ゲートウェイのログを確認するには、kubectl -n "$NS" logs deploy/gateway-openlm-gateway-tyk-gateway を実行します。より詳しいログが必要な場合は、tyk-oss.tyk-gateway.gateway.log.level: debug を設定してアップグレードします。確認後は元に戻してください。
アンインストールする
リリースをアンインストールします。ボリュームは、あわせて削除したい場合にだけ削除します。
helm -n "$NS" uninstall openlm-gateway
kubectl -n "$NS" delete pvc tyk-app-claim tyk-policies-claim tyk-middleware-claim # only to remove the volumes as well
ボリュームと 2 つのシークレットは、削除しない限り残ります。
トラブルシューティング
ゲートウェイが動作しない場合は、表示されている内容をこの表で探します。
| 表示される内容 | 考えられる原因 | 対処方法 |
|---|---|---|
helm が The gateway needs its own APISecret で停止する | シークレットが設定されていない、または 0.2.x に同梱されていたシークレットを使用している | インストールのステップ 2 を実行し、useSecretName を設定します |
helm が Please define storageClassName to be used(1.0.0-rc.2 より前は Pelase define…)で停止する | storageClassName が指定されていない | kubectl get storageclass に表示されるいずれかを設定します |
Pod が Pending のまま、ボリュームも Pending | ストレージクラスが ReadWriteOnce ボリュームを提供できない | 別のストレージクラスを使用します |
ゲートウェイの Pod が再起動し、ログに redis が含まれる | ホスト、ポート、パスワード、または TLS の設定が誤っている | addrs、useSSL、シークレット openlm-gateway-redis を確認します。Azure: ポート 10000 または 6380、TLS を有効 |
ログまたはジョブに CROSSSLOT が含まれる | Azure Managed Redis がクラスターポリシーで作成されている | 非クラスターポリシーでキャッシュを作成し直します |
| 約 5 分後にブートストラップジョブが失敗する | ゲートウェイが正常でない(通常は Redis が原因) | 先にゲートウェイを修正し、アップグレードを再実行します |
Web UI は表示されるがページにデータがなく、/api/... が 404 を返す | ルートが読み込まれていない | ルートを確認 し、アップグレードを再実行します |
/api/<service> が 502 または 503 を返す | そのサービスが実行されていない、またはゲートウェイがプラットフォームと別の namespace にある | kubectl -n "$NS" get pods を実行し、ゲートウェイをプラットフォームの namespace にインストールします |
OpenShift: /api/... でホームページが表示される | /api のルートがない | openShiftRoute.enabled: true を設定するか、oc get route を確認します |
| アップグレード後にゲートウェイが 2 つある | 新しいチャートが新しいリリース名でインストールされた | 新しいリリースをアンインストールし、代わりに openlm-gateway をアップグレードします |
技術リファレンス
チャートが作成するオブジェクト
チャートは次のオブジェクトを作成します。
| 種類 | 名前 | 備考 |
|---|---|---|
| Deployment | gateway-openlm-gateway-tyk-gateway | Tyk Gateway 5.9.1。init コンテナ busybox がディレクトリを準備します。非 root で、読み取り専用のルートファイルシステムで実行されます。 |
| Service | gateway-svc-openlm-gateway-tyk-gateway | ポート 8080、トラフィック用です。プラットフォームの Ingress とルートはここを指します。 |
| Service | gateway-control-svc-openlm-gateway-tyk-gateway | ポート 9699、コントロール API 用です。クラスター内部のみ。 |
| Job | gateway-bootstrapper-job-<revision> | ルートを読み込みます。完了の 5 分後に削除されます。 |
| PersistentVolumeClaim | tyk-app-claim, tyk-policies-claim, tyk-middleware-claim | それぞれ 200 MB、ReadWriteOnce、アンインストール時も保持 |
| Secret | secrets-openlm-gateway-tyk-gateway | 平文で設定した値(APISecret、Redis パスワード)のためにチャートが作成します。useSecretName と passSecret を使用する場合は不要です。 |
| Secret | tyk-operator-conf | Tyk のツール用に作成される場合があります。useSecretName を使用する場合、シークレットの値は含まれません。 |
| Ingress | openlm-gateway-tyk-gateway | ingress.enabled: true の場合のみ |
| Route | openlm-gateway(または openShiftRoute.name) | openShiftRoute.enabled: true の場合のみ |
セキュリティに関する注意
次のセキュリティ上の点に注意してください。
- コントロール API(ポート 9699)はすべてのルートを変更できます。クラスター内部にとどめ、
gateway-control-svc-…には Ingress、ルート、LoadBalancerのいずれも作成しないでください。NetworkPolicy を使用する場合は、ポート 9699 へのアクセスをブートストラップジョブの Pod からだけに許可します。 APISecretはコントロール API の鍵です。values ファイルではなくシークレット(useSecretName)に保管し、運用 の手順でローテーションしてください。- ルートはキーレスです。ゲートウェイはサインインを確認せずにリクエストを転送し、各プラットフォームサービスがユーザーのトークンを自身で確認します。
- OpenShift では、ルートが HSTS と、/api を公開する に記載したセキュリティヘッダーを追加します。
ドキュメントチームは、大規模言語モデルを使ってこのページを下書きすることがあります。公開前に、テクニカルライターがすべてのページをレビューし、製品と照らし合わせて検証します。最終的な判断は人間が行います。