8.7. 3scale ActiveDoc カスタムリソースのデプロイ
Red Hat 3scale API Management ActiveDocs は、OpenAPI Specification に準拠する RESTful Web サービスを定義する API 定義ドキュメントをベースとしています。ActiveDoc カスタムリソース (CR) は、開発者ポータルの ActiveDocs に使用できる OpenAPI Specification(OAS) ドキュメントをインポートする 1 つの方法です。OAS は、API に対して使用できるプログラミング言語が特定のものだけに限定されないようにする規格です。人間とコンピューターは、ソースコードのアクセス、ドキュメント、またはネットワークトラフィックの検査なしに API プロダクトの機能をより簡単に理解することができます。
前提条件
- オンプレミス型 3scale 2.11 インスタンスの管理者権限を持つユーザーアカウント
- API を定義する OAS ドキュメント
-
ActiveDocCR がテナントにリンクする方法を理解している。
8.7.1. シークレットから OAS ドキュメントをインポートする 3scale ActiveDoc カスタムリソースのデプロイ
3scale バックエンド および プロダクト を作成できるように、ActiveDoc カスタムリソース (CR) をデプロイします。
Operator はシークレットのコンテンツのみを読み取ります。Operator はシークレットのフィールド名を読み取りません。たとえば、データは key: value のペアで設定され、value はファイルの内容を表し、key はファイル名になります。ファイル名は、ActiveDoc CRD のこのコンテキストで Operator によって無視されます。Operator はファイルの内容のみを読み取ります。
前提条件
- 3scale Operator がカスタムリソースのリンク先となるテナントを識別する方法 を理解している。
OAS(OpenAPI Specification) ドキュメントが含まれるシークレットを定義します。たとえば、以下の内容で
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"
手順
シークレットを作成します。以下に例を示します。
$ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
ActiveDocCR を定義します。OAS ドキュメントが含まれるシークレットへの参照を指定するようにしてください。たとえば、myactivedoccr1.yamlファイルを作成できます。apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: name: "Operated ActiveDoc From secret" activeDocOpenAPIRef: secretRef: name: myoasdoc1定義したばかりのリソースを作成します。以下に例を示します。
$ oc create -f myactivedoccr1.yaml
この例では、出力は以下のようになります。
activedoc.capabilities.3scale.net/myactivedoccr1 created
検証
- Red Hat OpenShift Container Platform (OCP) 管理者アカウントにログインします。
- Operators > Installed Operators に移動します。
- Red Hat Integration - 3scale をクリックします。
- Active Doc タブをクリックします。
-
OAS ドキュメントが存在することを確認します。上記の例では、
myactivedoccr1という名前の新しい OAS ドキュメントが表示されます。
8.7.2. 3scale ActiveDoc カスタムリソース定義の機能
ActiveDoc カスタムリソース定義 (CRD) は、開発者の OpenAPI ドキュメント形式の製品ドキュメントを考慮します。ActiveDoc CRD デプロイメント機能に関する知識は、デベロッパーポータルの ActiveDocs の作成に役立ちます。
ActiveDocCR は、以下のいずれかから OpenAPI ドキュメントを読み取りできます・- Secret
-
httpまたはhttps形式の URL
-
オプションで、
productSystemNameフィールドを使用して、ActiveDocCR を 3scale 製品にリンクできます。値は、3scale プ製品の CR のsystem_nameである必要があります。 -
publishedフィールドを使用して、3scale のActiveDocドキュメントを公開または非表示にすることができます。デフォルトでは、これはhiddenに設定されています。 -
skipSwaggerValidationsフィールドを使用して、OpenAPI 3.0 検証を省略できます。デフォルトでは、ActiveDocCR は検証されます。
8.7.3. シークレットから OAS ドキュメントをインポートする 3scale OpenAPI カスタムリソースのデプロイ
指定した URL から OAS(OpenAPI Specification) ドキュメントをインポートする ActiveDoc カスタムリソース (CR) をデプロイできます。その後、この OAS ドキュメントを、デベロッパーポータルで API の ActiveDocs の基礎として使用できます。
前提条件
手順
- OpenShift アカウントで、Operators > Installed operators に移動します。
- 3scale operator をクリックします。
- Active Doc タブをクリックします。
ActiveDocCR を作成します。以下に例を示します。apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" providerAccountRef: name: mytenantオプション。Self-managed APIcast の場合、
ActiveDocCR でproductionPublicBaseURLおよびstagingPublicBaseURLフィールドをデプロイメントの URL に設定します。以下に例を示します。apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 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"-
Save をクリックします。3scale operator が
ActiveDocCR を作成するまでに数秒かかります。
検証
- Red Hat OpenShift Container Platform (OCP) 管理者アカウントにログインします。
- Operators > Installed Operators に移動します。
- Red Hat Integration 3scale をクリックします。
- Active Doc タブをクリックします。
-
OAS ドキュメントが存在することを確認します。上記の例では、
myactivedoccr1という名前の新しい OAS ドキュメントが表示されます。
