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

Heroku アドオンは、データストレージ、監視、分析、データ処理などの、アプリケーションをサポートするコンポーネントです。これらは、サードパーティプロバイダーまたは Heroku のどちらかによって完全に保守されます。アドオンは、開発者が、支援サービスを完全な本番容量で稼働する状態に維持するための複雑さを増すことなく、独自のアプリケーションロジックに焦点を絞ることができるようにするために存在します。

Elements Marketplace のカテゴリ別の使用可能なアドオン​を参照してください。

アドオンは、Heroku Dashboard または CLI を使用してアプリケーションにインストールされます。ほとんどのアドオンには、機能や価格が異なる複数のプランが用意されています。

アドオンプランは月額価格になっており、秒単位で比例配分されます​。プランを使用した時間分の料金のみを支払います。たとえば、Mini Heroku Data for Redis データベースの料金は月額 3 ドルです。Mini Heroku Data for Redis データベースを作成して 15 日後に削除した場合、料金は約 1.50 ドルです。

基本的な使用法

アドオンは、Dashboard または CLI のどちらかを使用してアプリに追加できます。Elements サイトには両方の手順が含まれており、CLI の例を以下に示します。

アドオンがアプリに追加されたら、それを 1 つ以上の環境設定 (環境変数) として使用できます。

これらの環境設定は、Dashboard の特定のインストール済みアドオンインスタンスの 「Attachment Details」 (アタッチメントの詳細) で確認できます。

また、一部のアドオンには、Dashboard と CLI の両方からアクセスできる (その特定のアドオンリソースの) 独自のダッシュボードがあります。

CLI インストールの例

アドオンは、heroku addons:create SERVICE​ コマンドを使用してインストールできます。このコマンドは、アドオンをそのプロバイダーでプロビジョニングし、アドオンにグローバル名とアプリケーション上のそのアドオンへのデフォルトのエイリアスを付与し、そのエイリアスに基づいた名前を使用してアドオンが提供するすべての環境設定を設定します。

次の例では、Heroku Data for Redis アドオン​をプロビジョニングし、それを example-app​ という名前の仮想のアプリにインストールします。

$ heroku addons:create heroku-redis --app example-app
Creating shining-calmly-4402... done, ($3/month)
Adding shining-calmly-4402 to example-app... done
Setting REDIS_URL and restarting example-app... done, v3

CLI の出力は、新しくインストールされたアドオンのグローバル名が shining-calmly-4402​ であり、アプリケーション上のそのアドオンのエイリアスが REDIS​ (このアドオンサービスのデフォルト値) であり、その結果、設定された環境設定が REDIS_URL​ であることを示しています。環境設定はアドオンごとに異なり、各アドオンのドキュメントで説明されています。たとえば、Heroku Data for Redis のドキュメント​を参照してください。

アドオンの詳細は、heroku addons​ コマンドを使用していつでも表示できます。

$ heroku addons --app example-app
=== Resources for example-app
Plan                    Name                 Price
-----------------  -------------------  ----------
heroku-redis:mini  shining-calmly-4402  $3/month

=== Attachments for example-app
Name   Add-on               Billing App
-----  -------------------  -------------
REDIS  shining-calmly-4402  example-app

Resources​ (リソース) セクションには、このアプリケーションによって所有されているアドオンが、プラン、グローバル名、コストなどのそのアドオンに関する詳細と共に一覧表示されます。アタッチメント​のセクションには、この (つまり、アドオンへのエイリアスを含む) アプリケーションにアタッチされているすべてのアドオンが一覧表示されます。このアプリがそのアドオンを所有しているかどうかには関係ありません。ここで、REDIS​ が今インストールした shining-calmly-4402​ アドオンへのエイリアスであることを確認できます。この段階では、アドオンのリソースとそのアタッチメントの区別は必要ないように見えるかもしれませんが、以下の次のセクションでは、これが必要である理由を示すいくつかの重要な例について見ていきます。

このアドオンをインストールすることにより、エイリアス REDIS​ が前に付加されたすべての環境変数の管理をそのアドオンに委任したことになります。heroku-redis​ の場合は、URL​ 変数のみが使用されるため、REDIS_URL​ がこのアドオンによって設定されます。

$ heroku config --app example-app
REDIS_URL:     redis://h:pa4kvrg6a3ah52g5akto82kil@ec2-54-204-3-133.compute-1.amazonaws.com:6569

高度な使用法

アドオンをアプリケーションに関連付ける方法をよりきめ細かく制御できる手段がいくつかあります。

• デフォルトでは、アドオンリソースには shining-calmly-4402​ などの俳句のような名前が付与されますが、アドオンの名前はカスタマイズできます。
• 一部のアドオンは 1 つのアプリ内に複数の名前を持つことができます。
• アドオンによっては複数のアプリにアタッチできます。

わかりやすい名前

アドオンのグローバル名 shining-calmly-4402​ は、必ずしもわかりやすいとはいえません。アプリと同様に、必要でなければ名前を選択する必要はありませんが、多くの場合、アプリケーションの複雑さが増していくと問題になることがあります。

アドオンを最初に作成するときは、--name​ オプションを使用して、わかりやすい名前を付けることができます。

$ heroku addons:create heroku-redis --app example-app --name important-redis
Creating important-redis... done, ($3/month)
Adding important-redis to example-app... done
Setting REDIS_URL and restarting example-app... done, v7

これで、アドオンインスタンスが識別される場所では常に、認識可能な名前が表示されます。

$ heroku addons --app example-app
=== Resources for example-app
Plan                    Name             Price
-----------------  ---------------  ----------
heroku-redis:mini  important-redis  $3/month

=== Attachments for example-app
Name   Add-on           Billing App
-----  ---------------  -------------
REDIS  important-redis  example-app

エイリアスの名前はアプリケーションに関連している場合があります。

たとえば、Python の世界では、一般的なタスク/ジョブキューである Celery​ は Redis を含む複数のバックエンドストレージシステムのいずれかを使用できます。このライブラリは、デフォルトでは環境設定 BROKER_URL​ を調べ、URL 転送プロトコルを利用して、使用するバックエンドを決定します。

example-app​ 上のキューバックエンドとして Redis を使用したい場合を考えてみます。 アドオン環境設定はエイリアスが前に付加されているため、デフォルト以外のエイリアスを選択して、Celery がそのバックエンドとして Redis インスタンスを簡単に使用するようにできます。

$ heroku addons:create heroku-redis --app example-app --name important-redis --as BROKER
Creating important-redis... done, ($3/month)
Adding important-redis to example-app... done
Setting BROKER_URL and restarting example-app... done, v9

上記の出力に示されているように、アプリケーションには通常のデフォルトの REDIS_URL​ ではなく、BROKER_URL​ が設定されていることがわかります。これは heroku config​ の出力でも確認できます。

$ heroku config --app example-app
BROKER_URL: redis://h:pfcs5ilk6ksc7f5nt8v62qqf1ip@ec2-54-204-3-133.compute-1.amazonaws.com:6599

複数のエイリアス/アタッチメント

アドオンを参照するために使用するエイリアスが複数あると有効な場合があります。例として、タスクキューブローカーに加えて、前の例の同じ Redis インスタンスをセッションストアとして使用したい場合を考えてみます。これは、新しいエイリアスを含むアプリにアドオンをリンクする heroku addons:attach EXISTING_ADDON​ を使用して実現できます。

$ heroku addons:attach important-redis --app example-app --as SESSION_STORE
Attaching important-redis as SESSION_STORE to example-app... done
Setting SESSION_STORE vars and restarting example-app... done, v10

アタッチメントが作成されたら、追加のエイリアスを heroku addons​ で、 結果として追加された新しい環境設定を heroku config​ で確認できます。

$ heroku addons --app example-app
=== Resources for example-app
Plan                    Name             Price
----------------- ---------------  ----------
heroku-redis:mini  important-redis  $3/month

=== Attachments for example-app
Name           Add-on           Billing App
-------------  ---------------  -------------
BROKER         important-redis  example-app
SESSION_STORE  important-redis  example-app
$ heroku config --app example-app
BROKER_URL:        redis://h:pfcs5ilk6ksc7f5nt8v62qqf1ip@ec2-54-204-3-133.compute-1.amazonaws.com:6599
SESSION_STORE_URL: redis://h:pfcs5ilk6ksc7f5nt8v62qqf1ip@ec2-54-204-3-133.compute-1.amazonaws.com:6599

2 つのアタッチメントが一覧表示されていますが、どちらも 1 つの important-redis​ アドオンに対応することに注意してください。また、両方の環境設定が同じ値を持つことにも注意してください。

複数のエイリアスを作成する機能はまた、2 番目のアタッチメントを作成して、エイリアスとそれに対応する環境設定の名前を変更した後、heroku addons:detach ATTACHMENT_NAME​ を使用して元のアタッチメントを削除するためにも使用できます。

アプリ間でのアドオンの共有

上記のように、heroku addons:attach​ コマンドは、アプリケーション上のアドオンの追加のエイリアスを作成するために使用されます。これを利用すると、両方の所有者が同じである限り、別の​アプリケーション上のアドオンのエイリアスも作成できます。

たとえば、ブローカー (前の例) のキューに入れようとしているタスクを、example-tasker​ という名前の別のアプリケーション内の別のコンポーネントで処理する必要があるとします。任意の (またはデフォルトの) エイリアスを使用してアドオンを 2 番目のアプリケーションと共有できますが、後でその目的を理解できるように BROKER を再利用しましょう。

$ heroku addons:attach important-redis --app example-tasker --as BROKER
Attaching important-redis as BROKER to example-tasker... done
Setting BROKER vars and restarting example-tasker... done, v3

2 番目のアプリケーション上のアドオンと環境設定を見てみましょう。

$ heroku addons -a example-tasker
=== Resources for example-tasker
There are no add-ons.

=== Attachments for example-tasker
Name    Add-on           Billing App
------  ---------------  -------------
BROKER  important-redis  example-app
$ heroku config -a example-tasker
BROKER_URL: redis://h:pfcs5ilk6ksc7f5nt8v62qqf1ip@ec2-54-204-3-133.compute-1.amazonaws.com:6599

example-tasker​ アプリケーションによって所有されているアドオンリソースは存在しないが、 important-redis​ という名前のアドオンへの BROKER​ という名前のアタッチメント (これは、アプリ example-app​ に請求される) が存在することに注意してください。また、BROKER_URL​ が example-app​ 上のその同類と値を共有していることにも注意してください。何らかの理由でアドオンプロバイダーでこの値を変更することが必要になった場合は、新しい値が設定された状態で、これらのアプリケーションの両方が自動的に再起動されます。

アプリへの複数の同じアドオンサービスのインストール

ほとんどのアドオンは、特定のアプリケーションに 1 回のみインストールするように設計されていますが、一部のアドオンは複数回インストールできます。

たとえば、タスクブローカーとセッションストアを Redis の異なるインスタンスでバックアップしたい場合を考えてみます。これを行う理由として、アドオンを共有しているときにアクセスできるデータの制限や、各ユースケースに異なるプランやサードパーティプロバイダーによって提供される異なるセマンティックスがある場合 (たとえば、耐久性と処理速度のどちらかの選択) などのいくつかが考えられます。

2 番目の Redis インスタンスは非常に簡単に作成できます。

$ heroku addons:create heroku-redis --app example-app
Creating sighing-nobly-1891... done, ($3/month)
Adding sighing-nobly-1891 to example-app... done
Setting REDIS_URL and restarting example-app... done, v11

3 番目を作成することもできます。

$ heroku addons:create heroku-redis --app example-app
Creating cooling-carefully-7273... done, ($3/month)
Adding cooling-carefully-7273 to example-app... done
Setting HEROKU_REDIS_ROSE_URL and restarting example-app... done, v12

セッションストアでは新しい Redis インスタンスを使用するため、SESSION_STORE​ エイリアスを新しいアドオンを指すエイリアスに置き換えましょう。

$ heroku addons:attach sighing-nobly-1891 --as BROKER --app example-app
Attaching sighing-nobly-1891 as BROKER to example-app...
 !    sighing-nobly-1891 will overwrite BROKER_URL on example-app.
 !    To proceed, type "example-app" or re-run this command with --confirm example-app
>

ここでは既存のエイリアスと環境設定を置き換えるため、その意図を確認する必要があります。確認すると、アタッチメントとその環境変数が置き換えられます。

> example-app
Attaching sighing-nobly-1891 as BROKER to example-app... done
Setting BROKER vars and restarting example-app... done, v14
$ heroku addons --app example-app
=== Resources for example-app
Plan                    Name                    Price
-----------------  ----------------------  ----------
heroku-redis:mini  cooling-carefully-7273  $3/month
heroku-redis:mini  important-redis         $3/month
heroku-redis:mini  sighing-nobly-1891      $3/month

=== Attachments for example-app
Name               Add-on                  Billing App
-----------------  ----------------------  -------------
BROKER             sighing-nobly-1891      example-app
HEROKU_REDIS_ROSE  cooling-carefully-7273  example-app
REDIS              sighing-nobly-1891      example-app
SESSION_STORE      important-redis         example-app
$ heroku config --app example-app
BROKER_URL:            redis://h:p5ip3vevv16shofgnkstglu65r9@ec2-54-204-3-133.compute-1.amazonaws.com:6609
HEROKU_REDIS_ROSE_URL: redis://h:pankbrfd3va8gejrrvep7r69j0@ec2-54-204-3-133.compute-1.amazonaws.com:6619
REDIS_URL:             redis://h:p5ip3vevv16shofgnkstglu65r9@ec2-54-204-3-133.compute-1.amazonaws.com:6609
SESSION_STORE_URL:     redis://h:pfcs5ilk6ksc7f5nt8v62qqf1ip@ec2-54-204-3-133.compute-1.amazonaws.com:6599

SESSION_STORE​、BROKER​、HEROKU_REDIS_ROSE​ はそれぞれ異なるアドオンインスタンスを指しており、それぞれが対応する環境設定に設定された一意の値を持っています。HEROKU_REDIS_ROSE​ としてエイリアス指定されたアドオンは例として作成されただけであり、このシナリオでは REDIS​ エイリアスが冗長であるため、それらを削除します。

$ heroku addons:detach REDIS --app example-app
Removing REDIS attachment to sighing-nobly-1891 from example-app... done
Unsetting REDIS vars and restarting example-app... done, v15
$ heroku addons:destroy cooling-carefully-7273
 !    WARNING: Destructive Action
 !    This command will affect the app: example-app
 !    To proceed, type "example-app" or re-run this command with --confirm example-app
> example-app
Destroying cooling-carefully-7273 on example-app... done, ($3/month)
Removing vars for HEROKU_REDIS_ROSE from example-app and restarting... done, v16

これですべてが希望どおりになりました。つまり、2 つの個別のインスタンスがあり、そのうちの 1 つが両方のアプリケーションへの BROKER​ としてエイリアス指定されています。

$ heroku addons --app example-app
=== Resources for example-app
Plan                    Name                Price
-----------------  ------------------  ----------
heroku-redis:mini  important-redis     $3/month
heroku-redis:mini  sighing-nobly-1891  $3/month

=== Attachments for example-app
Name           Add-on              Billing App
-------------  ------------------  -------------
BROKER         sighing-nobly-1891  example-app
SESSION_STORE  important-redis     example-app
$ heroku addons --app example-tasker
=== Resources for example-tasker
There are no add-ons.

=== Attachments for example-tasker
Name    Add-on           Billing App
------  ---------------  -------------
BROKER  important-redis  example-app

高度な使用法の例

アドオンを試してみるために使用できるユースケースの例のいくつかを次に示します。これらのシナリオは、Heroku 自体の実際のインスタンスに基づいています。

• データウェアハウスとして機能している 1 つのアプリケーションを使用して、複数のアプリケーションの Heroku Postgres データベースを共有します。各エイリアスに、それが指しているデータベースを持つアプリに基づいて名前を付けます。
• 互いにイベントをリッスンするために、複数のアプリの間で CloudAMQP​ などのメッセージキューを共有します。
• 複数の RedisCloud​ インスタンスを作成し、自動的に選択されるエイリアスを観察します。アプリケーションが使用するインスタンスを変更できるように、heroku addons:attach​ を使用して、すでに存在するエイリアスを置き換えます。
• 既存のインスタンスがすでに使用しているエイリアスを使用してインストールすることにより、RedisCloud​ インスタンス を Heroku Redis インスタンスに (またはその逆に) 置き換えます。
• アドオンへの唯一のエイリアスの削除を試み、エラーメッセージを観察します。

詳細

アドオンに関してアプリ開発者が実行できること

• アプリケーションに任意の数のアドオンをインストールする。
• 場合によっては、同じアプリケーションに同じアドオンの複数のインスタンスをインストールする。
• 同じ所有者を持つ複数のアプリケーションの間で特定のアドオンを共有する。
• より多くのアクションを実行するためにアドオンダッシュボードにログインする。

アプリに関してアドオンが実行できること

アドオンは、次のようないくつかの方法で Heroku アプリケーションと対話できます。

• アドオンを使用して、特定の環境設定​をアプリケーションに追加および更新する。
• ログに書き込む。
• ログを読み取る。
• デプロイイベントをリッスンする。
• ドメインの追加または削除イベントをリッスンする。
• アプリ情報を表示する。
• アプリの所有者情報を表示する。

アタッチメントの名前/エイリアス

アドオンをインストールまたはアタッチする場合、アタッチメントは、そのアプリケーションに固有の名前/エイリアスを持っている必要があります。これは、同じアドオンの複数のアタッチメントを区別できるようにして、環境設定が競合しないようにするためです。

環境設定が設定される方法のいくつかの例を次に示します。

アドオンのインストール時に行う必要がある​決定を最小限に抑えるために、Heroku では、名前付けの競合を処理するためのいくつかの単純なルールに基づいてエイリアスが自動的に割り当てられます。

基本的に、アタッチメント名は次のように選択されます。

1. ユーザーの選択 (指定されている場合)。

   If provided but presents a conflict, confirmation to overwrite it is requested.

2. アドオンプロバイダーによって選択されたデフォルトのエイリアス (使用可能な場合)。

   Usually, this is a derivative of the name of the add-on service (e.g. IronCache’s service name is iron_cache and its default alias is IRON_CACHE, while Heroku Postgres’ service name is heroku-postgresql but its chosen default alias is DATABASE not HEROKU_POSTGRESQL).

3. アドオンサービス名とランダムな色に基づいて生成されたエイリアス。

   For example, when DATABASE is already taken, a name like HEROKU_POSTGRESQL_CYAN is chosen for Heroku Postgres; and when REDISCLOUD is already taken, a name like REDISCLOUD_BLUE is chosen for the add-on RedisCloud.

heroku addons:create​ または heroku addons:attach​ を実行している場合は、--as​ オプションを使用して独自のエイリアスを常に指定できます。この名前は、そのアプリケーションのスコープ内で一意である必要があります。そうでない場合は、既存の名前を上書きするための確認が表示されることがあります。

さらに、コマンド内でアドオンインスタンス (important-redis​ など) の識別子が想定される場合は、そのアドオンのいずれかの既知のエイリアスを識別子として使用することもできます。このアドオンは、現在のアプリケーションと指定されたエイリアスを調べることによって解決されます。別のアプリケーション上のエイリアスでアドオンを参照する必要がある場合は、app-name::ALIAS​ の長い形式のバージョンを使用できます。

環境設定の値は変更される場合がある

環境設定​は、アドオンサービスにアクセスする方法に関する情報をアプリケーションに提供します。アドオン環境設定は通常 URL の形式であり、資格情報、ホストやポートの情報、リソース名、さらにはプロトコル情報 (上記の例など) がエンコードされています。

アドオンは、アプリケーション内の環境設定にアクセスできるため、場合によってはそれらを変更できます (フェイルオーバーを必要とする基礎となるインフラストラクチャの障害が発生した場合など)。このような場合、アドオンプロバイダーは、サービスを自身のインフラストラクチャの別の部分に切り替え、対応する環境設定の値を更新することによってこの変更を伝えることができます。

環境設定が変更された場合、アプリケーションは、結果として得られるリリース​で自動的に再起動されます。したがって、サービスの中断をできるだけ最小限に維持するために、アプリケーションはコードまたは設定でハードコーディングされたアドオン環境設定の値を使用したり、ビルド​中に環境設定の値をキャッシュしたりしないことが重要です。代わりに、環境設定は、実行時またはアプリケーションの起動中に常に動的に読み取られる必要があります。