View a markdown version of this page

AWSSupport-ConfigureEC2Metadata - Amazon Systems Manager Automation Runbook Reference
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

AWSSupport-ConfigureEC2Metadata

Description

This runbook helps you configure instance metadata service (IMDS) options for Amazon Elastic Compute Cloud (Amazon EC2) instances. Using this runbook, you can configure the following:

  • Enforce the use of IMDSv2 for instance metadata.

  • Configure the HttpPutResponseHopLimit value.

  • Allow or deny instance metadata access.

For more information about instance metadata, see Configuring the Instance Metadata Service in the Amazon EC2 User Guide.

Run this Automation (console)

Document type

Automation

Owner

Amazon

Platforms

Linux, macOS, Windows

Parameters

  • AutomationAssumeRole

    Type: String

    Description: (Optional) The Amazon Resource Name (ARN) of the Amazon Identity and Access Management (IAM) role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user that starts this runbook.

  • EnforceIMDSv2

    Type: String

    Valid values: required | optional | unchanged

    Default: optional

    Description: (Optional) Enforce IMDSv2. If you choose required, the Amazon EC2 instance will only use IMDSv2. If you choose optional, you can choose between IMDSv1 and IMDSv2 for metadata access. Specify unchanged to keep the current value instead of applying the default.

    Important

    If you enforce IMDSv2, applications that use IMDSv1 might not function correctly. Before enforcing IMDSv2, make sure your applications that use IMDS are upgraded to a version that support IMDSv2. For information about Instance Metadata Service Version 2 (IMDSv2), see Configuring the Instance Metadata Service in the Amazon EC2 User Guide.

  • HttpPutResponseHopLimit

    Type: Integer

    Valid values: 0-64

    Default: 0

    Description: (Optional) The desired HTTP PUT response hop limit value (1-64) for instance metadata requests. This value controls the number of hops that the PUT response can traverse. To prevent the response from traveling outside of the instance, specify 1 for the parameter value. Specify 0 to keep the current value.

  • InstanceId

    Type: String

    Description: (Required) The ID of the Amazon EC2 instance whose metadata settings you want to configure.

  • MetadataAccess

    Type: String

    Valid values: enabled | disabled | unchanged

    Default: enabled

    Description: (Optional) Allow or deny instance metadata access in the Amazon EC2 instance. If you specify disabled, all other parameters will be ignored and the metadata access will be denied for the instance. Specify unchanged to keep the current value instead of applying the default. If the current value is disabled, unchanged also ignores all other parameters.

Required IAM permissions

The AutomationAssumeRole parameter requires the following actions to use the runbook successfully.

  • ec2:DescribeInstances

  • ec2:ModifyInstanceMetadataOptions

  • ssm:GetAutomationExecution

  • ssm:StartAutomationExecution

Document Steps

  1. getCurrentMetadataOptions - Gets the current metadata options of the instance and resolves unchanged to the current value.

  2. branchOnMetadataAccess - Branches automation based on the value of MetadataAccess parameter.

  3. disableMetadataAccess - Calls the ModifyInstanceMetadataOptions API action to disable metadata endpoint access.

  4. branchOnHttpPutResponseHopLimit - Branches automation based on the value of HttpPutResponseHopLimit parameter.

  5. maintainHopLimitAndConfigureImdsVersion - If HttpPutResponseHopLimit is 0, maintains current hop limit and changes other metadata options.

  6. waitBeforeAssertingIMDSv2State - Waits 30 seconds before asserting IMDSv2 status.

  7. setHopLimitAndConfigureImdsVersion - If HttpPutResponseHopLimit is greater than 0, configures the metadata options using the given input parameters.

  8. castHttpPutResponseHopLimit - Casts the value of the HttpPutResponseHopLimit parameter to a string.

  9. waitBeforeAssertingHopLimit - Waits 30 seconds before asserting metadata options.

  10. assertHopLimit - Asserts the HttpPutResponseHopLimit property is set to the value you specified.

  11. branchOnIMDSv2Option - Branches verification based on the value of EnforceIMDSv2 parameter.

  12. assertIMDSv2IsOptional - Asserts HttpTokens value set to optional.

  13. assertIMDSv2IsEnforced - Asserts HttpTokens value set to required.

  14. waitBeforeAssertingMetadataState - Waits 30 seconds before asserting the metadata state is disabled.

  15. assertMetadataIsDisabled - Asserts metadata is disabled.

  16. describeMetadataOptions - Gets the metadata options after the changes you've specified have been applied.

Outputs

getCurrentMetadataOptions.InitialState

getCurrentMetadataOptions.InitialMetadataAccess

getCurrentMetadataOptions.InitialIMDSv2

getCurrentMetadataOptions.InitialHttpPutResponseHopLimit

describeMetadataOptions.State

describeMetadataOptions.MetadataAccess

describeMetadataOptions.IMDSv2

describeMetadataOptions.HttpPutResponseHopLimit