アドオンの非同期プロビジョニング

最終更新日 2024年05月02日(木)

ワークフローの例
知っておきたいこと
前提条件
実装
まとめ

非同期プロビジョニングにより、パートナーは最も効率的な方法で帯域外プロビジョニングを実行できます。アドオンサービスのセットアップに特に時間がかかるパートナーによる使用が主に想定されていますが、誰でも使用できます。

これにより、すべてのパートナーが heroku pg:wait のような動作を実装できるようになり、自動でのアプリのセットアップとオーケストレーションが簡単になり、エラーも減少します。

ワークフローの例

図の説明は後述

これはかなり人為的な例ですが、非同期プロビジョニングの効果を示しています。この例では、パートナーはプライマリとセカンダリの 2 つのデータストアをスピンします。レプリケーションを設定するために、これを順番に実行します。

パートナーはプロビジョニングリクエストに 202 Accepted で応答し、そのインフラストラクチャのプロビジョニングに進みます。
まずプライマリをプロビジョニングし、接続文字列でアドオンの設定を更新します。アプリは再起動されません。
次に、セカンダリをプロビジョニングし、その接続文字列でアドオンの設定を更新します。アプリはまだ再起動されません。
最後に、処理が完了し、アドオン (とそのコンポーネントのすべて) が完全にプロビジョニングされて使用の準備ができたことを通知するために、Heroku を明示的に呼び出します。ここでアプリが再起動されます。

このプロセスの各段階の詳細は「実装」のセクションで追って説明します。

知っておきたいこと

請求

アドオンのプロビジョニングが開始するとすぐ、顧客への請求が発生します。つまり、サービスのプロビジョニングの時間とコストも、顧客の支払い額に反映されることになります。したがって、顧客ができるだけ早くサービスから価値を得られるよう、あらゆる努力を払って臨機応変なプロビジョニングに努めてください。

プロビジョニングされないアドオン

12 時間以内にプロビジョニングが終わらない (または、その時間内にサービスで API を介して “プロビジョニング済み” とマークできない) アドオンは失敗とみなされ、ユーザーのアプリから削除されます。この場合、顧客への請求は発生しないため、パートナーへの支払いも発生しません。

前提条件

パートナー向け Platform API を使用する必要があります
非同期プロビジョニングを使用するには、アクセスをリクエストする必要があります (アドオンパートナー API の v1 を使用している場合は、エコシステムエンジニアリングチーム)までお問い合わせください)。v3 統合では、デフォルトで非同期プロビジョニングがサポートされています。

実装

プロビジョニングリクエストに 202 Accepted で応答する

Heroku からプロビジョニングリクエストを受信したら、以下を実行します。

システムでこのアドオンインスタンスを表すレコード (通常はアカウント) を作成します。
サービスの中で時間のかかる部分をプロビジョニングするためのジョブをキューに入れます。
最後に、次の内容で応答します。
- 作成したアカウント (またはその他の要素) の ID
- ユーザーへのメッセージ
- 202 Accepted 応答コード

プロビジョニング応答の例

status 202
JSON.encode({
  id: account.id,
  message: "Your add-on is being provisioned. It will be available shortly."
})

これは、アドオンをプロビジョニング状態に保ち、その間は設定が更新されてもアプリを再起動しないよう Heroku に指示します。アプリが再起動される前に、プロビジョニング済みで使用の準備ができているとアドオンを明示的にマークする必要があります。

アドオンの設定を更新する

プロビジョニングが完了したら、アプリでサービスを利用するために必要な情報を指定してアドオンの設定を更新します。これによってアプリがリリースされるわけではないため、プロビジョニング中、多くの変数を一度に 1 つずつ更新していっても問題ありません。

アドオン設定エンドポイントに関するドキュメントを参照してください。このエンドポイントにアクセスするには、パートナー向け Platform API を使用している必要があります。

PATCH /addons/01234567-89ab-cdef-0123-456789abcdef/config
Host: api.heroku.com:443
Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer 2af695e0-93e3-4821-ac2e-95f68435f128

{
  "config": [
    {
      "name": "MY_ADDON",
      "value": "bar"
    }
  ]
}

一部のアドオンでは、アプリケーションで設定されている実際の環境変数がキーと異なっている場合があります。送信するすべての環境変数に同じ接頭辞 (アドオンの名前を大文字にしたもの) を付けてください。ただし、Heroku アプリのコンテキスト内では、さまざまな理由により接頭辞が異なる場合があります。

たとえば、アドオンの名前が fast-db で、FAST_DB_URL を設定している場合、アプリケーションでの変数名はデフォルトで FAST_DB_URL になりますが、ユーザーが接頭辞 PRIMARY_DB を付けてアドオンを追加した場合は PRIMARY_DB_URL になります。

アドオンのプロビジョニングを完了する

最後のステップでは、アドオンが完全にプロビジョニングされて使用の準備ができていることを Heroku に通知します。プロビジョニングリクエストから 12 時間以内にこの手順を実行しない場合、失敗とみなされてアドオンは削除されます。プロビジョニングが完了したことを示すには、アドオンのプロビジョニング操作エンドポイントを使用します。

POST /addons/:uuid/actions/provision

この時点で、ユーザーのアプリが再起動し、サービスを利用するために適切な環境変数が設定されます。

アドオンのプロビジョニング失敗の処理

プロビジョニングが失敗した場合、アドオンのプロビジョニング解除操作エンドポイントを使用して、アドオンがプロビジョニング解除されたことを Heroku に通知する必要があります。

POST /addons/:uuid/actions/deprovision

この時点でリソースはユーザーのアプリから削除され、ユーザーへの請求は発生しません。

まとめ

アドオンパートナーは非同期プロビジョニングを使用して、プロビジョニングのステータスを Heroku に通知し、自動化とオーケストレーションを推進することができます。パートナーは、Heroku API との統合方法の一部に変更を加え、機能を明確に有効化する必要があります。実装に関する質問がある場合は、Heroku のエコシステムエンジニアリングチームまでお問い合わせください。

Categories