メインコンテンツまでスキップ

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 への各リクエストは、次の順に処理されます。

  1. Ingress(または OpenShift のルート)が、/api で始まるすべてのパスをゲートウェイに送ります。
  2. ゲートウェイがそのパスの ルート を検索します。各ルートは、/api/licenses のような 1 つのパスを、openlm-licenses のような同じ namespace 内の 1 つの OpenLM Platform サービスに対応付けます。
  3. ゲートウェイはリクエストを転送し、応答を返します。ゲートウェイ自体はサインインを確認しません。確認するのは 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 を使用する Kubernetestyk-oss.tyk-gateway.gateway.ingress.enabled: false。ほかの設定は不要です。プラットフォームの Ingress がすでに /api をゲートウェイに送ります。
OpenShift のルートOpenShift、ROSA、AROopenShiftRoute.enabled: true、openShiftRoute.host: <your address>、Tyk の Ingress は無効
ゲートウェイの Ingressプラットフォームの Ingress を使用しないゲートウェイTyk の Ingress を有効にし、ホスト、クラス、TLS シークレットを指定
ゲートウェイ自体の Ingress は既定で有効です

チャートの既定値では、ゲートウェイはプレースホルダーのホスト 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 を設定します。

お使いの RedisaddrsuseSSLstorage.database
ネットワーク内、TLS なし["<host>:6379"]false空いているデータベース(例: 2)
TLS あり["<host>:<TLS port>"]true空いているデータベース
Azure Managed Redis["<name>.<region>.redis.azure.net:10000"]true0
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.useSSLfalseRedis への TLS 接続
tyk-oss.global.redis.passSecret.name, .keyName(空)Redis パスワードを格納したシークレットとキー
tyk-oss.global.redis.storage.database2Redis のデータベース番号
tyk-oss.tyk-gateway.gateway.hostNamegateway-domain.comお使いのアドレス
tyk-oss.tyk-gateway.gateway.ingress.enabledtrueゲートウェイ自体の Ingress
tyk-oss.tyk-gateway.gateway.replicaCount1ゲートウェイの Pod 数です。2 つ以上にすると、アップグレード中のダウンタイムがなくなります。
tyk-oss.tyk-gateway.gateway.resources(なし)CPU とメモリーの要求と制限
tyk-oss.tyk-gateway.gateway.nodeSelector, .tolerations, .affinity(なし)ゲートウェイの Pod を実行する場所
tyk-oss.tyk-gateway.gateway.log.levelwarndebug、info、warn、error のいずれか
tyk-oss.tyk-gateway.gateway.extraEnvs600 秒のタイムアウトTYK_GW_* 変数として指定する追加の Tyk 設定です。リストを置き換えるとタイムアウトの設定が消えるため、タイムアウトもコピーして含めてください。
openShiftRoute.enabledfalse/api 用の OpenShift のルートを作成します
openShiftRoute.host(空)お使いのアドレスです。ルートを有効にする場合は必須です。
openShiftRoute.nameopenlm-gatewayルートの名前です。既存のルートを引き継ぐ場合などに使用します。
openShiftRoute.routeSecurity.enabledtrueルートに HSTS とセキュリティヘッダーを付けます
openShiftRoute.routeSecurity.hstsMaxAge31536000HSTS の max-age(秒)
openShiftRoute.routeSecurity.hstsIncludeSubDomainstrueHSTS の includeSubDomains
bootstrapperJob.imagepublic.ecr.aws/r3q3q2f4/olm-gateway-bootstrapper:<version>ルートを含むイメージです。チャートのバージョンごとに固定されています。
bootstrapperJob.affinity, .tolerations(なし)ジョブを実行する場所です。ジョブには nodeSelector の設定がないため、affinity を使用してください。
bootstrapperJob.argocd.enabledfalseArgo CD でチャートをデプロイする場合は true にします。ジョブが PostSync フックとして実行され、アプリケーションは同期状態を保ちます。
プライベートレジストリ(エアギャップ環境)

次のイメージをミラーし、チャートからそのコピーを参照するように設定します。

イメージ設定
docker.tyk.io/tyk-gateway/tyk-gateway:v5.9.1tyk-oss.tyk-gateway.gateway.image.repository と .tag
busybox:1.32tyk-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 をアップグレードします

技術リファレンス​

チャートが作成するオブジェクト

チャートは次のオブジェクトを作成します。

種類名前備考
Deploymentgateway-openlm-gateway-tyk-gatewayTyk Gateway 5.9.1。init コンテナ busybox がディレクトリを準備します。非 root で、読み取り専用のルートファイルシステムで実行されます。
Servicegateway-svc-openlm-gateway-tyk-gatewayポート 8080、トラフィック用です。プラットフォームの Ingress とルートはここを指します。
Servicegateway-control-svc-openlm-gateway-tyk-gatewayポート 9699、コントロール API 用です。クラスター内部のみ。
Jobgateway-bootstrapper-job-<revision>ルートを読み込みます。完了の 5 分後に削除されます。
PersistentVolumeClaimtyk-app-claim, tyk-policies-claim, tyk-middleware-claimそれぞれ 200 MB、ReadWriteOnce、アンインストール時も保持
Secretsecrets-openlm-gateway-tyk-gateway平文で設定した値(APISecret、Redis パスワード)のためにチャートが作成します。useSecretName と passSecret を使用する場合は不要です。
Secrettyk-operator-confTyk のツール用に作成される場合があります。useSecretName を使用する場合、シークレットの値は含まれません。
Ingressopenlm-gateway-tyk-gatewayingress.enabled: true の場合のみ
Routeopenlm-gateway(または openShiftRoute.name)openShiftRoute.enabled: true の場合のみ
セキュリティに関する注意

次のセキュリティ上の点に注意してください。

  • コントロール API(ポート 9699)はすべてのルートを変更できます。クラスター内部にとどめ、gateway-control-svc-… には Ingress、ルート、LoadBalancer のいずれも作成しないでください。NetworkPolicy を使用する場合は、ポート 9699 へのアクセスをブートストラップジョブの Pod からだけに許可します。
  • APISecret はコントロール API の鍵です。values ファイルではなくシークレット(useSecretName)に保管し、運用 の手順でローテーションしてください。
  • ルートはキーレスです。ゲートウェイはサインインを確認せずにリクエストを転送し、各プラットフォームサービスがユーザーのトークンを自身で確認します。
  • OpenShift では、ルートが HSTS と、/api を公開する に記載したセキュリティヘッダーを追加します。

ドキュメントチームは、大規模言語モデルを使ってこのページを下書きすることがあります。公開前に、テクニカルライターがすべてのページをレビューし、製品と照らし合わせて検証します。最終的な判断は人間が行います。