AWS Systems Manager Distributorでパッケージをインストールするには、配布対象EC2からAWS管理S3バケットへの到達性が必要

2026.05.01
 はじめにAWS Systems Manager Distributor は、ソフトウェアや設定用ファイルなどをパッケージとして登録し、Systems Manager 経由でマネージドインスタンスに配布できる機能です。

Run Command や Automation と組み合わせることで、対象インスタンスに一括でインストール処理を実行できます。
Distributor の概要については、以下の AWS Black Belt 資料が分かりやすいです。
https://pages.awscloud.com/rs/112-TZM-766/images/AWS-Black-Belt_2023_AWS-SystemsManager-Distributor_0922_v1.pdf
今回は、Distributor を使って EC2 にソフトウェアを配布する構成を検証しました。

その中で、AWSドキュメントの手順に明確に記載されていませんが、Distributor パッケージをインストールするには、配布対象の EC2 から AWS 管理 S3 バケットへ到達できる必要があることが分かりました。
具体的には、以下のような AWS 管理 S3 バケットです。
https://aws-ssm-document-attachments-<リージョン名>.s3.<リージョン名>.amazonaws.com
一方で、今回の検証環境では、EC2 のインスタンスプロファイルに追加の s3:GetObject 権限は付与していません。

インスタンスプロファイルは AmazonSSMManagedInstanceCore のみでしたが、S3 へのネットワーク的な到達経路がある状態では Distributor パッケージのインストールに成功しました。
そのため、少なくとも今回の条件では、必要だったのは 配布対象 EC2 から AWS 管理 S3 バケットへのネットワーク到達性 であり、追加の S3 権限ではありませんでした。
今回は、この必要性について実際に試した結果を整理します。
 前提条件今回の検証では、Distributor 用のファイル一式はすでに用意済みとします。
Distributor パッケージ作成時は、ZIP ファイルと JSON マニフェストファイルを S3 にアップロードして作成します。
To create a package using the advanced workflow, you upload package files and a JSON manifest file to an Amazon S3 bucket.

高度なワークフローを使用してパッケージを作成するには、パッケージファイルと JSON マニフェストファイルを Amazon S3 バケットにアップロードします

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/distributor-working-with-packages-create.html
また、今回の検証環境では以下を設定済みとします。
対象 EC2 はマネージドインスタンス
EC2 のインスタンスプロファイルは AmazonSSMManagedInstanceCore のみ
 DistributorとAWS-ConfigureAWSPackageの関係Distributor は、ソフトウェアや設定用ファイルをパッケージドキュメントとして作成、管理、配布する仕組みです。

Black Belt の資料でも、Distributor の構成要素として manifest ファイルやインストール可能なアセットを含むパッケージドキュメントが説明されています。
また、Distributor で作成したパッケージは、Systems Manager 上では SSM ドキュメントとして扱われます。

そのため、実際に EC2 にパッケージをインストールする時は、Run Command から AWS-ConfigureAWSPackage を実行し、Distributor で作成したパッケージドキュメントを指定します。
つまり、以下のような関係です。
Distributor
パッケージドキュメントを作成する
バージョンを管理する

AWS-ConfigureAWSPackage
Distributor で作成したパッケージドキュメントを EC2 にインストールする

今回の検証では、SSM Distributor で以下の通り、名前は test-1 で、アップロードした S3 バケットを指定してパッケージを作成しました。
その後、AWS-ConfigureAWSPackage から、Distributor で作成したこのパッケージを指定してインストールします。

今回利用した name パラメータの arn:aws:ssm:ap-northeast-1:111111111111:document/test-1 は、Distributor で作成したパッケージドキュメントに対応する SSM ドキュメント ARN です。
以降では、東京リージョンのAWS CloudShellを開き、以下のコマンドを使って、配布対象 EC2 から AWS 管理 S3 バケットへ到達できない場合と、到達できる場合の違いを確認します。
aws ssm send-command \
  --document-name "AWS-ConfigureAWSPackage" \
  --instance-ids "i-07eac737140e347e5" \
  --parameters '{
    "action":["Install"],
    "installationType":["Uninstall and reinstall"],
    "name":["arn:aws:ssm:ap-northeast-1:111111111111:document/test-1"],
    "version":["1.0.1"]
  }'
 S3へ到達できない場合まず、S3 への到達経路が無い状態で試しました。
対象 EC2 から、AWS 管理 S3 バケットに対して以下を実行します。
curl -I --connect-timeout 10 https://aws-ssm-document-attachments-ap-northeast-1.s3.ap-northeast-1.amazonaws.com
結果はタイムアウトでした。
curl: (28) Connection timed out after 10001 milliseconds
この状態で AWS-ConfigureAWSPackage を実行すると、Run Command のステップ2で失敗しました。

そのときのログは以下です。
failed to download installation package reliably, https://aws-ssm-document-attachments-ap-northeast-1.s3.ap-northeast-1.amazonaws.com/.../AmazonLinux.zip
Download failed due to Get "https://aws-ssm-document-attachments-ap-northeast-1.s3.ap-northeast-1.amazonaws.com/.../AmazonLinux.zip": dial tcp 3.5.157.242:443: i/o timeout
このログから、aws-ssm-document-attachments-ap-northeast-1.s3.ap-northeast-1.amazonaws.com 上のインストールパッケージを取得しようとして失敗していることが分かります。
 S3へ到達できる場合次に、S3 のゲートウェイ型 VPC エンドポイントを作成し、EC2 から AWS 管理 S3 バケットへ到達できるようにしました。
同じ curl を実行すると、今度は 403 が返りました。
aws ssm send-command \
  --document-name "AWS-RunShellScript" \
  --instance-ids "i-07eac737140e347e5" \
  --parameters '{
    "commands": [
      "curl -I --connect-timeout 10 https://aws-ssm-document-attachments-ap-northeast-1.s3.ap-northeast-1.amazonaws.com"
    ]
  }'
HTTP/1.1 403 Forbidden
x-amz-bucket-region: ap-northeast-1
Server: AmazonS3
403 はアクセス拒否ですが、今回の確認ポイントは ネットワーク的に到達できているか なので、この結果で問題ありません。
続いて、同じ EC2 に対して Distributor package をインストールすると成功しました。
aws ssm send-command \
  --document-name "AWS-ConfigureAWSPackage" \
  --instance-ids "i-07eac737140e347e5" \
  --parameters '{
    "action":["Install"],
    "installationType":["Uninstall and reinstall"],
    "name":["arn:aws:ssm:ap-northeast-1:111111111111:document/test-1"],
    "version":["1.0.1"]
  }'
get-command-invocation の結果は以下です。
{
  "CommandId": "67e375da-b288-48fd-9971-acdbfcb20227",
  "InstanceId": "i-07eac737140e347e5",
  "DocumentName": "AWS-ConfigureAWSPackage",
  "Status": "Success",
  "StatusDetails": "Success"
}
この結果から、AWS 管理 S3 バケットに到達できる状態であれば、Distributor package のインストールまで成功することが確認できました。
 なぜS3への到達性が必要なのかここまでの結果から、Distributor パッケージのインストール時には、配布対象の EC2 が AWS 管理 S3 バケット上のパッケージ実体を取得しに行くことが分かります。
AWS 公式ドキュメントの Distributor トラブルシューティングでは、VPC を使用している場合、対象リージョンの AWS-ConfigureAWSPackage ドキュメントを含む AWS マネージド S3 バケットへアクセスできないことが、エラー原因の一つとして記載されています。
原因 2: VPC を使用するとき、ターゲットとする AWS リージョンのドキュメント AWS-ConfigureAWSPackage を含む AWS マネージド S3 バケットへのアクセス権を、IAM インスタンスプロファイルに付与しませんでした

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/distributor-troubleshooting.html
また、SSM Agent の技術詳細でも、Systems Manager の各種オペレーションの中で、SSM Agent が AWS マネージド S3 バケットにアクセスする場合があることが説明されています。
さまざまな Systems Manager のオペレーションを実行する過程で、AWS Systems Manager Agent (SSM Agent) は多数の Amazon Simple Storage Service (Amazon S3) バケットにアクセスします。

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/ssm-agent-technical-details.html#ssm-agent-minimum-s3-permissions
さらに、Systems Manager の VPC エンドポイントに関するドキュメントでも、インスタンスがインターネットへアクセスできない構成では、S3 エンドポイントや AWS マネージド S3 バケットへのアクセスを考慮する必要があることが説明されています。
VPC エンドポイントポリシーでは、少なくとも「SSM Agent と AWS マネージド S3 バケットとの通信」に記載されている Amazon S3 バケットへのアクセスを許可する必要があります。

https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-vpc.html
今回の検証でも、S3 への到達経路が無い状態では AWS-ConfigureAWSPackage の実行時に、以下の AWS 管理 S3 バケットへの接続がタイムアウトして失敗しました。
aws-ssm-document-attachments-<リージョン名>.s3.<リージョン名>.amazonaws.com
一方で、S3 のゲートウェイ型 VPC エンドポイントを作成し、配布対象 EC2 から AWS 管理 S3 バケットへネットワーク的に到達できる状態にすると、Distributor パッケージのインストールは成功しました。
このため、Distributor パッケージのインストールでは、配布対象 EC2 から AWS 管理 S3 バケットへのネットワーク到達性が必要です。

一方で、今回の条件では、EC2 インスタンスプロファイルに追加の s3:GetObject 権限を付与しなくてもインストールに成功しました。
 権限次に気になるのは、EC2 のインスタンスプロファイルに追加の s3:GetObject 権限が必要かどうかです。
AWS 公式ドキュメントには、VPC を使用する場合に AWS マネージド S3 バケットへのアクセス許可が必要である旨の記載があります。
一方で、SSM Agent のリリースノートを見ると、バージョン 3.3.2299.0 で aws:configurePackage plugin の s3:GetObject 依存が削除されています。
Remove dependency on s3:GetObject for aws:configurePackage plugin

aws:configurePackage plugin における s3:GetObject 依存を削除

https://github.com/aws/amazon-ssm-agent/releases/tag/3.3.2299.0
今回の検証環境では、EC2 インスタンスプロファイルには AmazonSSMManagedInstanceCore のみを付与しており、追加の s3:GetObject 権限は付与していませんでした。
それでも、S3 へのネットワーク的な到達経路がある状態では Distributor パッケージのインストールに成功しました。
そのため、少なくとも今回の条件では、追加の s3:GetObject 権限は不要でした。
AWS-ConfigureAWSPackage を利用
配布対象 EC2 から AWS 管理 S3 バケットへネットワーク的に到達可能
aws:configurePackage plugin が s3:GetObject に依存しない SSM Agent バージョンを利用
つまり、今回の検証で必要だったのは、追加の S3 権限ではなく、配布対象 EC2 から AWS 管理 S3 バケットへのネットワーク到達性でした。
 まとめAWS Systems Manager Distributor でパッケージをインストールする場合、配布対象 EC2 から AWS 管理 S3 バケットへの到達性が必要でした。
S3 への到達経路が無い状態では、AWS-ConfigureAWSPackage の実行時に aws-ssm-document-attachments-<リージョン名>.s3.<リージョン名>.amazonaws.com への接続がタイムアウトし、インストールに失敗しました。
一方で、S3 のゲートウェイ型 VPC エンドポイントを作成して到達できるようにすると、インストールは成功しました。
なお、今回の条件では、EC2 インスタンスプロファイルに追加の s3:GetObject 権限を付与しなくてもインストールできました。
Distributor を利用する場合は、まず配布対象 EC2 から AWS 管理 S3 バケットへ到達できるかを確認するとよさそうです。