deploying-containers-to-amazon-lightsail

Amazon Lightsail へのコンテナのデプロイ

概要

Amazon Lightsail Container Service は、管理された HTTPS URL の背後でコンテナイメージを実行し、月額固定料金を提供します。URL、TLS 証明書、ロードバランシングが含まれているため、クラスター、VPC、ロードバランサー、レジストリを設定する必要はありません。

このスキルでは、あらゆるソースのコンテナイメージを、稼働してリクエストを処理する Lightsail のデプロイに移行し、リクエストを処理できないデプロイの問題を診断します。サービスを作成するには、2 つの項目を選択します。各ノードのメモリと vCPU を決める power と、実行するノード数を決める scale です。各ノードではデプロイの完全なコピーが実行されます。容量は自動で変わりません。オートスケーリングも、ゼロへのスケールもないため、サービスにさらに容量が必要になったら、自分で power または scale を増やします。

前提条件

作成を始める前に、次の点を確認してください。

• イメージのソース、アプリがリッスンするポート、リージョンを確認します。
• **実行時に利用可能なオプション（power とリージョン）を確認します。**値をハードコードしないでください。
• **プランと料金を確認します。**月額固定料金（power × scale。トラフィックがなくても請求されます）を伝え、請求対象のリソースを作成する前に確認を取ります。ユーザーがすでに実行を指示している場合を除き、確認が必要です。何も伝えずに作成してはいけません。料金を確認する場所については、以下の「料金」セクションを参照してください。
• **固定の上限は変更できません。**サービスごとのノード数の上限が scale の上限です。また、デプロイごとのコンテナ数とデプロイのバージョン数にも上限があります。上限の引き上げを提案するのではなく、Lightsail quotas で値を確認してください。アカウントの作成から日が浅い場合や、利用が少ない場合、実際のクォータが公開されているデフォルト値より低いことがあります。
• **権限を確認します。**呼び出し元の ID には、以下の「操作」表に記載された Lightsail アクションが必要です。アクションが不足していると、ツールの問題やクォータの問題ではなく、最初の呼び出しでアクセス拒否エラーが発生します。権限の範囲を設定する方法については、以下の「セキュリティに関する考慮事項」セクションを参照してください。

ツール：パブリックレジストリのイメージをデプロイする場合は、AWS CLI（v2）だけで十分です。操作は AWS MCP ツール（推奨。下記参照）または CLI から直接実行できます。ローカルでのビルドやプッシュには、docker（実行中）も必要です。さらに、push-container-image ショートカットを使う場合は lightsailctl プラグインが必要です（プラグインを使わないプッシュでは、代わりに docker と register-container-image を使用します）。

AWS の操作を実行する場合：利用可能であれば、AWS MCP 実行ツール aws___run_script を優先して使い、各呼び出しは短くしてください。すぐに戻る 1 つの操作に限定し、長時間実行する操作は避けてください（約 30 秒を超えて実行中の呼び出しは打ち切られ、セッションが失われます）。これは必須ではありません。同じ操作はローカルの aws CLI からも実行でき、MCP ツールが利用できない場合はこちらを使います。ローカルイメージのビルドとプッシュは、Docker／lightsailctl の操作として自分のマシン上で実行するものであり、MCP ツール経由では実行できない点に注意してください。

lightsailctl のインストール：必要なのは push-container-image ショートカットを使う場合だけです。また、AWS CLI v2 と実行中の Docker が必要です。

• macOS： brew install aws/tap/lightsailctl
• Linux： curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-amd64/lightsailctl" -o /usr/local/bin/lightsailctl && chmod +x /usr/local/bin/lightsailctl
• Windows： https://s3.us-west-2.amazonaws.com/lightsailctl/latest/windows-amd64/lightsailctl.exe をダウンロードして、PATH に追加します。

インストールがブロックされる場合や、プラグインが引き続き見つからない場合は、トラブルシューティングのリファレンスを参照してください。または、references/local-image.md に記載されているプラグイン不要のプッシュを使い、プラグインを完全に省略してください。

参考資料

手順の詳細は、このスキルに同梱されている参考資料ファイルに記載されています。作業を始める前に、イメージのソースまたはこれから行う手順に合った参考資料を必ず読んでください。ポート、イメージのアーキテクチャ、プッシュ方法など、間違えやすい要件と正確な手順が記載されています。

参考資料を開くには、AWS MCP サーバー上ではスキルのコンテンツ取得ツールで取得してください。それ以外の場合は、このスキルのディレクトリ（スキルの読み込み時に場所が示されています）から読み取ります。例：<skill-dir>/references/NAME.md。 裸の references/NAME.md からは読み取らないでください。これはスキルではなく作業ディレクトリを基準に解決され、「No files found」というエラーになります。その場合は、スキルのディレクトリを先頭に追加して再試行してください。

• references/public-image.md — パブリックレジストリのイメージ（ビルドもプッシュも不要）。
• references/local-image.md — ローカルイメージをビルドし、サービスのレジストリにプッシュします（docker、push-container-image、またはプラグイン不要の手順）。
• references/github-source.md — GitHub リポジトリをクローンしてビルドし、ローカルイメージの手順に進みます。
• references/deployment.md — デプロイの構成（containers + publicEndpoint + ヘルスチェック）、ステータスが ACTIVE になるまでのポーリング、ロールバック、削除の方法。
• references/troubleshooting.md — lightsailctl が見つからない場合、デプロイのステータスが FAILED の場合、502/503、exec format error（CPU アーキテクチャの不一致）。

サービス、デプロイ、コンテナ

• コンテナサービス — 最初に作成する、長期間稼働するリソースです。容量（power × scale）、パブリック HTTPS URL、プライベートドメイン、および専用のイメージレジストリを所有します。料金は作成から削除まで発生します。
• デプロイ — サービスで実行する内容を定義した、変更不可のバージョン付き仕様です。一度に有効にできるのは1つで、新しいデプロイを作成すると仕様全体が置き換わります。
• コンテナ — デプロイ内のエントリです（デプロイごとの上限は、上記リンク先の Lightsail のクォータを参照してください）。それぞれに名前、イメージ、ポートがあります。パブリックエンドポイントにできるのは1つだけで、その他のコンテナには兄弟コンテナから localhost 経由でのみアクセスできます。

料金

料金は、転送クォータに応じて容量ごとに設定されています。月額料金は、作成から削除まで、リクエストの有無にかかわらず、パワーの料金 × スケールで計算されます。各サービスには月間データ転送クォータが1つ含まれます。このクォータは、サービスで選択したパワーやスケールによって変わりません。クォータを超えた送信データには、リージョンによって異なる料金が GB 単位で課金されます。受信データもクォータに含まれますが、超過しても課金されません。

料金を記載する場合は、以下のいずれかの情報源から直前に確認した値のみを使用してください。記憶に頼ったり、確認していない料金に $0.00 のようなプレースホルダーを使ったりしないでください。容量料金は正確に計算できます（パワーの料金 × スケール）。送信データの料金は、把握できないトラフィック量によって変わるため正確には計算できません。合計額ではなく、GB あたりの料金を示してください。

• パワーの料金 — get-container-service-powers が唯一の情報源です。各パワーのノードあたりの月額料金が返されるため、その金額をそのまま記載してください。
• 転送クォータ — AWS Price List の get-products オペレーションで AmazonLightsail サービスコードを指定し、Lightsail Containers レコードの dataTransferQuota 属性を参照してください。
• 送信データの料金 — overageType = ContainerSvc:Data Transfer の TERM_MATCH フィルターを使い、別の get-products レコードを検索してください。productFamily ではなく overageType を使用してください。Lightsail Networking には CDN、バケット、インスタンス、DNS の超過料金も含まれています。これらのレコードでは転送元のロケーションが示されるため、regionCode ではなく fromRegionCode で絞り込んでください。

ワークフロー

1. サービスを作成する — 適切なパワーとスケールを選択し、state が READY になるまで get-container-services をポーリングします。 get-container-service-powers は各パワーの name（nano）と powerId（nano-1）を返します。サービスの作成時には、--power に name を指定してください。
2. イメージを用意する — イメージソースごとに異なる唯一の手順です。上記の該当するリファレンスに従ってください。
3. バージョンをデプロイする（containers とヘルスチェック付きの publicEndpoint を1つ含めます）。デプロイメントをポーリングして ACTIVE になるまで待ちます。デプロイメントのリファレンスを参照してください。
4. 確認して報告する — デプロイメントが ACTIVE になってから、サービスから生成されたURLを読み取ります（ランダムなIDが含まれるため、組み立てずに読み取ってください）。URLが応答することを確認し、URL、月額料金、リソースの削除コマンドを報告してください。

ポーリング： 作成とデプロイはすぐに応答し、処理は非同期で完了します。完了までに約5～10分かかることがあり、PENDING／ACTIVATING の状態が続いていても正常です。短いステータス確認を一時停止を挟んで繰り返す方法でポーリングしてください。各確認はすぐに応答する短い呼び出しにし、その間に短い sleep を挟みます。長時間実行される1回の呼び出し内（1つの run_script 内のループや長い shell のループ）で待たないでください。これが実行タイムアウトの原因になります（1回の呼び出しが約30秒を超えて実行され続けると、打ち切られてセッションが失われることがあります）。デプロイメントが ACTIVE になってからURLを返してください。

推奨事項と禁止事項

✅ 推奨事項	❌ 禁止事項
作成前に月額料金を確認する（続行するよう指示されている場合を除く）	課金対象のリソースを黙って作成する
APIからパワー、リージョン、料金、イメージのバージョンを確認する	パワー、スケール、リージョン、料金、イメージのバージョンをハードコードする
イメージの手順に進む前に、イメージソースのリファレンスを読む	ビルド／プッシュの順序を推測する
短い呼び出しと、その間の sleep を繰り返してポーリングする。ACTIVE になってからURLを返す	長時間実行される1回の呼び出し（run_script のループや長い shell のループ）内で待つ。URLを早く返す
パブリックイメージの場合は、ビルドとプッシュを完全に省略する	レジストリにイメージがすでにあるのに、ローカルでのビルドを必須にする
障害の診断には get-container-log を読む	502や FAILED のデプロイメントに対して、確認せずに再ビルドや再デプロイを行う
マイクロサービスやオートスケーリングには、ECS/EKSまたはECS Express Modeを推奨する	あらゆるコンテナの質問に対してLightsailを回答として提示する
リソースの削除コマンドを必ず提示する	ユーザーが課金を止められない状態にする

オペレーション

オペレーション（aws lightsail …）	目的	備考
get-container-service-powers	仕様と価格を含む、利用可能なパワーを一覧表示します	記憶しているサイズや価格を引用せず、こちらを参照してください
create-container-service	サービスを作成します	定額料金 ＝ パワー × スケール
update-container-service	実行中のサービスの容量（パワー／スケール）を変更します	ダウンタイムなしで現在のデプロイを自動的に再デプロイし、同じデプロイバージョンを維持します
get-container-services	状態を確認します	デプロイ前は READY、デプロイが有効になった後は RUNNING です
push-container-image	ローカルイメージをプッシュします	lightsailctl プラグインと、実行中のローカル Docker が必要です
create-container-service-registry-login	一時的なレジストリ認証情報を取得します	プラグインを使わずにプッシュする場合の最初の手順です
register-container-image	プッシュ済みのイメージをダイジェストで登録します	push-container-image の、プラグインを使わない代替手段です
get-container-images	サービスのレジストリにあるイメージバージョンを一覧表示します	Lightsail がバージョン番号を割り当てます。推測せず、こちらを参照してください
create-container-service-deployment	イメージをデプロイします	containers{} + publicEndpoint{containerName, containerPort, healthCheck}
get-container-service-deployments	デプロイの状態と履歴を確認します	ACTIVATING → ACTIVE。以前のバージョンを再デプロイするとロールバックできます
get-container-log	コンテナログを読み取ります	デプロイの失敗を診断する際は、まずこちらを確認してください。シークレットや顧客データをログに記録しないでください
delete-container-service	サービスを削除します	課金が停止します

セキュリティに関する考慮事項

• 最小権限の IAM — 呼び出し元のプリンシパルには、lightsail:* や管理者ポリシーではなく、このワークフローで実際に使用する lightsail: アクション（上のオペレーション表に記載）だけを許可してください。
• シークレット — environment の値はデプロイ仕様に保存され、get-container-service-deployments で読み取れます。また、独立したシークレット注入の仕組みはありません。そのため、コンテナが必要とする認証情報はそこに設定する必要があります。必要なものだけを渡してください。値がパスワード、トークン、API キー、接続文字列などの認証情報に相当する場合は、デプロイ前に必ずユーザーに警告し、判断を委ねてください。選択肢の一つは、値を自ら復号するアプリケーションを使うことです。その場合、デプロイ仕様には暗号文を格納し、キーはイメージに含めます。これらの値や、それらを含む get-container-service-deployments のレスポンスを、ユーザーに提示したり、いかなる成果物にも出力またはログ記録したりしないでください。
• 公開範囲 — エンドポイントは AWS 管理証明書を使用した HTTPS のみで、Shield Standard が一般的なネットワーク層の DDoS を自動的に防御します。インターネットから到達できるのは publicEndpoint で指定されたコンテナのみです。コンテナサービスにはリクエストのスロットリングや WAF がなく、Lightsail がセキュリティヘッダーを追加することもありません。そのため、入力検証、レート制限、CSP／HSTS／X-Content-Type-Options／X-Frame-Options はすべてアプリケーション側の責任です。
• プライベートネットワークへのアクセス — コンテナは、同じアカウントとリージョンにある他の Lightsail リソースへ、フィルタリングされずにネットワークアクセスできます。また、これを制限する Lightsail ファイアウォールルールもありません。そのリージョンで VPC ピアリングが有効な場合、ユーザー自身の VPC にも同様にアクセスできます。したがって、イメージだけが唯一の制御手段となるため、ユーザーがビルドしていないイメージをデプロイする前に、必ず警告してください。
• 監査 — CloudTrail はすべての Lightsail API 呼び出しを記録します。イベント履歴はデフォルトで有効になっており、証跡を作成すると S3 への継続的な配信が行われます。

トラブルシューティング

デプロイに失敗した場合や URL でサービスが提供されない場合など、問題が発生したときは、 references/troubleshooting.md を読んでください。まずコンテナログを確認し、根本原因を特定してください。