Code Engine を使用したテキスト分析

フロントエンド・アプリケーションをデプロイする

1. 新しい Code Engine アプリケーションをデプロイするには、以下のコマンドを実行します。サービス名 frontend と、事前作成されたコンテナー・イメージを --image フラグのパラメーターとして指定します。

   ibmcloud code-engine application create --name frontend --image icr.io/solution-tutorials/tutorial-text-analysis-code-engine-frontend
   

   このコマンドを実行すると、アプリケーションの URL を含む出力が表示されます。 https://frontend.305atabsd0w.us-south.codeengine.appdomain.cloud のようになります。 次のステップに進むために、このURL をコピーするか、メモしてください。 この2つのデータ（アプリケーション名と画像名）だけで Code Engineはお客様のアプリケーションをデプロイし、設定や管理の複雑な作業を代行します。

   コンテナイメージの作成に使用したアプリケーションのソースコードは GitHubで公開されていますので、ご参考ください。 ソース・コードからコンテナー・イメージをビルドして、そのイメージをプライベート Container Registry にプッシュする場合は、 ここにある説明に従ってください。

2. 前のステップで作成したURL をブラウザで開くと、以下のような出力が表示されます

   

   ibmcloud code-engine application get -n frontend コマンドを実行して、アプリケーションの詳細を表示します。 ID、プロジェクト情報、アプリケーションの経過時間、アプリケーションにアクセスするための URL、アプリケーション構成にアクセスするためのコンソール URL、イメージ、リソース割り当て、アプリケーションのさまざまなリビジョン、条件、ランタイムなどの詳細が表示されます。 リビジョンは 1 つしかないため、トラフィックの 100% が最新のリビジョンにアクセスしていることがわかります。 インスタンスの数とその状況を確認することもできます。

3. トラブルシューティングや アプリケーションのログの確認 には、 <INSTANCE_NAME> を ibmcloud code-engine application get -n frontend コマンドのインスタンス名に置き換えて、以下のコマンドを実行してください。

   実行中のインスタンスが表示されない場合は、手順2からURL を開くことを確認してください。

   ibmcloud code-engine application logs --instance <INSTANCE_NAME>
   

   アプリケーションが実行中の場合は、backend URL: undefined と、アプリがポート 8080 で listen していることが表示されます。 後でこのチュートリアルの中で、このフロントエンド・アプリケーションをバックエンド・アプリケーションに接続します。

おめでとうございます!! 単純なコマンドを使用して Web アプリケーションを Code Engine にデプロイしました。ポッド、デプロイメント、サービス、Ingress といった Kubernetes の複雑な部分の知識も不要でした。

アプリケーションをスケーリングする

application create コマンドを使用してアプリケーションを作成した際、使用するイメージとアプリケーションの名前を渡しただけで完了しました。 これはアプリケーションを展開する上で必要最低限の情報ですが、 他にも制御できる設定項目が多数 あります。 例えば、インスタンスごとに同時に処理できる要求の数、アプリケーションのインスタンスに設定する CPU の量、アプリケーションのインスタンスに設定するメモリーの量、アプリケーションの環境変数、アプリケーションで使用できるインスタンスの最大数と最小数、およびアプリケーションが要求を listen するポートなどを設定できます。

これらの値の多くにはデフォルト設定があり、アプリケーションの作成時にオプションとして何も指定されていない場合にそれらが使用されます。 ここでは値を指定していなかったので、Code Engine はデフォルトの最大スケールである 10 が指定された状態でアプリケーションをデプロイしました。したがって、アプリケーションは最大で 10 個のインスタンスまでしかスケーリングできません。 デフォルトの最小スケールはゼロなので、アプリケーションが使用されなくなったときにはゼロに縮小されます。

1. Code Engineのオートスケーリング機能を調べるには、負荷ジェネレータを使用して、当社のサービスに対してリクエストを実行します。 以下のシェル・スクリプトは、3000 要求の基本ロードをシミュレートします。

   1. ローカル端末ウィンドウ (シェル) を開きます。

   2. 上記の手順で作成したフロントエンドURL 用のシェル変数を作成します。

      export APPURL=<frontend-application-url>
      

   3. 以下のスクリプトを実行して、何らかの負荷を生成します。 これを繰り返して、より多くのトラフィックを作成することができます。

      seq 1 3000 | xargs -n1 -P300  curl -s  $APPURL -o /dev/null
      

2. 前のセクションの Cloud Shell セッションで、以下のコマンドを実行して、自動スケーリングの一部として増加しているインスタンス (ポッド) カウントを確認します。

   ibmcloud code-engine application get -n frontend
   

   デフォルトでは、インスタンスごとに同時に処理できる要求の最大数は 10 で、自動スケーリングが行われますが、この値は --concurrency or -cn コマンドに application update フラグを指定して実行することで変更できます。

3. 10 個ものインスタンスの作成を許可したくない場合は、より小さい数に最大スケールの値を調整できます。 サーバーレス・アプリケーションは簡単に拡張できますが、限られた数の接続しか処理できない SQL DB やレート制限された別の API などのダウンストリーム・サービスによって左右される場合があります。 このフロントエンド・アプリケーションのインスタンス数を制限してみましょう。

   ibmcloud code-engine application update --name frontend --max-scale 5
   

4. 負荷の生成が停止したら、数分間待機し、インスタンスが終了して最終的にゼロ・インスタンスに縮小されたことを確認します。

5. ローカル・ウィンドウでロード・ジェネレーター・コマンドを使用してスクリプトを再実行し、アプリケーションに対する要求を作成します。 Cloud Shellで、 ibmcloud code-engine application get -n frontend コマンドを実行すると、インスタンス数が5に増加していることが確認できます。

   次のような出力になります。

   Name                                        Revision        Running  Status   Restarts  Age
   frontend-00002-deployment-77d5fbfb5d-7zpfl  frontend-00002  3/3      Running  0         70s
   frontend-00002-deployment-77d5fbfb5d-kv6rn  frontend-00002  3/3      Running  0         69s
   frontend-00002-deployment-77d5fbfb5d-mhlwn  frontend-00002  3/3      Running  0         68s
   frontend-00002-deployment-77d5fbfb5d-qkjmd  frontend-00002  3/3      Running  0         67s
   frontend-00002-deployment-77d5fbfb5d-zpr9n  frontend-00002  3/3      Running  0         85s
   

バックエンド・アプリケーションをデプロイし、接続をテストする

1. テキスト・ファイルを IBM Cloud Object Storage に保管する新しいバックエンド・アプリケーションをデプロイするには、次のコマンドを実行します。

   ibmcloud code-engine application create --name backend --image icr.io/solution-tutorials/tutorial-text-analysis-code-engine-backend --cluster-local
   

   --cluster-local フラグは Code Engineにこのアプリケーションのエンドポイントをプライベートに保つよう指示します。つまり、プロジェクト内からのみ利用可能であることを意味します。 この指示は多くの場合、セキュリティー上の目的で使用されます。 今回の場合では、クラスターの外からバックエンド・アプリケーションにアクセスされることはないため、パブリック・エンドポイントを使用してバックエンド・アプリケーションを公開する理由はありません。

2. 次のコマンドで使用するために、出力から内部エンドポイント URL をコピーして保存します。 出力は、次のようになります。

   BACKEND_PRIVATE_URL=http://backend.xxxxxx
   

   ibmcloud code-engine application get -n backend コマンドを実行すると、バックエンドアプリケーションのステータスと詳細 URL ）を確認できます。

3. フロントエンド・アプリケーションは環境変数 (BACKEND_URL) を使用して、バックエンド・アプリケーションがホストされている場所を認識します。 ここでフロントエンド・アプリケーションを更新して、この値がバックエンド・アプリケーションのエンドポイントを指すように設定する必要があります。

   ibmcloud code-engine application update --name frontend --env BACKEND_URL=$BACKEND_PRIVATE_URL
   

   --env フラグは、複数の環境変数を設定する必要がある場合に、必要な回数だけ使用できます。 このオプションは、ibmcloud code-engine application create コマンドでもフロントエンド・アプリケーションに対して使用することができます (その時点でフロントエンド・アプリケーションの値がわかっている場合)。 詳しくは、 環境変数の処理 の資料のトピックを参照してください。

4. ブラウザーでフロントエンド URL のハード・リフレッシュを実行して、バックエンド・アプリケーションへの接続をテストします。 テキスト・ファイル (.txt) をアップロードするオプションがページに表示されます。また、テキスト・ファイルを保管および処理するために必要な IBM Cloud サービスにバックエンドがまだ接続していないので、バックエンド・アプリケーションからのエラー・メッセージもこのページに表示されます。 「テキスト・ファイルのアップロード (Upload text file)」 をクリックしても、同じようなエラー・メッセージが表示されるはずです。

Object Storage および Natural Language Understanding サービスをプロビジョンする

1. Object Storage のインスタンスを作成します。

   1. アカウントに Object Storage サービス・インスタンスが既にある場合は、ライト プランまたは 標準 プランを選択します。
   2. 「サービス名」 を your-initials-code-engine-cos に設定します。
   3. Code Engine プロジェクトを作成したリソース・グループを選択します。
   4. 「作成」 をクリックします。
   5. サービス名をシェル変数に取り込みます。

      COS_INSTANCE_NAME=your-initials-code-engine-cos
      

2. 「バケットの作成」 の下で 「バケットの作成」 をクリックし、 「カスタム・バケットの作成」 の下で 「作成」 を選択します。

   バケットを作成したり、オブジェクトを追加する際には、個人識別情報（PII）の使用を避けるようにしてください。注：PIIとは、氏名、所在地、その他の手段によって、あらゆるユーザー（自然人）を特定できる情報を指します。

   1. 「固有のバケット名 (Unique bucket name)」 ( <your-initials>-bucket-code-engine など) を入力します。
   2. Code Engineを作成した場所を選択します。
   3. 「Smart Tier」 ストレージ・クラスを選択します。
   4. 「バケットの作成」 をクリックします。
   5. シェル変数にバケット名を取り込みます。

      COS_BUCKETNAME=your-initials-bucket-code-engine
      

3. バケット・ページ上。

   1. 「設定」タブをクリックします
   2. Direct エンドポイントは、 IBM Cloud内にデータを保持します。 シェル変数に直接エンドポイントを取り込みます。 アメリカ南部のダラスではそうかもしれない：

      COS_ENDPOINT=s3.direct.us-south.cloud-object-storage.appdomain.cloud
      

4. Natural Language Understanding のインスタンスを作成します。

   1. 場所を選択し、 ライトプランを選択します。
   2. 「サービス名」 を code-engine-nlu に設定し、Code Engine プロジェクトを作成したリソース・グループを選択します。
   3. ご使用条件を読み、 「次のご使用条件を読み、同意します」 にチェック・マークを付けます。
   4. 「作成」 をクリックします。
   5. サービス名をシェル変数に取り込みます。

      NLU_INSTANCE_NAME=YourServiceName
      

Object Storage サービスをバックエンド・アプリケーションにバインドする

ここで、先ほど作成した IBM Cloud Object Storage インスタンスの資格情報をバックエンド・アプリケーションに渡す必要があります。 Object Storageをアプリケーション にバインドすることで、サービス用の認証情報がアプリケーションまたはジョブの環境変数に自動的に追加されます。

1. アプリケーションで使いやすいように、接頭辞 COS を付けて Object Storage サービスのバインディングを作成します。 bind コマンドは、サービス・インスタンスにサービス資格情報を作成し、その資格情報を使用してアプリケーションの環境変数を初期化します。 _ --prefix フラグを使用することで、各サービスバインドにカスタム環境変数の接頭辞を使用するように設定することができます。_

   ibmcloud code-engine application bind --name backend --service-instance $COS_INSTANCE_NAME --role Writer --prefix COS
   

2. また、テキスト・ファイルを保管するバケット名と COS エンドポイントもアプリケーションに指定する必要があります。 これらは両方とも前のステップで定義されています。 Smart Tier の us-south のエンドポイントは s3.direct.us-south.cloud-object-storage.appdomain.cloud です。

   機密性の高い情報ではないため、バケット名とエンドポイントを保持する コンフィグマップを定義します。 configmap は、構成成果物をイメージ・コンテンツから切り離し、コンテナー化されたアプリケーションをポータブルな状態に保つことを可能にする Kubernetes オブジェクトです。 この configmap は、ファイルから、またはキー値ペアから作成できます。ここでは、--from-literal フラグを指定してキー値ペアを使用します。 これらを前にキャプチャーしたことを確認し、configmap を作成します。

   echo bucket $COS_BUCKETNAME endpoint $COS_ENDPOINT
   

   ibmcloud code-engine configmap create --name backend-configuration --from-literal=COS_BUCKETNAME=$COS_BUCKETNAME --from-literal=COS_ENDPOINT=$COS_ENDPOINT
   

3. configmap が定義されているので、これで configmap の値に基づいてアプリケーションのランタイムに環境変数を設定するように Code Engine に要求することで、バックエンド・アプリケーションを更新できます。 次のコマンドを使用して、バックエンド・アプリケーションを更新します。

   ibmcloud code-engine application update --name backend --env-from-configmap backend-configuration
   

   シークレットを作成するには、--env-from-secret フラグを使用することが必要になります。 シークレットと configmap は両方とも「マップ」であるため、設定される環境変数にはこれらのマップ内の各エントリーの「キー」に対応する名前が付けられ、環境変数の値はその「キー」の値になります

4. バックエンド・アプリケーションがバインディングと configmap を使用して更新されているかどうかを確認します。 以下のコマンドを実行し、出力に Service Bindings と Environment Variables のセクションがあるかどうかを確認します。

   ibmcloud code-engine application get --name backend
   

5. フロントエンド UI に移動し、テキスト分析を行う テキスト・ファイルをアップロード します。 アップロードしたファイルには、Not analyzed タグが付いています。

ジョブの作成

ジョブ は HTTPに応答するアプリケーションとは異なり、1回実行して終了するように設計された実行可能ファイルを含むコンテナイメージを実行するために使用することを目的としています。 job を作成するときに、ジョブを実行するたびに使用される作業負荷構成情報を指定できます。 ジョブはコンソールから、または CLI を使用して作成できます。

このジョブは、IBM Cloud Object Storage からテキスト・ファイルを読み取り、Natural Language Understanding サービスを使用してそのファイルを分析します。 ジョブが両方のサービスのサービス資格情報にアクセスできる必要があります。

1. ジョブを作成するには、次のコマンドを実行します

   ibmcloud code-engine job create --name backend-job --image icr.io/solution-tutorials/tutorial-text-analysis-code-engine-backend-job --env-from-configmap backend-configuration
   

   --env フラグを使用して Natural Language Understanding サービスのバージョンを設定することができます。 バージョン管理については、このリンクを参照してください。

IBM Cloud サービスをジョブにバインドする

1. アップロードされたファイルを読み取って結果を保管するジョブで使用するために、接頭部 COS_JOB を指定して Object Storage サービスのバインディングを作成します。

   ibmcloud code-engine job bind --name backend-job --service-instance $COS_INSTANCE_NAME --role Writer --prefix COS_JOB
   

2. 同様に、アップロードされたテキスト・ファイルを分析するために、接頭部 NLU_JOB を指定して Natural Language Understanding サービスをバインドします。

   ibmcloud code-engine job bind --name backend-job --service-instance $NLU_INSTANCE_NAME --role Writer --prefix NLU_JOB
   

3. ジョブのバインディングと configmap が更新されているかどうかを確認します。 以下のコマンドを実行し、出力に Service Bindings と Environment Variables のセクションがあるかどうかを確認します。

   ibmcloud code-engine job get --name backend-job
   

ジョブを実行する

1. 上記で作成した構成で ジョブを実行する には、 jobrun submit コマンドを使用します

   ibmcloud code-engine jobrun submit --name backend-jobrun --job backend-job
   

   ジョブを実行すると、ジョブ構成で設定した多くの変数を上書きできます。 変数をチェックするには、ibmcloud code-engine jobrun submit --help を実行します。

2. jobrun の状況を確認するために、以下のコマンドを実行します。

   ibmcloud code-engine jobrun get --name backend-jobrun
   

3. ログは以下のように表示できます。

   ibmcloud code-engine jobrun logs --follow --name backend
   

4. フロントエンド UI で、「テキスト・ファイルのアップロード (Upload text file)」の隣の 「更新」 ボタンをクリックし、アップロードされた各テキスト・ファイルの 「キーワード」 と 「JSON」 を表示します。 各ファイルのタグが Analyzed に変わります。

5. 新しいファイルをアップロードするか、「削除」 アイコンをクリックして個々のファイルを削除し、以下のコマンドで jobrun を再実行依頼し、「更新」 ボタンを押して結果を確認します。

   ibmcloud code-engine jobrun resubmit --jobrun backend-jobrun
   

ジョブ実行を自動化する

手動でジョブを実行する代わりに IBM Cloud Object Storage バケットへの変更を listen する Object Storage サブスクリプションを作成することで、ジョブの実行を自動化することができます。 バケットへの サブスクリプション を作成すると、そのバケットへの変更が成功するごとに、ジョブが個別のイベントを受信します。

1. Object Storage サブスクリプションを作成するには、その前に Code Engine にNotifications Manager役割を割り当てておく必要があります。 通知マネージャーの役割を持つ Code Engine は、Object Storage のバケットの通知を表示、変更、および削除できます。 ここにある説明に従って、通知マネージャー役割を Code Engine プロジェクトに割り当てます。
2. 以下のコマンドを実行して、backend-job を IBM Cloud Object Storage イベント・プロデューサーに接続します。 コマンドを実行する前に、bucket name を確認して更新します。

   ibmcloud code-engine subscription cos create --name backend-job-cos-event --destination-type job --destination backend-job --bucket $COS_BUCKETNAME --prefix files --event-type write
   

3. ここで、新規ファイルをアップロードし、「更新」 ボタンを押して結果を確認します。 jobrun はサブスクリプションで処理されるため、今後、再び実行依頼する必要はありません。