How do I use the UpgradeWindowsAWSDrivers runbook to upgrade or repair storage and network AWS drivers on an EC2 Windows instance?

Short description

The AWSSupport-UpgradeWindowsAWSDrivers runbook uses the SSM Agent to install the latest AWS drivers. If the runbook can't contact the SSM Agent, then the runbook installs the drivers offline, if explicitly requested.

Note: Both the online and offline upgrades create an Amazon Machine Image (AMI) before the installation starts. This AMI persists after the runbook completes installation. You must secure access to the AMI or delete it. The online method restarts the target instance as part of the upgrade process. For the offline method, you must stop and start the EC2 instance.

Resolution

Prerequisites

• Make sure that your AWS Identify and Access Management (IAM) user or role has the permissions listed in Required IAM permissions.
• For instances that connect to Systems Manager using Amazon Virtual Private Cloud (Amazon VPC) endpoints, use this runbook in only the us-east-1 AWS Region. If the instance uses an internet or transit gateway to connect to Systems Manager without VPC endpoints, then the runbook works in all AWS Regions.
• This runbook fails on a domain controller. To update AWS PV drivers on a domain controller, see Upgrade a Domain Controller (AWS PV Upgrade).

Run the AWSSupport-UpgradeWindowsAWSDrivers runbook

1. Open the Systems Manager console.

2. In the navigation pane, choose Documents.

3. In the search bar, type AWSSupport-UpgradeWindowsAWSDrivers.

4. Select the AWSSupport-UpgradeWindowsAWSDrivers document.

5. Choose Execute automation.

6. Enter the following input parameters:

   • AllowOffline (Optional): To install the drivers offline if the online installation fails, set this value to True.
     Note: The offline method requires a stop and start of the EC2 instance. Data stored in instance store volumes is lost when the instance is stopped. And, If you're not using an Elastic IP address, then the public IP address changes. For more information, see What happens when you stop an instance.
   • AutomationAssumeRole (Optional): Enter the ARN of the IAM role that allows Automation to perform actions for you. If a role isn't specified, then Automation uses the permissions of the user that starts the runbook.
   • ForceUpgrade (Optional): If you want to allow the offline drivers upgrade to proceed even though your instance already has the latest drivers, then set this value to True.
   • InstanceId (Required): Enter the instance ID of your EC2 instance for Windows Server.
   • SubnetId (Optional): For offline installation, enter the subnet ID for the rescue instance used to perform the offline drivers upgrade. If a subnet ID isn't specified, then Automation creates a new VPC to act as the rescue instance.

7. Required IAM permissions: The target EC2 instance must have an IAM role that includes the following permissions:

   • ssm:StartAutomationExecution: This permission runs the automation.
   • ssm:SendCommand: This permission sends the command to the target instance.
   • ssm:GetAutomationExecution: This permission reads the automation output.

   Note: It's a best practice to use the Automation IAM role AmazonSSMAutomationRole to run this automation. Or, to provide these permissions, attach the AmazonSSMManagedInstanceCore Amazon managed policy to your IAM role. For more information, see Use IAM to configure roles for Automation.

8. Choose Execute. The runbook performs the following steps:

   • aws:assertAwsResourceProperty: Verifies that the input instance is a Windows instance.
   • aws:assertAwsResourceProperty: Verifies that he input instance is a managed instance. If it is a managed instance, then the online upgrade starts. If not, then the offline upgrade is evaluated.

   (Online upgrade) If the input instance is a managed instance

   • aws:createImage: Creates an AMI backup.
   • aws:createTags: Tags the AMI backup.
   • aws:runCommand: Installs the ENA network driver using the AWS-ConfigureAWSPackage.
   • aws:runCommand: Installs the NVMe driver using the AWS-ConfigureAWSPackage.
   • aws:runCommand: Installs the AWS PV driver using the AWS-ConfigureAWSPackage.

   (Offline upgrade) If the input instance is not a managed instance

   • aws:assertAwsResourceProperty: If the AllowOffline flag is set to True, then the offline upgrade starts. If not, then the automation ends.
   • aws:changeInstanceState: Stops the source instance.
   • aws:changeInstanceState: Force stops the source instance.
   • aws:createImage: Creates an AMI backup of the source instance.
   • aws:createTags: Tags the AMI backup of the source instance.
   • aws:executeAwsApi: Turns on ENA for the instance.
   • aws:assertAwsResourceProperty: Asserts the ForceUpgrade flag.
   • (Forced offline upgrade) If ForceUpgrade is set to True, then the aws:executeAutomation invokes AWSSupport-StartEC2RescueWorkflow with the force driver upgrade script. This workflow installs the drivers regardless of the current installed version.
   • (Offline upgrade) If ForceUpgrade is set to False, then aws:executeAutomation invokes the AWSSupport-StartEC2RescueWorkflow with the upgrade drivers script.

After the runbook completes, you see the following output:

• preUpgradeBackup.ImageId: An AMI that persists after the automation completes. You must secure access to the AMI or delete it.
• preOfflineUpgradeBackup.ImageId: An AMI that persists after the automation completes. You must secure access to the AMI or delete it.
• installAwsEnaNetworkDriverOnInstance.Output: Contains information about the AWS ENA drivers.
• installAWSNVMeOnInstance.Output: Contains information about the AWS NVMe drivers.
• installAWSPVDriverOnInstance.Output: Contains information about the AWS PV drivers.
• upgradeDriversOffline.Output
• forceUpgradeDriversOffline.Output

Note: To help you troubleshoot, manage, and reduce costs on your AWS resources, AWS Support maintains a subset of the Systems Manager provided predefined runbooks. These runbooks are prefixed with "AWSSupport-" or "AWSPremiumSupport-".

Related information

Run this automation (console)

Run an automation

Setting up automation

AWS Support Automation Workflows (SAW).