API 管理を楽にしよう！: Tanzu Application Platform が提供する API 自動登録機能とは

この記事では、VMware Tanzu Application Platform (以降TAP）が提供する API 自動登録機能について紹介します。
TAP は、開発者向けの TAP GUI という優れた統合 GUI ポータルを提供しており、API 管理も TAP GUI 経由で完結できるようになっています。TAP GUI の詳細については別のブログで紹介していますので参考ください。

まず、TAP 1.2 まではどのように TAP GUI 経由で API `を管理していたかをみてみましょう。

TAP GUI は API ドキュメントプラグイン経由でソフトウェア catalog のコンポーネントやシステムに接続可能な API のリストをスタンドアロンで提供しています。
各 API エンティティを TAP GUI に登録することで、その API を提供するコンポーネントと、その API を消費するコンポーネントのリストを TAP GUI から一元管理することが可能です。

現在、API ドキュメントプラグインは次の API 形式をサポートしています。

OpenAPI 2 & 3
AsyncAPI
GraphQL
Plain (他の形式をサポートするため)

具体例でみる API ドキュメントプラグイン経由での API 手動登録機能

上記の説明だけではイメージがつかないと思うので、具体的な手順を通じて TAP GUI に API エンティティを手動で登録してみたいと思います。

参考ドキュメントは下記となります。
https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.4/tap/tap-gui-plugins-api-docs-getting-started.html

(ちなみに、そもそも TAP をインストールできず本ブログで紹介する TAP API 関連の機能を含め試せない場合は、こちらのブログを参考に TAP をインストールしてみてください。)

TAP GUI に API エンティティを登録する Step は下記となります。

Step1. TAP GUI にアクセスし、Home -> REGISTER ENTITY をクリックします。

Step2. 下記の YAML ファイルを catalog-info.yaml として Github 上に保存します。
(こちらの Step は TAP GUI の操作ではなく、GitHub 上にファイルを保存する操作となりますので、具体的な GitHub 操作方法に関しては GitHub ドキュメントを参考ください)

catalog-info.yaml ファイルの中身は下記となります。

=========

apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: demo-domain
  description: Demo Domain for Tanzu Application Platform
  annotations:
    'backstage.io/techdocs-ref': dir:.
spec:
  owner: demo-team
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: demo-app-ms-1
  description: Demo Application's Microservice-1
  tags:
    - microservice
  annotations:
    'backstage.io/kubernetes-label-selector': 'app.kubernetes.io/part-of=demo-app-ms-1'
    'backstage.io/techdocs-ref': dir:.
spec:
  type: service
  providesApis:
   - demo-api
  lifecycle: alpha
  owner: demo-team
  system: demo-app
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: demo-app-ms-2
  description: Demo Application's Microservice-2
  tags:
    - microservice
  annotations:
    'backstage.io/kubernetes-label-selector': 'app.kubernetes.io/part-of=demo-app-ms-2'
    'backstage.io/techdocs-ref': dir:.
spec:
  type: service
  consumesApis:
   - demo-api
  lifecycle: alpha
  owner: demo-team
  system: demo-app
---

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: demo-app
  description: Demo Application for Tanzu Application Platform
  annotations:
    'backstage.io/techdocs-ref': dir:.
spec:
  owner: demo-team
  domain: demo-domain

---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: demo-api
  description: The demo API for Tanzu Application Platform GUI
  links:
    - url: https://api.agify.io
      title: API Definition
      icon: docs
spec:
  type: openapi
  lifecycle: experimental
  owner: demo-team
  system: demo-app # Or specify system name of your choice
  definition: |
    openapi: 3.0.1
    info:
      title: Demo API
      description: defaultDescription
      version: '0.1'
    servers:
      - url: https://api.agify.io
    paths:
      /:
        get:
          description: Auto generated using Swagger Inspector
          parameters:
            - name: name
              in: query
              schema:
                type: string
              example: type_any_name
          responses:
            '200':
              description: Auto generated using Swagger Inspector
              content:
                application/json; charset=utf-8:
                  schema:
                    type: string
                  examples: {}

=========

非常に長い YAML ファイルとなりますが、内容を簡単に説明しますと、demo-domain というドメインと demo-app というシステムが含まれています。
demo-app のシステムに更に 2 つのマイクロサービス（demo-app-ms-1とdemo-app-ms-1）があり、demo-app-ms-1 が demo-api という API を提供し、demo-app-ms-2 が demo-api を消費するような定義ファイルになっています。
このような依存関係は YAML 定義ファイルの spec.providesApis と spec.consumesApis で定義されています。

今回の手順では https://github.com/gordon-jin/hello-world 上に Step2 の catalog-info.yaml ファイルをアップロードしています。Step3. TAP GUI に戻って「Select URL」に「Step2」で保存した GitHub 上の catalog-info.yaml の URL をコピペします。

今回の手順では https://github.com/gordon-jin/hello-world/blob/master/catalog-info.yaml を「Select URL」にコピペしています。

Step4. Import ボタンをクリックします。

Step5. TAP GUI の Home 画面に戻り、２つの Catalog Entity( demo-app-ms-1 と demo-app-ms-1 ) が登録されているのを確認します。

これで手動での API 登録は完了です。

では、登録されている API の中身をみてみましょう。

TAP GUI の左側パネルの APIs をクリックすると右側に demo-api という API が登録されているのを確認できます。

demo-api をクリックすると、この API の OWNER、SYSTEM、LIFECYCLE などの情報と、一番下にこの API を提供しているコンポーネントと消費しているコンポーネントを確認できます。

また、View graph をクリックすることで graph 経由で API システム構成、API 提供元、API 消費者などを確認できます。

今度は Definition をクリックし、該当 API の仕様書を確認します。

次は、上記の「Example : type_any_name」を「Example : tanzu」に仕様書を変更したいと思います。

demo-api の Overview に戻って、Edit アイコンをクリックします。

GitHub の catalog-info.yaml の編集画面に遷移しますが、ここで「example: type_any_name」を「example: tanzu」に変更し、GitHub を Commit します。

GitHub を更新後、TAP GUI の catalog 上にも反映されているのを確認します。
(TAP GUI の更新には 200 秒かかります)

「example: tanzu」に更新されているのを確認できます。

ここまで API 手動登録機能について紹介しました。

多少長い YAML ファイルを OpenAPI Specification に従って作成して登録する必要がありますが、API エンティティを catalog として TAP GUI に登録することで TAP GUI から API の一元管理が可能です。
また、YAML ファイルを GitHub 上に保存することで、簡単にバージョン管理もできます。

ただ、このような YAML ファイルは API アプリ作成するたびに手動で作って登録する必要があるため、開発者にとっては面倒な作業となります。

この面倒な作業を劇的に改善するのが TAP 1.3 から提供している API 自動登録機能です。

API 自動登録機能とは

API 自動登録機能とは、アプリの Workload の構成で定義された API 仕様を TAP GUI に自動的に登録する機能です。
API 仕様書は、手動での API 登録のように個別の YAML ファイルを用意する必要はなく、TAP 上に API を提供するアプリの Workload をデプロイするだけで、TAP GUI 上に自動的に登録されるようになるのです。

具体例でみる API 自動登録機能

では、TAP 上に実際の RESTful Web Service をベースとした Spring boot アプリの Workload をデプロイし、関連 API が自動的に TAP GUI 上に登録されることを具体的なイメージを通じてみていきましょう。

今回は、下記の公式ドキュメントにある Spring Boot example app を使います。
https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.4/tap/api-auto-registration-usage.html

Using a Spring Boot app with a REST service
You can use a Spring Boot example app built using Building a RESTful Web Service guide. and has the Springdoc dependency.

下記の tanzu cli コマンドを使って rest-service `アプリの Workload を TAP 上にデプロイします。

tanzu apps workload apply rest-service \
--app rest-service \
--git-repo https://github.com/gordon-jin/rest-service \
--git-branch main \
--type web \
--label apis.apps.tanzu.vmware.com/register-api=true \
--param-yaml api_descriptor='{"description":"simple rest api.","location":{"path":"/v3/api-docs"},"owner":"demo","system":"dev","type":"openapi"}' \
--annotation autoscaling.knative.dev/minScale=1 \
-n demo \
-y

従来のアプリの Workload をデプロイする時と違う点としては、
–label apis.apps.tanzu.vmware.com/register-api=true と
–param-yaml api_descriptor の部分が追加されています。
–param-yaml api_descriptor にパラメータとして API の Owner、system などの情報を記入しています。

しばらく経つと、TAP GUI と Tanzu CLI から rest-service アプリの Workload が正常にデプロイされているのを確認できます。

それぞれの確認方法は下記となります。

TAP GUI 経由での確認：

TAP GUI -> Supply Chains で rest-service アプリの Workload のStatus が Healthy になっているのを確認します。

Tanzu CLI 経由での確認：

下記の Tanzu CLI コマンドを使って rest-service アプリの Workload の Status が Ready になっているのを確認します。

$ tanzu apps wld get rest-service -n demo
? Overview
name: rest-service
type: web

? Source
type: git
url: https://github.com/gordon-jin/rest-service
branch: main

? Supply Chain
name: source-to-url

RESOURCE READY HEALTHY TIME OUTPUT
source-provider True True 45m GitRepository/rest-service
image-provider True True 43m Image/rest-service
config-provider True True 43m PodIntent/rest-service
app-config True True 43m ConfigMap/rest-service
service-bindings True True 43m ConfigMap/rest-service-with-claims
api-descriptors True True 43m ConfigMap/rest-service-with-api-descriptors
config-writer True True 42m Runnable/rest-service-config-writer

? Delivery
name: delivery-basic

RESOURCE READY HEALTHY TIME OUTPUT
source-provider True True 41m ImageRepository/rest-service-delivery
deployer True True 41m App/rest-service

? Messages
No messages found.

? Pods
NAME READY STATUS RESTARTS AGE
rest-service-00001-deployment-54f4cd64bf-nlbtp 2/2 Running 0 41m
rest-service-build-1-build-pod 0/1 Completed 0 45m
rest-service-config-writer-6ckz8-pod 0/1 Completed 0 42m

? Knative Services
NAME READY URL
rest-service Ready https://rest-service.demo.172.17.203.60.sslip.io

To see logs: "tanzu apps workload tail rest-service --namespace demo"

次に、 rest-service アプリの関連 API が自動的に登録されているかを確認します。
TAP GUI -> APIs をクリックすると、demo/rest-service-172.17.203.60.sslip.io として登録されているのを確認できます。

demo/rest-service-172.17.203.60.sslip.io をクリックすると、Overview のところから該当 API の OWNER、SYSTEM、TYPE、LIFECYCLE の情報を確認できます。
こちらの情報は rest-service アプリの Workload をデプロイ時使っていた –param-yaml で設定した値になります。

今度は上記画面の Definition をクリックし、API 仕様書を確認します。

この画面から API の実行も可能です。

GET / greeting を展開し、[TRY IT OUT] ボタンをクリックします。

name の値は Tanzu にし、EXECUTE ボタンをクリックします。

実行結果は下記となります。

API 自動登録機能の仕組み

では、API 自動登録機能の仕組みについて少し説明します。

TAP GUI 上で API を自動登録するには、下記の要件を満たす必要があります。

1. TAP 上にデプロイするアプリは API を公開するアプリであること

サンプルアプリの作成については下記ドキュメントの「Building a RESTful Web Service guide」を参考ください。

https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.4/tap/api-auto-registration-usage.html

Using a Spring Boot app with a REST service
You can use a Spring Boot example app built using Building a RESTful Web Service guide. and has the Springdoc dependency.

2. TAP 上に API Auto Registration package がインストールされていること
(今回は TAP full profile を使っており、API Auto Registration package はデフォルトで入っています)

API Auto Registration package を個別にインストールする場合は、下記のドキュメントを参考ください。

https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/1.4/tap/api-auto-registration-installation.html

API Auto Registration package をインストールすると、api-auto-registration という Namespace に api-auto-registration-controller という名前の Pod が起動されます。

$ kubectl get pods -n api-auto-registration
NAME READY STATUS RESTARTS AGE
api-auto-registration-controller-56df54dfc6-kptnw 1/1 Running 8 (97m ago) 14d

API 自動登録のアーキテクチャ

TAP 上に API を公開するアプリの Workload をデプロイすると、上記の図にある Run cluster 中の APIDescriptor が TAP の Supplychain の中で生成され、api-auto-registration-controller はそれを検知して TAP GUI 上に API を登録する仕組みになっています

API 自動登録の流れ

rest-service アプリの Workload をデプロイ中に生成された apidescriptor は下記のコマンドで確認できます。

$ kubectl get apidescriptors -n demo
NAME STATUS
rest-service Ready
sample-api-descriptor-with-absolute-url Ready

もし、アプリのソースコード上 API を公開するように書いていない、かつ、Workload のデプロイのパラメータとして
–label apis.apps.tanzu.vmware.com/register-api=true と
–param-yaml api_descriptor
を追加している場合は、APIDescriptor は生成できず Workload はデプロイ中にエラーとなります。

なお、今回の手順ではアプリの Workload をデプロイ時、つまり、TAP の Supplychain の過程で apidescriptor が生成され、TAP GUI 上に自動登録されていますが、TAP 上にアプリの Workload をデプロイせず、個別に apidescriptor だけを作成して TAP GUI 上に登録してみるのも可能です。
(何らかの理由で API が TAP GUI 上にうまく自動登録できない場合、トラブルシューティングの一つの方法として仮の apidescriptor を登録してみるとよいです。)

例として、下記のコマンドを実行すると、sample-api-descriptor-with-absolute-url という apidescriptor が生成され、TAP GUI 上に登録されます。

kubectl apply -f - <<EOF
apiVersion: apis.apps.tanzu.vmware.com/v1alpha1
kind: APIDescriptor
metadata:
  name: sample-api-descriptor-with-absolute-url
  namespace: demo
spec:
  type: openapi
  description: A sample APIDescriptor to validate package installation successful
  system: test-installation
  owner: test-installation
  location:
    path: "/api/v3/openapi.json"
    baseURL:
      url: https://petstore3.swagger.io
EOF

$ kubectl get apidescriptor -n demo
NAME STATUS
rest-service Ready
sample-api-descriptor-with-absolute-url Ready

TAP GUI -> APIs 経由で demo/sample-api-descriptor-with-absolute-url-172.17.203.60.sslip.io という名前の API が登録されているのを確認できます。

いかがでしょうか？
TAP では YAML ファイルをベースとした API 手動登録機能のほか、TAP 1.3 からは API 自動登録機能も提供しており、TAP 上に API を公開するアプリの Workload をデプロイするだけで API 情報は TAP GUI 上に自動登録され、API 管理はかなり楽になります。

まとめ

ここまで TAP 1.3 から提供している API の自動登録機能について紹介しました。
開発者は API の自動登録機能を利用することで、簡単に API を登録、管理することが可能です。

VMware ブログでは、引き続き TAP の新機能を続々と紹介させていただきます。

具体例でみる API ドキュメントプラグイン経由での API 手動登録機能

API 自動登録機能とは

具体例でみる API 自動登録機能

API 自動登録機能の仕組み

まとめ

関連記事

Tanzu Application Platform でサーバレスとコンテナを和解？Vol2: Cloud Native Runtimes

Tanzu Application Platform 1.4 リリース ー 開発者のトイルを軽減し、運用とセキュリティを強化

Tanzu Application Platform でサーバレスとコンテナを和解？Vol1: Function Buildpacks

Tanzu Application Platform 1.4 リリースー開発者のトイルを軽減し、運用とセキュリティを強化