8.6. 3scale OpenAPI カスタムリソースのデプロイ


OpenAPI カスタムリソース (CR) は、開発者ポータルの ActiveDocs に使用できる OpenAPI Specification(OAS) ドキュメントをインポートする 1 つの方法です。OAS は、API に対して使用できるプログラミング言語が特定のものだけに限定されないようにする規格です。人間とコンピューターは、ソースコードのアクセス、ドキュメント、またはネットワークトラフィックの検査なしに API プロダクトの機能をより簡単に理解することができます。

前提条件

  • オンプレミス型 3scale 2.11 インスタンスの管理者権限を持つユーザーアカウント
  • API を定義する OAS ドキュメント
  • OpenAPI CR がテナントにリンクする方法に関する理解

8.6.1. シークレットから OAS ドキュメントをインポートする 3scale OpenAPI カスタムリソースのデプロイ

3scale バックエンド および プロダクト を作成できるように、OpenAPI カスタムリソース (CR) をデプロイします。

注記

Operator はシークレットのコンテンツのみを読み取ります。Operator はシークレットのフィールド名を読み取りません。

手順

  1. OAS ドキュメントが含まれるシークレットを定義します。たとえば、以下の内容で myoasdoc1.yaml を作成することができます。

    openapi: "3.0.2"
    info:
      title: "some title"
      description: "some description"
      version: "1.0.0"
    paths:
      /pet:
        get:
          operationId: "getPet"
          responses:
            405:
              description: "invalid input"
  2. シークレットを作成します。以下に例を示します。

    $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml
    
    secret/myoasdoc1 created
  3. OpenAPI CR を定義します。OAS ドキュメントが含まれるシークレットへの参照を指定するようにしてください。たとえば、myopenapicr1.yaml ファイルを作成することができます。

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      name: myopenapicr1
    spec:
      openapiRef:
        secretRef:
          name: myoasdoc1
  4. 定義したばかりのリソースを作成します。以下に例を示します。

    $ oc create -f myopenapicr1.yaml

    この例では、出力は以下のようになります。

    openapi.capabilities.3scale.net/myopenapicr1 created

8.6.2. 3scale OpenAPI カスタムリソース定義の機能

OpenAPI カスタムリソース定義 (CRD) のデプロイメント機能に関する知識は、3scale プロダクトの設定、バックエンド、およびその後の開発者ポータル用の ActiveDocs の作成に役立ちます。

  • OAS ドキュメントは、以下から読み込むことができます。

    • Kubernetes シークレット
    • http および https 形式の両方の URL
  • OAS ドキュメントでは、info.title 設定は 215 文字を超えることができません。Operator はこの設定を使用して、長さの制限がある OpenShift オブジェクト名を作成します。
  • サーバーリストの最初の servers[0].url 要素のみがプライベート URL として解析されます。OpenAPI Specification(OAS) は、servers[0].url 要素の basePath コンポーネントを使用します。
  • OpenAPI CRD は単一の最上位のセキュリティー要件をサポートしますが、運用レベルのセキュリティーはサポートしません。
  • OpenAPI CRD は apiKey セキュリティースキームをサポートします。

8.6.3. OpenAPI カスタムリソースを定義する際のインポートルール

インポートルールは、3scale デプロイメントの OpenAPI ドキュメントを設定する際に、OpenAPI Specification(OAS) が 3scale とどのように機能するかを指定します。

プロダクト名

デフォルトのプロダクトシステム名は、OpenAPI ドキュメントの info.title フィールドから取得されます。OpenAPI ドキュメントのプロダクト名を上書きするには、OpenAPI カスタムリソース (CR) の spec.productSystemName フィールドを指定します。

プライベートベース URL

プライベートベース URL は OpenAPI CR servers[0].url フィールドから読み込まれます。OpenAPI CR の spec.privateBaseURL フィールドを使用して、これを上書きできます。

3scale メソッド

インポートされた OpenAPI ドキュメントで定義される各操作は、プロダクトレベルで 1 つの 3scale メソッドに変換されます。メソッド名は、操作オブジェクトの operationId フィールドから読み取られます。

3scale のマッピングルール

インポートされた OpenAPI ドキュメントで定義される各操作は、プロダクトレベルで 1 つの 3scale マッピングルールに変換されます。以前の既存のマッピングルールは OpenAPI CR でインポートされたルールに置き換えられました。

OpenAPI ドキュメントでは、paths オブジェクトは動詞およびパターンプロパティーのマッピングルールを提供します。3scale メソッドは operationId に応じて関連付けられます。

delta の値は 1 にハードコーディングされます。

デフォルトでは、Strict マッチング ポリシーが設定されます。マッチングポリシーは、OpenAPI CRD の spec.PrefixMatching フィールドを使用して、接頭辞マッチング に切り替えることができます。

認証

1 つのトップレベルのセキュリティー要件のみがサポートされます。操作レベルのセキュリティー要件はサポートされていません。

サポートされるセキュリティースキームは apiKey です。

apiKey セキュリティースキームタイプ:

  • クレデンシャルの場所 は、セキュリティースキームオブジェクトの OpenAPI ドキュメント in フィールドから読み込まれます。
  • 認証ユーザー キーは、セキュリティースキームオブジェクトの OpenAPI ドキュメント name フィールドから読み込まれます。

以下は、apiKey セキュリティー要件のある OAS 3.0.2 の例の一部です。

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header

OpenAPI ドキュメントがセキュリティー要件を指定しない場合、以下が適用されます。

  • プロダクト認証が apiKey に設定されます。
  • クレデンシャルの場所 はデフォルトで 3scale の値 As query parameters (GET) or body parameters (POST/PUT/DELETE) に設定されます。
  • Auth ユーザー キーはデフォルトで 3scale の値 user_key に設定されます。

3scale 認証セキュリティー は、OpenAPI CRD の spec.privateAPIHostHeader フィールドおよび spec.privateAPISecretToken フィールドを使用して設定できます。

ActiveDocs

3scale ActiveDoc は作成されていません。

3scale プロダクトポリシーチェーン

3scale ポリシーチェーンは、3scale が作成するデフォルトのポリシーチェーンです。

3scale デプロイメントモード

デフォルトでは、設定した 3scale デプロイメントモードは APIcast 3scale により管理されます。しかし、spec.productionPublicBaseURL または spec.stagingPublicBaseURL、あるいは両方のフィールドが OpenAPI CR にある場合、プロダクトのデプロイメントモードは APIcast で自己管理されます。

カスタム公開ベース URL を持つ OpenAPI CR の例:

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"

8.6.4. URL から OAS ドキュメントをインポートする 3scale OpenAPI カスタムリソースのデプロイ

指定した URL から OAS ドキュメントをインポートする OpenAPI カスタムリソースをデプロイできます。その後、この OAS ドキュメントを、デベロッパーポータルで API の ActiveDocs の基礎として使用できます。

前提条件

  • 同じ namespace にある 3scale インスタンスのデフォルトのテナントにリンクしない OpenAPI カスタムリソースを作成する場合、OpenAPI CR が含まれる namespace には、OpenAPI CR がリンクするテナントを特定するシークレットが含まれます。シークレットの名前は以下のいずれかになります。

    • threescale-provider-account
    • ユーザー定義

    このシークレットには、3scale インスタンスの URL と、3scale インスタンスの 1 つのテナントにアクセスするためのクレデンシャルが含まれるトークンが含まれます。

手順

  1. OpenShift アカウントで、Operators > Installed operators に移動します。
  2. 3scale operator をクリックします。
  3. YAML タブを選択します。
  4. OpenAPI カスタムリソースを作成します。以下に例を示します。

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      name: openapi1
    spec:
      openapiRef:
        url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
      providerAccountRef:
        name: mytenant
  5. Save をクリックします。3scale operator が OpenAPI CR を作成するまでに数秒かかります。

検証

  1. OpenShift の 3scale Product Overview ページで、Synced 状態が True とマークされていることを確認します。
  2. 3scale アカウントに移動します。
  3. OAS ドキュメントが存在することを確認します。上記の例では、openapi1 という名前の新しい OAS ドキュメントが表示されます。

8.6.5. 関連情報

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.