SSM Agent に関する技術的な詳細を知る

このトピックの情報を使用して、AWS Systems Manager Agent (SSM Agent) を実装し、エージェントの仕組みを理解するのに役立ちます。

トピック

• SSM Agent バージョン 3.2.x.x 認証情報の動作
• SSM Agent 認証情報の優先順位
• ローカル ssm-user アカウントについて
• SSM Agentと Instance Metadata Service (IMDS)
• SSM Agent を最新の状態に維持
• SSM Agent インストールディレクトリが変更、移動、削除されていないことの確認
• AWS リージョン による SSM Agent のローリング更新
• SSM Agent と AWS マネージド S3 バケットとの通信
• SSM Agent がプリインストールされている AMIs を見つける
• Linux 用 EC2 インスタンスで SSM Agent を使用する
• macOS 用 EC2 インスタンスで SSM Agent を使用する
• Windows Server 用 EC2 インスタンスで SSM Agent を使用する
• SSM Agent ステータスの確認とエージェントの起動
• SSM Agent バージョン番号の確認
• SSM Agent ログの表示
• SSM Agent を介してルートレベルコマンドへのアクセスを制限する
• SSM Agent への更新の自動化
• SSM Agent 通知にサブスクライブする

SSM Agent バージョン 3.2.x.x 認証情報の動作

インスタンスが、Quick Setup のデフォルトのホスト管理設定を使用してオンボーディングされた場合、SSM Agent は一時的な認証情報のセットを /var/lib/amazon/ssm/credentials (Linux と macOS の場合)、または %PROGRAMFILES%\Amazon\SSM\credentials (Windows Server の場合) に格納します。一時的な認証情報には、デフォルトのホスト管理設定で選択した IAM ロールに指定した許可が含まれます。Linux では、これらの認証情報にアクセスできるのは、root アカウントだけです。Windows Server では、SYSTEM アカウントとローカル管理者のみがこれらの認証情報にアクセスできます。

SSM Agent 認証情報の優先順位

このトピックは SSM Agent がリソースにアクションを実行するためにどのようにアクセス許可が付与されるか、重要な情報について説明します。

注記

エッジデバイスのサポートは少し異なります。AWS IoT Greengrass コアソフトウェアを使用できようにエッジデバイスを設定、AWS Identity and Access Management (IAM) サービスロールを設定、AWS IoT Greengrass を使って SSM Agent をデバイスに展開する必要があります。詳細については、「Systems Manager を利用したエッジデバイスの管理」を参照してください。

SSM Agent がマシンにインストールされている場合、Systems Manager サービスと通信するには許可が必要です。Amazon Elastic Compute Cloud (Amazon EC2) インスタンスでは、このようなアクセス許可は、インスタンスにアタッチされたインスタンスプロファイルで提供されます。非 EC2 マシンの場合、SSM Agent は通常、必要な許可を共有認証情報ファイルから取得し、/root/.aws/credentials (Linux と macOS) または %USERPROFILE%\.aws\credentials (Windows Server) に保存されています。必要な許可は、ハイブリッドアクティベーションプロセス中にこのファイルに追加されます。

ただし、まれに、SSM Agent がタスクを実行するための許可をチェックする複数の場所に、マシンの許可が追加されてしまうことがあります。

例えば、Systems Manager によって管理されるように EC2 インスタンスを設定したとします。その設定にはインスタンスプロファイルのアタッチが含まれます。しかし、そのインスタンスをデベロッパーまたはエンドユーザーのタスクにも使用し、そのインスタンス に AWS Command Line Interface (AWS CLI) をインストールすることにしました。このインストールでは、インスタンス上の認証情報ファイルに追加のアクセス許可が追加されます。

インスタンスで Systems Manager コマンドを実行すると、SSM Agent は、インスタンスプロファイルではなく認証情報ファイルからの認証情報など、使用する想定とは異なる認証情報を使用しようとすることがあります。これは、SSM Agent がデフォルトの資格情報プロバイダーチェーンに規定された順序で資格情報を検索するためです。

注記

Linux と macOS では、SSM Agent はルートユーザーとして実行されます。したがって、このプロセスで SSM Agent が検索する環境変数と認証情報ファイルは、ルートユーザーのみのものです (/root/.aws/credentials)。SSM Agent は、認証情報の検索中に、インスタンス上の他のユーザーの環境変数や認証情報ファイルを参照しません。

デフォルトのプロバイダーチェーンは、次の順序で認証情報を検索します。

1. 環境変数 (設定されている場合) (AWS_ACCESS_KEY_ID および AWS_SECRET_ACCESS_KEY)。

2. ハイブリッド環境のアクティベーションや AWS CLI のインストールなどによって提供されるアクセス許可を持つ共有認証情報ファイル (Linux と macOS の場合は $HOME/.aws/credentials、Windows Server の場合は %USERPROFILE%\.aws\credentials)。

3. Amazon Elastic Container Service (Amazon ECS) タスク定義または RunTask API オペレーションを使用するアプリケーションが存在する場合、タスクの AWS Identity and Access Management (IAM) ロール。

4. Amazon EC2 インスタンスにアタッチされたインスタンスプロファイル。

5. デフォルトのホスト管理構成用に選択された IAM ロール。

関連情報については、次のトピックを参照してください。

• EC2 インスタンスのインスタンスプロファイル — Systems Manager に必要なインスタンスのアクセス許可を設定する

• ハイブリッドアクティベーション – ハイブリッドアクティベーションを作成して、Systems Manager にノードを登録する

• AWS CLI クレデンシャルファイル – AWS Command Line Interface ユーザーガイドの「設定と認証情報ファイルの設定」

• デフォルトの認証情報プロバイダーチェーン – AWS SDK for Go デベロッパーガイドの「認証情報の指定」

  注記

  AWS SDK for Go デベロッパーガイドのこのトピックでは、SDK for Go に関するデフォルトのプロバイダーチェーンについて説明します。ただし、SSM Agent の認証情報の評価にも同じ原則が適用されます。

ローカル ssm-user アカウントについて

SSM Agent バージョン 2.3.50.0 以降では、エージェントは ssm-user という名前のローカルユーザーアカウントを作成し、/etc/sudoers.d ディレクトリ (Linux と macOS) または、管理者グループ (Windows Server) に追加します。2.3.612.0 より前のエージェントバージョンでは、アカウントはインストール後に SSM Agent が最初に起動または再起動するときに作成されます。バージョン 2.3.612.0 以降では、ssm-user アカウントは、インスタンスでセッションが最初に開始されたときに作成されます。この ssm-user は、AWS Systems Manager の一機能である Session Manager でセッションが開始されたときのデフォルトの OS ユーザーです。ssm-user を特権の少ないグループに移動するか、sudoers ファイルを変更することで、アクセス許可を変更できます。SSM Agent がアンインストールされるときに、ssm-user アカウントはシステムから削除されません。

Windows Server では、SSM Agent は各セッションの開始時に ssm-user アカウントの新しいパスワードの設定を処理します。Linux マネージドインスタンスで ssm-user にはパスワードは設定されていません。

SSM Agent 2.3.612.0 バージョンから、ssm-user アカウントは、ドメインコントローラーとして使用されている Windows Server マシンに自動的には作成されません。Session Manager ドメインコントローラーで Windows Server を使用するには、ssm-user アカウントが存在しない場合は手動でアカウントを作成し、ドメイン管理者のアクセス許可をユーザーに割り当てます。

重要

ssm-user アカウントを作成するには、インスタンスに添付されたインスタンスプロファイルによって、必要なアクセス許可が付与される必要があります。詳細については、「ステップ 2: Session Managerのインスタンスのアクセス権限の確認または追加」を参照してください。

SSM Agentと Instance Metadata Service (IMDS)

Systems Manager の正常な機能は、EC2 インスタンスメタデータに左右されます。Systems Manager は、Instance Metadata Service (IMDSv1 および IMDSv2) のバージョン 1 またはバージョン 2 を使用して、インスタンスメタデータにアクセスできます。インスタンスはインスタンスメタデータサービスの IPv4 アドレスにアクセスできる必要があります: 169.254.169.254。詳細については、「Amazon EC2 ユーザーガイド」の「Instance metadata and user data」(インスタンスメタデータとユーザーデータ) を参照してください。

SSM Agent を最新の状態に維持

新しい機能が Systems Manager に追加されるか、既存の機能が更新されると必ず、更新されたバージョンの SSM Agent がリリースされます。最新バージョンのエージェントを使用しないと、マネージドノードが Systems Manager の各種機能を使用できなくなる可能性があります。このため、マシン上で SSM Agent を最新状態に維持するプロセスを自動化することをお勧めします。詳細については、SSM Agent への更新の自動化 を参照してください。GitHub の「SSM Agent リリースノート」ページをサブスクライブすると、SSM Agent の更新に関する通知を受け取ることができます。

注記

新しい機能が Systems Manager に追加されるか、既存の機能が更新されると必ず、更新されたバージョンの SSM Agent がリリースされます。最新バージョンのエージェントを使用しないと、マネージドノードが Systems Manager の各種機能を使用できなくなる可能性があります。このため、マシン上で SSM Agent を最新状態に維持するプロセスを自動化することをお勧めします。詳細については、SSM Agent への更新の自動化 を参照してください。GitHub の「SSM Agent リリースノート」ページをサブスクライブすると、SSM Agent の更新に関する通知を受け取ることができます。

デフォルトで SSM Agentが含まれている Amazon Machine Images (AMIs) は、最新バージョンの SSM Agentで更新されるまでに最大 2 週間かかります。SSM Agent に対するさらに頻繁な自動更新を設定することをお勧めします。

SSM Agent インストールディレクトリが変更、移動、削除されていないことの確認

SSM Agent は /var/lib/amazon/ssm/ (Linux と macOS) および %PROGRAMFILES%\Amazon\SSM\ (Windows Server) にインストールされます。これらのインストールディレクトリには、認証情報ファイル、プロセス間通信 (IPC) 用リソース、オーケストレーションフォルダなど、SSM Agent が使用する重要なファイルやフォルダが含まれています。インストールディレクトリ内のものは変更、移動、削除しないでください。そうでないと、SSM Agent が正しく機能しなくなる可能性があります。

AWS リージョン による SSM Agent のローリング更新

GitHub リポジトリで SSM Agent 更新が使用可能になった後、更新されたバージョンは各 AWS リージョン に異なる時間にロールアウトされ、すべてにロールアウトされるまで、最大 2 週間かかることがあります。このため、リージョンに SSM Agent の新しいバージョンをデプロイしようとすると、「Unsupported on current platform (現在のプラットフォームでサポートされていません)」または「updating amazon-ssm-agent to an older version, please turn on allow downgrade to proceed (amazon-ssm-agent を古いバージョンに更新しています。ダウングレードを許可してください)」というエラーが表示されることがあります。

使用可能な SSM Agent のバージョンを確認するには、curl コマンドを実行します。

グローバルダウンロードバケットで利用できるエージェントのバージョンを表示するには、次のコマンドを実行します。

curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/VERSION

特定のリージョンで使用可能なエージェントのバージョンを表示するには、次のコマンドを実行します。region を(米国東部 (オハイオ) リージョンでは us-east-2 などの作業しているリージョンに置き換えます。

curl https://s3.region.amazonaws.com/amazon-ssm-region/latest/VERSION

VERSION コマンドなしでブラウザで curl ファイルを直接開くこともできます。

SSM Agent と AWS マネージド S3 バケットとの通信

さまざまな Systems Manager のオペレーションを実行する過程で、AWS Systems Manager Agent (SSM Agent) は多数の Amazon Simple Storage Service (Amazon S3) バケットにアクセスします。これらの S3 バケットはパブリックにアクセス可能です。デフォルトで、SSM Agent は HTTP 呼び出しを使用してこれに接続します。

ただし、Systems Manager のオペレーションで仮想プライベートクラウド (VPC) エンドポイントを使用している場合は、Systems Manager の Amazon Elastic Compute Cloud (Amazon EC2) インスタンスプロファイル、またはハイブリッドおよびマルチクラウド環境の非 EC2 マシンのサービスロールで、明示的なアクセス許可を付与する必要があります。それ以外の場合、リソースからこれらのパブリックバケットにアクセスすることはできません。

VPC エンドポイントの使用中にこれらのバケットへのマネージドノードアクセスを許可するには、カスタム Amazon S3 許可ポリシーを作成し、それをインスタンスプロファイル (EC2 インスタンスの場合) またはサービスロール (非 EC2 ノードの場合) にアタッチします。

Systems Manager オペレーションで仮想プライベートクラウド (VPC) エンドポイントを使用する方法については、「Systems Manager のために VPC エンドポイントを使用して EC2 インスタンスのセキュリティを強化する」を参照してください。

注記

これらのアクセス許可では、SSM Agent が必要とする AWS マネージドバケットへのアクセスのみが付与されます。また、その他の Amazon S3 オペレーションに必要なアクセス許可は付与されません。また、独自の S3 バケットへのアクセス許可は付与されません。

詳細については、次のトピックを参照してください。

• Systems Manager に必要なインスタンスのアクセス許可を設定する

• ハイブリッドおよびマルチクラウド環境で Systems Manager に必要な IAM サービスロールを作成する

必要なバケットアクセス許可

次の表は、各 S3 バケットについて説明しています。SSM Agent は Systems Manager のオペレーションで、このようなバケットにアクセスする必要があるかもしれません。

注記

region は、米国東部 (オハイオ) リージョンの us-east-2 のように、AWS Systems Manager でサポートされている AWS リージョン の識別子を表します。サポートされている region 値の一覧については、「Amazon Web Services 全般のリファレンス」の「Systems Manager サービスエンドポイント」にある Region 列を参照してください。

SSM Agent が必要とする Amazon S3 のアクセス許可

S3 バケット ARN	説明
arn:aws:s3:::aws-windows-downloads-region/*	Windows Server オペレーティングシステムのみをサポートする一部の SSM ドキュメントに必要です。さらに、AWSEC2-ConfigureSTIG などのクロスプラットフォームサポート用のドキュメントもあります。
arn:aws:s3:::amazon-ssm-region/*	SSM Agent インストールの更新のために必須です。これらのバケットには SSM Agent インストールパッケージ、および AWS-UpdateSSMAgent ドキュメントとプラグインによって参照されるインストールマニフェストが含まれています。これらのアクセス許可が提供されていない場合、SSM Agent は HTTP コールを実行して更新プログラムをダウンロードします。
arn:aws:s3:::amazon-ssm-packages-region/*	2.2.45.0 より前のバージョンの SSM Agent を使用して、SSM ドキュメント AWS-ConfigureAWSPackage を実行するために必要です。
arn:aws:s3:::region-birdwatcher-prod/*	SSM Agent バージョン 2.2.45.0 以降で使用されるディストリビューションサービスへのアクセスが提供されます。このサービスは、AWS-ConfigureAWSPackage ドキュメントを実行するために使用されます。 このアクセス許可は、アフリカ (ケープタウン) リージョン (af-South-1) と欧州 (ミラノ) リージョン (eu-South-1) を除くすべての AWS リージョン で必要です。
arn:aws:s3:::aws-ssm-distributor-file-region/*	SSM Agent バージョン 2.2.45.0 以降で使用されるディストリビューションサービスへのアクセスが提供されます。このサービスは、SSM ドキュメント AWS-ConfigureAWSPackage を実行するために使用されます。 このアクセス許可は、アフリカ (ケープタウン) リージョン (af-south-1) および欧州 (ミラノ) リージョン (eu-south-1) にのみ必要です。
arn:aws:s3:::aws-ssm-document-attachments-region/*	AWS Systems Manager の一機能であり、AWS が所有する Distributor のパッケージが含まれている S3 バケットへのアクセスを提供します。
arn:aws:s3:::patch-baseline-snapshot-region/*	パッチベースラインのスナップショットを含む S3 バケットへのアクセスを提供します。これは、次の SSM ドキュメントのいずれかを使用する場合に必要です。 AWS-RunPatchBaseline AWS-RunPatchBaselineAssociation AWS-RunPatchBaselineWithHooks AWS-ApplyPatchBaseline (レガシーの SSM ドキュメント) 注記 中東 (バーレーン) リージョン (me-south-1) のみ、この S3 バケットでは異なる命名規則が使用されています。この AWS リージョン でのみ、代わりに次のバケットを使用します。 patch-baseline-snapshot-me-south-1-uduvl7q8 アフリカ (ケープタウン) リージョン (af-south-1) のみ、この S3 バケットでは異なる命名規則が使用されています。この AWS リージョン でのみ、代わりに次のバケットを使用します。 patch-baseline-snapshot-af-south-1-tbxdb5b9
Linux と Windows Server マネージドノードの場合: arn:aws:s3:::aws-ssm-region/* macOS の Amazon EC2 インスタンスの場合: arn:aws:s3:::aws-patchmanager-macos-region/*	特定の Systems Manager ドキュメント (SSM ドキュメント) で使用するために必要なモジュールを含む S3 バケットへのアクセスを付与します。例: arn:aws:s3:::aws-ssm-us-east-2/* aws-patchmanager-macos-us-east-2/* 例外 いくつかの AWS リージョン の S3 バケット名は、ARN で示すように、拡張命名規則を使用しています。これらのリージョンでは、代わりに以下の ARN を使用します。 中東 (バーレーン) リージョン (me-south-1): aws-patch-manager-me-south-1-a53fc9dce アフリカ (ケープタウン) リージョン (af-south-1): aws-patch-manager-af-south-1-bdd5f65a9 ヨーロッパ (ミラノ) リージョン (eu-south-1): aws-patch-manager-eu-south-1-c52f3f594 アジアパシフィック (大阪) リージョン (ap-northeast-3): aws-patch-manager-ap-northeast-3-67373598a SSM ドキュメント 以下は、これらのバケットに格納されている一般的に使用される SSM ドキュメントの一部です。 Eclipse arn:aws:s3:::aws-ssm-region/: AWS-RunPatchBaseline AWS-RunPatchBaselineAssociation AWS-RunPatchBaselineWithHooks AWS-InstanceRebootWithHooks AWS-ConfigureWindowsUpdate AWS-FindWindowsUpdates AWS-PatchAsgInstance AWS-PatchInstanceWithRollback AWS-UpdateSSMAgent AWS-UpdateEC2Config Eclipse arn:aws:s3:::aws-patchmanager-macos-region/: AWS-RunPatchBaseline AWS-RunPatchBaselineAssociation AWS-RunPatchBaselineWithHooks AWS-InstanceRebootWithHooks AWS-PatchAsgInstance AWS-PatchInstanceWithRollback

例

次の例は、米国東部 (オハイオ) リージョン (us-east-2) で Systems Manager の使用に必要な S3 バケットへのアクセス権を付与する方法を示しています。ほとんどの場合、VPC エンドポイントを使用する場合にのみ、インスタンスプロファイルまたはサービスロールでこれらのアクセス許可を明示的に指定する必要があります。

重要

このポリシーの特定のリージョンの代わりにワイルドカード文字 (*) を使用しないことをお勧めします。例えば、arn:aws:s3:::aws-ssm-us-east-2/* を使用して、arn:aws:s3:::aws-ssm-*/* は使用しないでください。ワイルドカードを使用すると、アクセスを付与する S3 バケットへのアクセス権が付与される場合があります。複数のリージョンでインスタンスプロファイルを使用する場合は、各リージョンの最初の Statement ブロックを繰り返すことをお勧めします。

{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "s3:GetObject",
                "Resource": [
                    "arn:aws:s3:::aws-windows-downloads-us-east-2/*",
                    "arn:aws:s3:::amazon-ssm-us-east-2/*",
                    "arn:aws:s3:::amazon-ssm-packages-us-east-2/*",
                    "arn:aws:s3:::us-east-2-birdwatcher-prod/*",
                    "arn:aws:s3:::aws-ssm-document-attachments-us-east-2/*",
                    "arn:aws:s3:::patch-baseline-snapshot-us-east-2/*",
                    "arn:aws:s3:::aws-ssm-us-east-2/*",
                    "arn:aws:s3:::aws-patchmanager-macos-us-east-2/*"
                ]
            }
        ]
    }

ハードウェアフィンガープリントを使用したハイブリッドアクティベーションマシンの検証

ハイブリッドおよびマルチクラウド環境で非 EC2 を実行する場合、SSM Agent は多数のシステム属性 (ハードウェアハッシュと呼ばれます) を収集し、これらの属性を使用してフィンガープリントを計算します。フィンガープリントは、エージェントが特定の Systems Manager API に渡す不透明な文字列です。この固有のフィンガープリントは、発信者を特定のハイブリッドアクティベーションマネージドノードに関連付けます。エージェントは、フィンガープリントとハードウェアハッシュをローカルディスク上の Vault と呼ばれる場所に保存します。

エージェントは、マシンが Systems Manager で使用するために登録されると、ハードウェアハッシュとフィンガープリントを計算します。エージェントが RegisterManagedInstance コマンドを送信すると、フィンガープリントが Systems Manager サービスに戻されます。

その後、RequestManagedInstanceRoleToken コマンドを送信するときに、エージェントは Vault 内のフィンガープリントとハードウェアハッシュをチェックして、現在のマシン属性が保存されているハードウェアハッシュと一致することを確認します。現在のマシン属性が Vault に保存されているハードウェアハッシュと一致する場合、エージェントはフィンガープリントを Vault から RegisterManagedInstance に渡し、呼び出しが成功します。

現在のマシン属性が保存されているハードウェアハッシュと一致しない場合、SSM Agent は新しいフィンガープリントを計算し、新しいハードウェアハッシュとフィンガープリントを Vault に保存し、新しいフィンガープリントを RequestManagedInstanceRoleToken に渡します。これにより RequestManagedInstanceRoleToken が失敗し、エージェントは Systems Manager サービスに接続するためのロールトークンを取得できません。

この障害は設計上のものであり、複数のマネージドノードが同じマネージドノードとして Systems Manager サービスと通信することを防ぐための検証手順として使用されます。

現在のマシン属性を Vault に保存されているハードウェアハッシュと比較すると、エージェントは次のロジックを使用して、古いハッシュと新しいハッシュが一致するかどうかを判断します。

• SID (システム/マシン ID) が異なる場合は、一致しません。

• 同じ場合は、IP アドレスが同じであれば一致します。

• それ以外の場合は、一致するマシン属性の割合が計算され、ユーザー設定の類似度しきい値と比較され、一致があるかどうかが判断されます。

類似度のしきい値は、ハードウェアハッシュの一部として Vault に保存されます。

類似度のしきい値は、インスタンスの登録後に次のようなコマンドを使用して設定できます。

Linux マシンの場合:

sudo amazon-ssm-agent -fingerprint -similarityThreshold 1

PowerShell を使用している Windows Server マシンの場合:

cd "C:\Program Files\Amazon\SSM\" `
    .\amazon-ssm-agent.exe -fingerprint -similarityThreshold 1

重要

フィンガープリントの計算に使用されるコンポーネントの 1 つが変更されると、エージェントが休止状態になる可能性があります。この休止状態を回避するには、類似度のしきい値を低い値 (1 など) に設定します。

SSM AgentGitHub での

SSM Agent のソースコードが GitHub に用意されているので、ニーズに応じてエージェントを調整できます。含めることを希望する変更について、プルリクエストを送信することをお勧めします。ただし、Amazon Web Services はこのソフトウェアの変更されたコピーの実行をサポートしていません。