AWS Systems Manager ディストリビューター によるパッケージ配布の全体像を絵に描いて理解してみた

Systems Manager のサービスを触るたび、いろいろ組み合わさっていて、魔境かよ……という思いに駆られます。

コンバンハ、千葉(幸)です。

AWS Systems Manager Distributor では、ソフトウェアをパッケージ化し、マネージドインスタンスに対して効率的に配布することができます。配布するパッケージを一元管理することで、複数のインスタンスにおけるソフトウェアのバージョンを統一化したり、ライフサイクルの管理を行うことが可能となります。

この配布は何によって実現されているのか?関連するリソースは何なのか?を絵(というか図)に描き起こしながら理解を深めていったところ、以下が出来上がりました。

はい。

詰め込み過ぎ感がありますね。

図の中に肝心の「ディストリビューター」っていう文字が出てこないじゃん!と自分でも思いましたが、ディストリビューターとは機能であり、概念であり、そしてまた一つの真実であり、常にあなたのすぐ側に寄り添っています。さっそく私たちの親愛なる友人の姿を確認していきましょう。

目次

マネージドインスタンス

ディストリビューターによる配布対象となるのはマネジードインスタンスです。 EC2 インスタンスのほか、オンプレミスのサーバもマネージドインスタンスとすることができます。

マネージドインスタンス内には SSM エージェントが稼働しており、ディストリビューターにより配布されるパッケージのインストール・更新などは SSM エージェントによって行われることとなります。

マネージドインスタンスとして Systems Manager の管理対象となるにはいくつか条件が必要ですが、特に重要な点は以下の通りです。

  • SSM エージェントが導入されていること
  • SSM エンドポイントに疎通可能であること
  • EC2 インスタンスの場合 IAM インスタンスプロファイルがアタッチされ必要な権限が付与されていること

詳細は以下を参照してください。

ディストリビューターによる配布の対象となるインスタンスは、以下のような方式で選択することができます。

  • インスタンス ID で個別に指定
  • 付与されているタグで指定
  • リソースグループで指定
  • 全台を指定(スケジュールで実行する場合のみ)

配布を実行する際に SSM エージェントが実行した内容を S3 や CloudWatch Logs に出力することが可能ですが、そのために必要な権限は、インスタンスに適用された IAM ロールで定義されている必要があります。

SSM ドキュメント

SSM ドキュメントは、マネージドインスタンスで Systems Manager が実行するアクションを定義する JSON または YAML 形式のドキュメントです。

複数のタイプが存在し、それぞれ使用される Systems Manager の機能が異なります。

  • コマンドドキュメント
  • オートメーションドキュメント
  • パッケードキュメント
  • セッションドキュメント
  • ポリシードキュメント
  • Change Calendar ドキュメント

AWS Systems Manager ドキュメント - AWS Systems Manager

ディストリビューターによる配布においては、パッケージドキュメントコマンドドキュメントが関連します。

パッケージドキュメント

パッケージドキュメントは、インストール可能なソフトウェア、アセットや、インストールを実行するスクリプトなどをパッケージ化したものです。

ディストリビューターにおいてはメインとなるコンポーネントと言えるでしょう。ここで定義した内容が、後続で説明する機能によってマネージドインスタンスに届けられ、インストール・更新などが実行されることになります。

パッケージドキュメントは AWS が提供しているものがあるほか、カスタマーが独自に作成することもできます。作成する場合の手順については以下のエントリに書きましたので、あわせてご参照ください。

コマンドドキュメント

コマンドドキュメントは、Run Command や ステートマネージャー によってマネージドインスタンスに対して実行が命令されるコマンドの内容を定義したドキュメントです。

こちらも AWS が管理するものとカスタマーが作成できるものに分かれますが、ディストリビューターに関連するものは AWS が管理する AWS-ConfigureAWSPackage というドキュメントです。

こちらのドキュメントの内訳はこのようになっています。

{
  "schemaVersion": "2.0",
  "description": "Install or uninstall a Distributor package. You can install the latest version, default version, or a version of the package you specify. Packages provided by AWS such as AmazonCloudWatchAgent, AwsEnaNetworkDriver, and AWSPVDriver are also supported.",
  "parameters": {
    "action": {
      "description": "(Required) Specify whether or not to install or uninstall the package.",
      "type": "String",
      "allowedValues": [
        "Install",
        "Uninstall"
      ]
    },
    "installationType": {
      "description": "(Optional) Specify the type of installation. Uninstall and reinstall: The application is taken offline until the reinstallation process completes. In-place update: The application is available while new or updated files are added to the installation.",
      "type": "String",
      "allowedValues": [
        "Uninstall and reinstall",
        "In-place update"
      ],
      "default": "Uninstall and reinstall"
    },
    "name": {
      "description": "(Required) The package to install/uninstall.",
      "type": "String",
      "allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:(package|document)\\/[a-zA-Z0-9/:.\\-_]{1,128}$|^[a-zA-Z0-9/:.\\-_]{1,128}$"
    },
    "version": {
      "description": "(Optional) The version of the package to install or uninstall. If you don’t specify a version, the system installs the latest published version by default. The system will only attempt to uninstall the version that is currently installed. If no version of the package is installed, the system returns an error.",
      "type": "String",
      "default": ""
    }
  },
  "mainSteps": [
    {
      "action": "aws:configurePackage",
      "name": "configurePackage",
      "inputs": {
        "name": "{{ name }}",
        "action": "{{ action }}",
        "installationType": "{{installationType}}",
        "version": "{{ version }}"
      }
    }
  ]
}

パラメータとして幾つかの値を引き渡す必要があり、その内容に応じてディストリビューターによる配布を行なった際の挙動が変わります。

名前 必須/オプション 概要
action 必須 インストールを行うかアンインストールを行うか
InstallationType オプション 更新の手法についてアンインストールして再インストールするかインプレースでアップデートするか
name 必須 配布するパッケージドキュメント名
version オプション パッケージドキュメント内のアセットに複数のバージョンがあった場合どれを適用するか

コマンドドキュメント AWS-ConfigureAWSPackage に引き渡されたパラメータによって、どのパッケージドキュメントのどういった内容をどう適用するかが定義されている、という立て付けになります。

Run Command

Run Command によって、マネージドインスタンスに対してコマンドドキュメントを実行することができます。

ディストリビューターを1回限りで実行する際には、この Run Command を使用することになります。

実行の際には以下の項目を指定することができます。

Systems Manager Run Command を使用するコマンドの実行 - AWS Systems Manager

  • ドキュメント
    • 先述の通り、 AWS-ConfigureAWSPackage です
  • パラメータ
    • 先ほど確認した通りです
    • パッケージドキュメントの指定はここで行います
  • ターゲット
    • 以下の方式で指定することができます
      • 特定のタグが付与されたインスタンス
      • インスタンスIDで直接指定
      • リソースグループ
  • コメント
    • コマンドの実行履歴を参照する際に確認できるメモです
  • タイムアウト
    • コマンド実行の全体が失敗するまでに待機する秒数です
  • レートの制御
    • 同時実行
      • コマンドを同時実行するインスタンス数または割合です
    • エラーのしきい値
      • コマンド全体を停止するエラー数のしきい値です
      • インスタンス数または割合で指定します
  • 出力オプション
    • コマンド出力先を指定します
      • S3 バケット
      • CloudWatch Logs ロググループ
  • SNS 通知
    • コマンドの実行状態に関する通知を受け取れます
      • 進行中
      • 成功
      • 失敗
      • タイムアウト
      • キャンセル

ステートマネージャー

ステートマネージャーはスケーラブルな設定管理サービスであり、マネージドインスタンスを定義された状態に保つプロセスを自動化します。

ディストリビューターをスケジュールで実行する際にはステートマネージャーを利用することになります。

ステートマネージャーではアソシエーションというリソースを作成し、マネージドインスタンスのあるべき状態を定義します。アソシエーションを定義すると、裏側ではコマンドが呼び出されます。

アソシエーションの作成時に設定できる項目は Run Command のものと似ています。差異を中心に取り上げます。

AWS Systems Manager ステートマネージャー - AWS Systems Manager

  • 名前
    • アソシエーション名です。
  • ドキュメント(Run Command と同じ)
  • パラメータ(Run Command と同じ)
  • ターゲット
    • 「マネージドインスタンス全体」の指定が可能です
  • スケジュール
    • CRON 式もしくは Rate 式で指定が可能です
  • コンプライアンスの重要度
    • コンプライアンスにレポートする重要度を指定できます
      • 非常事態
      • 高い
      • ミディアム
      • 低い
  • レート制御(Run Command と同じ)
  • 出力オプション
    • S3 バケットへの出力のみ対応しています

Run Command ではユーザーが指定できた「コメント」ですが、アソシエーションでは明示的に指定はできません。アソシエーションにより実行されたコマンドにはアソシエーションIDがコメントとして挿入されます。

Run Command やステートマネージャーを利用したディストリビューションの実行例は以下のエントリで記載しましたのであわせてご覧ください。ここでは AWS 管理のパッケージドキュメントの配布を行なっています。

終わりに

AWS Systems Manager ディストリビューターの全体像について確認しました。Systems Manager の他のサービスを組み合わせながら、パッケージの配布という機能を実現していることが分かりましたね。

改めてお腹いっぱいになりそうな絵を見ておきましょう。

ディストリビューター分からない……怖い……という方の理解の一助になれば幸いです。私はまだちょっと怖いです。

AWS Systems Manager Distributor - AWS Systems Manager

以上、千葉(幸)がお送りしました。