この記事について

JAWS-UG CLI専門支部 #81 Amazon EC2 Systems Manager 入門で実施するハンズオン用の手順書です。

前提条件

必要な権限

作業にあたっては、以下の権限を有したIAMユーザもしくはIAMロールを利用してください。

EC2 Systems Manager(ssm)のフルコントロール権限
EC2のフルコントロール権限
CloudFormationの関するフルコントロール権限
IAMの関するフルコントロール権限
Configの関するフルコントロール権限
S3の関するフルコントロール権限
SNSの関するフルコントロール権限

0. 準備

0.1. リージョンを指定

ハンズオンでは東京リージョンを利用しますが、必要に応じて他のリージョンに変更してご利用ください。（東京リージョンを他の検証目的で利用している、など）

コマンド

export AWS_DEFAULT_REGION="ap-northeast-1"

0.2. 資格情報を確認

コマンド

aws configure list

インスタンスプロファイルを設定したEC2インスタンスでアクセスキーを設定せずに実行した場合、以下のようになります。

結果

      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                <not set>             None    None
access_key     ****************QSAA         iam-role
secret_key     ****************c1xY         iam-role
    region                us-west-2              env    AWS_DEFAULT_REGION

0.3. バージョン確認

コマンド

aws --version

結果

（可能な限り最新版を利用しましょう）

0.4. バージョンアップ（必要に応じて）

コマンド

sudo pip install -U awscli

1. マネージドインスタンスの確認

作成したEC2インスタンスがマネージドインスタンスとして認識されていることを確認します。

SSM Agentの動作要件は以下の通りです。

コマンド

aws ssm describe-instance-information \
    --query "InstanceInformationList[?InstanceId==\`${INSTANCE_ID}\`]"

結果

[
    {
        "IsLatestVersion": false,
        "ComputerName": "WIN-NU3L7UBOQD9.WORKGROUP",
        "PingStatus": "Online",
        "InstanceId": "i-*****************",
        "IPAddress": "10.0.0.111",
        "ResourceType": "EC2Instance",
        "AgentVersion": "2.0.562.0",
        "PlatformVersion": "6.3.9600",
        "PlatformName": "Microsoft Windows Server 2012 R2 Standard",
        "PlatformType": "Windows",
        "LastPingDateTime": 1490878364.139
    }
]

正常に認識されていない場合、EC2インスタンスを再起動してください。

それでも正常に認識されてない場合には、「インスタンスプロフィルがアタッチされていること」「IAMロール（インスタンスプロファイル）に適切なポリシーがアタッチされていること」を確認してください。

2. AWS管理コマンドを実行する

手順書の検証時点でSSM Agentにバグがあるもようで、アップデートを実施すると後述するソフトウェアインベントリの収集が正常に機能しない可能性があります。この手順は、リソースの削除前に実施してみてください。

EC2Configは、Windows ServerのAMIに含まれる管理ツールです。

詳細については、以下のドキュメントを参照してください。

EC2Config サービスを使用した Windows インスタンスの設定

2.1. EC2Configを更新する

ドキュメント名の指定

コマンド

DOCUMENT_NAME="AWS-UpdateEC2Config"

ドキュメントの確認

ドキュメントの実行時に指定できるパラメータを確認できます。

コマンド

aws ssm describe-document \
    --name ${DOCUMENT_NAME}

結果

{
    "Document": {
        "Status": "Active",
        "Hash": "b45b8ffa5ac627fcc8c0e555678bb317c523f1ae847ef0de25d6115c8d729d6c",
        "Name": "AWS-UpdateEC2Config",
        "Parameters": [
            {
                "DefaultValue": "",
                "Type": "String",
                "Name": "version",
                "Description": "(Optional) A specific version of the EC2Config service to install. If not specified, the service will be updated to the latest version."
            },
            {
                "DefaultValue": "false",
                "Type": "String",
                "Name": "allowDowngrade",
                "Description": "(Optional) Allow the EC2Config service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version."
            }
        ],
        "DocumentType": "Command",
        "PlatformTypes": [
            "Windows"
        ],
        "DocumentVersion": "1",
        "HashType": "Sha256",
        "CreatedDate": 1487117202.214,
        "Owner": "Amazon",
        "SchemaVersion": "1.2",
        "DefaultVersion": "1",
        "LatestVersion": "1",
        "Description": "Update the EC2Config service to the latest version or specify an older version."
    }
}

ドキュメントで実行される処理の内容を確認できます。

詳細は、以下のドキュメントを確認してください。

Systems Manager Documents

コマンド

aws ssm get-document \
    --name ${DOCUMENT_NAME}

結果

{
    "Content": "{\n    \"schemaVersion\": \"1.2\",\n    \"description\": \"Update the EC2Config service to the latest version or specify an older version.\",\n    \"parameters\": {\n        \"version\": {\n            \"default\": \"\",\n            \"description\": \"(Optional) A specific version of the EC2Config service to install. If not specified, the service will be updated to the latest version.\",\n            \"type\": \"String\"\n        },\n        \"allowDowngrade\": {\n            \"default\": \"false\",\n            \"description\": \"(Optional) Allow the EC2Config service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version.\",\n            \"type\": \"String\",\n            \"allowedValues\": [\n                \"true\",\n                \"false\"\n            ]\n        }\n    },\n    \"runtimeConfig\": {\n        \"aws:updateAgent\": {\n            \"properties\": {\n                \"agentName\": \"Ec2Config\",\n                \"source\": \"https://s3.ap-northeast-1.amazonaws.com/aws-ssm-ap-northeast-1/manifest.json\",\n                \"allowDowngrade\": \"{{ allowDowngrade }}\",\n                \"targetVersion\": \"{{ version }}\"\n            }\n        }\n    }\n}\n",
    "Name": "AWS-UpdateEC2Config"
}

パラメータを確認

コマンド

cat << ETX

    INSTANCE_ID: ${INSTANCE_ID}
    ROLE_ARN_FOR_NOTIFICATION: ${ROLE_ARN_FOR_NOTIFICATION}
    SNS_TOPIC_ARN_FOR_EC2: ${SNS_TOPIC_ARN_FOR_EC2}

ETX

結果


    INSTANCE_ID: i-*****************
    ROLE_ARN_FOR_NOTIFICATION: arn:aws:iam::************:role/NotificationForEC2SystemsManager
    SNS_TOPIC_ARN_FOR_EC2: arn:aws:sns:ap-northeast-1:************:ec2-topic

コマンドの実行

※マネジメントコンソールの実行画面でコマンドを生成することも可能です。

コマンド

aws ssm send-command \
    --document-name "${DOCUMENT_NAME}" \
    --instance-ids ${INSTANCE_ID} \
    --parameters '{"allowDowngrade":["false"]}' \
    --timeout-seconds 600 \
    --service-role-arn ${ROLE_ARN_FOR_NOTIFICATION} \
    --notification-config NotificationArn="${SNS_TOPIC_ARN_FOR_EC2}",NotificationEvents="Success",NotificationType="Command"

結果

{
    "Command": {
        "Comment": "",
        "Status": "Pending",
        "MaxErrors": "0",
        "Parameters": {
            "allowDowngrade": [
                "false"
            ]
        },
        "ExpiresAfter": 1490879945.768,
        "ServiceRole": "arn:aws:iam::************:role/NotificationForEC2SystemsManager",
        "DocumentName": "AWS-UpdateEC2Config",
        "TargetCount": 1,
        "OutputS3BucketName": "",
        "NotificationConfig": {
            "NotificationArn": "arn:aws:sns:ap-northeast-1:************:ec2-topic",
            "NotificationEvents": [
                "Success"
            ],
            "NotificationType": "Command"
        },
        "CompletedCount": 0,
        "Targets": [],
        "StatusDetails": "Pending",
        "ErrorCount": 0,
        "OutputS3KeyPrefix": "",
        "RequestedDateTime": 1490879345.768,
        "CommandId": "********-****-****-****-************",
        "InstanceIds": [
            "i-*****************"
        ],
        "MaxConcurrency": "50"
    }
}

実行結果の確認

直近の1件の結果を表示します。

StatusがSuccessとなっています。

コマンド

aws ssm list-command-invocations \
    --query "sort_by(CommandInvocations,&RequestedDateTime)[-1]"

結果

{
    "Comment": "",
    "Status": "Success",
    "CommandPlugins": [],
    "ServiceRole": "arn:aws:iam::************:role/NotificationForEC2SystemsManager",
    "InstanceId": "i-*****************",
    "DocumentName": "AWS-UpdateEC2Config",
    "NotificationConfig": {
        "NotificationArn": "arn:aws:sns:ap-northeast-1:************:ec2-topic",
        "NotificationEvents": [
            "All"
        ],
        "NotificationType": "Command"
    },
    "StatusDetails": "Success",
    "StandardOutputUrl": "",
    "StandardErrorUrl": "",
    "InstanceName": "",
    "CommandId": "********-****-****-****-************",
    "RequestedDateTime": 1490349229.375
}

実行結果の確認（SNS）

成功している場合、設定したメールアドレス宛にsuatusが"Success"となっているメールが送信されています。
受信されていることを確認してください。

2.2. 任意のPowerShellコマンドを実行する

ドキュメント名の指定

コマンド

DOCUMENT_NAME="AWS-RunPowerShellScript"

ドキュメントの確認

コマンド

aws ssm describe-document \
    --name ${DOCUMENT_NAME}

結果

{
    "Document": {
        "Status": "Active",
        "Sha1": "6ed0a59dfeb7e40913899b2342aec27035a76167",
        "Hash": "6ed0a59dfeb7e40913899b2342aec27035a76167",
        "Name": "AWS-RunPowerShellScript",
        "Parameters": [
            {
                "Type": "StringList",
                "Name": "commands",
                "Description": "(Required) Specify the commands to run or the paths to existing scripts on the instance."
            },
            {
                "DefaultValue": "",
                "Type": "String",
                "Name": "workingDirectory",
                "Description": "(Optional) The path to the working directory on your instance."
            },
            {
                "DefaultValue": "3600",
                "Type": "String",
                "Name": "executionTimeout",
                "Description": "(Optional) The time in seconds for a command to be completed before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours)."
            }
        ],
        "DocumentType": "Command",
        "PlatformTypes": [
            "Windows",
            "Linux"
        ],
        "DocumentVersion": "1",
        "HashType": "Sha1",
        "CreatedDate": 1450125626.387,
        "Owner": "Amazon",
        "SchemaVersion": "1.2",
        "DefaultVersion": "1",
        "LatestVersion": "1",
        "Description": "Run a PowerShell script or specify the paths to scripts to run."
    }
}

コマンド

aws ssm get-document \
    --name ${DOCUMENT_NAME}

結果

{
    "Content": "{\n    \"schemaVersion\":\"1.2\",\n    \"description\":\"Run a PowerShell script or specify the paths to scripts to run.\",\n    \"parameters\":{\n        \"commands\":{\n            \"type\":\"StringList\",\n            \"description\":\"(Required) Specify the commands to run or the paths to existing scripts on the instance.\",\n            \"minItems\":1,\n            \"displayType\":\"textarea\"\n        },\n        \"workingDirectory\":{\n            \"type\":\"String\",\n            \"default\":\"\",\n            \"description\":\"(Optional) The path to the working directory on your instance.\",\n            \"maxChars\":4096\n        },\n        \"executionTimeout\":{\n            \"type\":\"String\",\n            \"default\":\"3600\",\n            \"description\":\"(Optional) The time in seconds for a command to be completed before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours).\",\n            \"allowedPattern\":\"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)\"\n        }\n    },\n    \"runtimeConfig\":{\n        \"aws:runPowerShellScript\":{\n            \"properties\":[\n                {\n                    \"id\":\"0.aws:runPowerShellScript\",\n                    \"runCommand\":\"{{ commands }}\",\n                    \"workingDirectory\":\"{{ workingDirectory }}\",\n                    \"timeoutSeconds\":\"{{ executionTimeout }}\"\n                }\n            ]\n        }\n    }\n}\n",
    "Name": "AWS-RunPowerShellScript"
}

コマンドの実行

コマンド

aws ssm send-command \
    --document-name ${DOCUMENT_NAME} \
    --instance-ids ${INSTANCE_ID} \
    --parameters '{"commands":["import-module servermanager","add-windowsfeature web-server -includeallsubfeature"],"executionTimeout":["3600"]}' \
    --timeout-seconds 600 \
    --output-s3-bucket-name ${BUCKET_NAME} \
    --service-role-arn ${ROLE_ARN_FOR_NOTIFICATION} \
    --notification-config NotificationArn="${SNS_TOPIC_ARN_FOR_EC2}",NotificationEvents="Success",NotificationType="Command"

実行結果の確認

直近の1件の結果を表示します。

コマンド

aws ssm list-command-invocations \
    --query "sort_by(CommandInvocations,&RequestedDateTime)[-1]"

結果

{
    "Comment": "",
    "Status": "Success",
    "CommandPlugins": [],
    "ServiceRole": "arn:aws:iam::************:role/NotificationForEC2SystemsManager",
    "InstanceId": "i-*****************",
    "DocumentName": "AWS-RunPowerShellScript",
    "NotificationConfig": {
        "NotificationArn": "arn:aws:sns:ap-northeast-1:************:ec2-topic",
        "NotificationEvents": [
            "Success"
        ],
        "NotificationType": "Command"
    },
    "StatusDetails": "Success",
    "StandardOutputUrl": "https://s3-ap-northeast-1.amazonaws.com/ec2-systems-manager-************/********-****-****-****-************/i-*****************/awsrunPowerShellScript/0.aws%3ArunPowerShellScript/stdout",
    "StandardErrorUrl": "https://s3-ap-northeast-1.amazonaws.com/ec2-systems-manager-************/********-****-****-****-************/i-*****************/awsrunPowerShellScript/0.aws%3ArunPowerShellScript/errout",
    "InstanceName": "",
    "CommandId": "********-****-****-****-************",
    "RequestedDateTime": 1490879834.044
}

実行結果の確認（SNS）

成功している場合、設定したメールアドレス宛にsuatusが"InProgress"および"Success"となっている2通のメールが送信されています。

実行結果の確認（S3）

コマンド

COMMAND_ID=$(aws ssm list-command-invocations \
    --query "sort_by(CommandInvocations,&RequestedDateTime)[-1].CommandId" \
    --output text) \
    && echo ${COMMAND_ID}

コマンド

OBJECT_KEY=$(aws s3 ls ${BUCKET_NAME} \
    --recursive \
    | grep ${COMMAND_ID} \
    | grep "stdout" \
    | awk '{print $4}') \
    && echo ${OBJECT_KEY}

結果

2017-03-24 10:54:12        330 ********-****-****-****-************/i-*************/awsrunPowerShellScript/0.awsrunPowerShellScript/stdout

環境によっては文字化けします。

必要に応じて、マネジメントコンソールからファイルをダウンロードして確認してください。

コマンド

aws s3 cp s3://${BUCKET_NAME}/${OBJECT_KEY} stdout && cat stdout

結果

download: s3://ec2-systems-manager-************/********-****-****-****-************/i-*****************/awsrunPowerShellScript/0.awsrunPowerShellScript/stdout to ./stdout

Success Restart Needed Exit Code      Feature Result
------- -------------- ---------      --------------
True    No             Success        {ASP.NET 4.5, .NET Framework 3.5 (.NET...

（一部省略）

以上