developersIO
Run Command で SSM Agent をダウングレードする手順を検証してみた

Run Command で SSM Agent をダウングレードする手順を検証してみた

SSM Agentを古いバージョンへダウングレードしようとしたら想定外の挙動に直面しました。その原因と解決方法、そしてマニフェストを活用した手順について紹介します。
AWS Systems Manager（SSM）AWS Systems Manager Run CommandAmazon EC2Windows Server
2026.08.08

はじめに

SSM Agent を意図的に古いバージョンへダウングレードして動作確認をしたい、という場面があります。
例えば、本番環境で SSM Agent のバージョン更新を行う前に、検証環境で古いバージョンの環境を再現して影響範囲を確認したいといった場面などです。

今回、Run Commandのコマンドドキュメント（AWS-UpdateSSMAgent） を用いて、EC2 インスタンス（Windows Server）上の SSM Agent を、最新版（記事執筆時点）の 3.3.4851.0 から古いバージョンの 3.0.1124.0 へダウングレードすることを試みました。

結論

  • SSM Agent のバージョン3.3.4851.0 → 3.0.1124.0は一気にダウングレードができず、中間バージョン 3.1.2282.0を経由する必要があった
  • 中間バージョンの候補の中にも 非推奨（deprecated）なバージョンが混在しており、どのバージョンを指定するかは別途 SSM マニフェストを確認して判断する必要がある

検証環境

  • OS: Windows Server 2019
  • SSM Agent: 3.3.4851.0 → 3.0.1124.0（ダウングレード方向）
  • リージョン: ap-northeast-1
  • 実行方法: AWS-UpdateSSMAgent document を Run Command で実行

1. Run Command でダウングレードを実行

3.3.4851.0 → 3.0.1124.0への更新を試みます。
なお、SSM Agent のダウングレード時は、allowDowngrade というパラメーターを明示的に true にしない限り、バリデーションの時点で拒否されるので、忘れずにtrue にしましょう。

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/run-command-tutorial-update-software.html

実行結果

Successfully downloaded manifest
Successfully downloaded updater version 3.3.4851.0
Updating amazon-ssm-agent from 3.3.4851.0 to 3.0.1124.0
before downgrading to 3.0.1124.0, first downgrade to any version from 3.1.821.0 to 3.2.923.0
Failed to update amazon-ssm-agent to 3.0.1124.0

実行結果には、「3.0.1124.0 に落とす前に、まず 3.1.821.0 〜 3.2.923.0 のどこかを経由してください」というメッセージが出力されました。

なぜ一気に飛べないのか

このメッセージはドキュメントには明記されていませんが、SSM Agent のソースコード（amazon-ssm-agent の GitHub リポジトリ、agent/updateutil/updateutil.go ）に手がかりがあります。

https://github.com/aws/amazon-ssm-agent/blob/mainline/agent/updateutil/updateutil.go

抜粋

// IsIdentityRuntimeConfigSupported returns true if source agent version is greater than 3.1.282.0, any error defaults to false
// this logic is required to ensure that updater does not rely on an old runtime config if an agent has been downgraded
// from a version that supported identity runtimeconfig and also to skip the runtimeconfig check when we know it does not exist

（和訳）
// IsIdentityRuntimeConfigSupported は、ソースエージェントのバージョンが 3.1.282.0 より大きい場合に true を返し、エラーが発生した場合はデフォルトで false を返します
// このロジックは、identity runtimeconfig をサポートしていたバージョンからエージェントがダウングレードされた場合に、updater が古いランタイム設定に依存しないようにするために必要です 
// また、runtimeconfig が存在しないことが分かっている場合に runtimeconfig のチェックをスキップするためにも必要です

こちらには、「エージェントが持つランタイム設定の形式が、バージョン3.1.282.0を境に変わっている」とあります。
つまり、この境界をまたいで一気にダウングレードすると、新しい形式で書かれたランタイム設定を古いバージョンのエージェントがうまく読めなくなる可能性がある、ということが読み取れます。

そのため、境界をまたぐ大きなダウングレードは、一旦境界のあたりを経由させてから、さらに古いバージョンへ落とす手順が必要となると言えそうです。

2. 中間バージョンを指定する

1 の実行結果で提示された範囲のうち、まずは上限の 3.2.923.0 を中間バージョンとして指定して、再度 Run Command を実行します。

Successfully downloaded manifest
Successfully downloaded updater version 3.3.4851.0
Updating amazon-ssm-agent from 3.3.4851.0 to 3.2.923.0
amazon-ssm-agent version 3.2.923.0 is deprecated/inactive, update skipped

結果はエラーではなく、deprecated/inactive のため skipped（正常終了扱い）となりました。

どのバージョンが 非推奨 あるいは 推奨 なのか、マニフェストで確認する

マニフェスト（ssm-agent-manifest.json）を確認すると、特定のバージョンにStatus というフィールドがあり、Deprecated や Inactive が入っている場合と、空欄（＝Active）の場合があることが分かりました。

https://s3.ap-northeast-1.amazonaws.com/amazon-ssm-ap-northeast-1/ssm-agent-manifest.json

powershell で実行

$region = "ap-northeast-1"
$manifest = Invoke-RestMethod -Uri "https://s3.$region.amazonaws.com/amazon-ssm-$region/ssm-agent-manifest.json"

$agent = $manifest.Packages | Where-Object { $_.Name -eq "amazon-ssm-agent" }
$winFile = $agent.Files | Where-Object { $_.Name -like "*windows-amd64*" }

# 1件だけプロパティを確認してフィールド名を特定する
$winFile.AvailableVersions | Select-Object -First 1 | Format-List *

マニフェスト例

CheckSum : de0ab9687a768bab027ce8c6c3498924f69bed11c0000d296d09886cb5cee706
Version  : 1.2.251.0
Status   : Inactive

この Status フィールドを使って、3 で提示されたバージョンの範囲を一覧表示します。

$winFile.AvailableVersions |
  Where-Object { [version]$_.Version -ge [version]"3.1.821.0" -and [version]$_.Version -le [version]"3.2.923.0" } |
  Sort-Object { [version]$_.Version } |
  Select-Object Version, Status |
  Format-Table -AutoSize

出力結果

Version    Status
-------    ------
3.1.821.0  Deprecated
3.1.941.0  Deprecated
3.1.1004.0 Deprecated
3.1.1045.0
3.1.1080.0
3.1.1141.0
3.1.1188.0
3.1.1208.0
3.1.1260.0
3.1.1374.0
3.1.1446.0 Deprecated
3.1.1476.0
3.1.1511.0
3.1.1575.0
3.1.1625.0
3.1.1634.0
3.1.1732.0
3.1.1767.0
3.1.1856.0
3.1.1927.0
3.1.2144.0
3.1.2282.0
3.2.183.0  Deprecated
3.2.286.0  Deprecated
3.2.345.0  Deprecated
3.2.419.0  Deprecated
3.2.532.0  Deprecated
3.2.574.0  Deprecated
3.2.582.0  Deprecated
3.2.815.0  Deprecated
3.2.923.0  Deprecated

結果を見ると、3.2.x 系はすべて Deprecated でした。つまり最初に選んだ 3.2.923.0 は、非推奨版だったということが分かります。一方 3.1.x 系には Status が空欄（Active）のバージョンが複数残っています。

この中から、範囲の上限に近く、かつ Active なバージョンとして 3.1.2282.0 を選び、再度 Run Command を実行します。

3. 2段階でのダウングレード実施

1段目：3.3.4851.0 → 3.1.2282.0

Successfully downloaded manifest
Successfully downloaded updater version 3.3.4851.0
Updating amazon-ssm-agent from 3.3.4851.0 to 3.1.2282.0
Successfully downloaded https://s3.ap-northeast-1.amazonaws.com/amazon-ssm-ap-northeast-1/amazon-ssm-agent/3.3.4851.0/amazon-ssm-agent-windows-amd64.zip
Successfully downloaded https://s3.ap-northeast-1.amazonaws.com/amazon-ssm-ap-northeast-1/amazon-ssm-agent/3.1.2282.0/amazon-ssm-agent-windows-amd64.zip
Initiating amazon-ssm-agent update to 3.1.2282.0
amazon-ssm-agent updated successfully to 3.1.2282.0

成功しました。

2段目：3.1.2282.0 → 3.0.1124.0

1段目が正常に完了したことを確認したら、そのまま同じ手順で最終目標のバージョンへ進めます。

Successfully downloaded manifest
Successfully downloaded updater version 3.3.4851.0
Updating amazon-ssm-agent from 3.1.2282.0 to 3.0.1124.0
Successfully downloaded https://s3.ap-northeast-1.amazonaws.com/amazon-ssm-ap-northeast-1/amazon-ssm-agent/3.1.2282.0/amazon-ssm-agent-windows-amd64.zip
Successfully downloaded https://s3.ap-northeast-1.amazonaws.com/amazon-ssm-ap-northeast-1/amazon-ssm-agent/3.0.1124.0/amazon-ssm-agent-windows-amd64.zip
Initiating amazon-ssm-agent update to 3.0.1124.0
amazon-ssm-agent updated successfully to 3.0.1124.0

2段目も成功しました。
SSM フリートマネージャーを確認すると、バージョン3.0.1124.0 で起動されていることが確認できました。

まとめ

Run Command で SSM Agent のバージョンをダウングレードする際に、一発でダウングレードできない場合があります。
その際は、SSM マニフェストを確認して、どのバージョンを経由したらよいかを確認の上で、段階的なダウングレードを進める必要があることが分かりました。
注意点として、Run Command の出力で提示された範囲内のバージョンであっても、非推奨版である可能性もあるため、範囲内を一覧化して Status が空欄のバージョンを選ぶと良いことが分かりました。

参考資料

クラスメソッドオペレーションズ株式会社について

クラスメソッドグループのオペレーション企業です。
運用・保守開発・サポート・情シス・バックオフィスの専門チームが、IT・AIをフル活用した「しくみ」を通じて、お客様の業務代行から課題解決や高付加価値サービスまでを提供するエキスパート集団です。
当社は様々な職種でメンバーを募集しています。
「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、クラスメソッドオペレーションズ株式会社 コーポレートサイト をぜひご覧ください。※2026年1月 アノテーション㈱から社名変更しました

この記事をシェアする

関連記事

AlmaLinux OS の EC2 インスタンスで amazon-ssm-agent の更新が失敗する原因と対処法
片方 裕人
2026.04.13
【小ネタ】 SSM エージェントを古いバージョンにダウングレードしてみた
片方 裕人
2025.08.10
Windows EC2 のユーザーデータで AWS Systems Manager API を使用する際の注意点
Shiina Yuichi
2025.02.12
SSM Automation Runbook "AWSEC2-CloneInstanceAndUpgradeWindows" 実行前の前提条件チェックスクリプトを作ってみた
片方 裕人
2026.01.16