Work with instance user data
You can use instance user data to customize your instances. When you launch an instance, you can store parameters or scripts as user data. Any scripts in user data are run when you launch the instance. You can view user data as an instance attribute. You can also view user data from your instance through the Instance Metadata Service (IMDS).
Considerations
-
User data is treated as opaque data: what you specify is what you get back upon retrieval. It is up to the instance to interpret and act on user data.
-
User data must be base64-encoded. Depending on the tool or SDK that you're using, the base64-encoding might be performed for you. For example:
The Amazon EC2 console can perform the base64-encoding for you or accept base64-encoded input.
AWS CLI version 2 performs base64-encoding of binary parameters for you by default. AWS CLI version 1 performs the base64-encoding of the
--user-dataparameter for you.The AWS SDK for Python (Boto3) performs base64-encoding of the
UserDataparameter for you.
-
User data is limited to 16 KB, in raw form, before it is base64-encoded. The size of a string of length n after base64-encoding is ceil(n/3)*4.
-
User data must be base64-decoded when you retrieve it. If you retrieve the data using instance metadata or the console, it's decoded for you automatically.
-
If you stop an instance, modify its user data, and start the instance, the updated user data is not run automatically when you start the instance. With Windows instances, you can configure settings so that updated user data scripts are run one time when you start the instance or every time you reboot or start the instance.
-
User data is an instance attribute. If you create an AMI from an instance, the instance user data is not included in the AMI.
Specify instance user data at launch
You can specify user data when you launch an instance. For console directions, see Specify instance user data at launch. For a Linux example that uses the AWS CLI, see User data and the AWS CLI. For a Windows example that uses the Tools for Windows PowerShell, see User data and the Tools for Windows PowerShell.
Modify instance user data
You can modify user data for instances with an EBS root volume. The instance must be in the stopped state. For console directions, see View and update the instance user data. For a Linux example that uses the AWS CLI, see modify-instance-attribute. For a Windows example that uses the Tools for Windows PowerShell, see User data and the Tools for Windows PowerShell.
Retrieve instance user data from your instance
To retrieve user data from an instance, use one of the following URIs. To retrieve user data using the IPv6 address, you must enable it, and the instance must be an instance built on the AWS Nitro System in a subnet that supports IPv6.
IPv4
http://169.254.169.254/latest/user-dataIPv6
http://[fd00:ec2::254]/latest/user-dataA request for user data returns the data as it is (content type
application/octet-stream). If the instance does not have any user
data, the request returns 404 - Not Found.
Example: Retrieve comma-separated text
This example retrieves user data that was specified as comma-separated text.
Example: Retrieve a script
This example retrieves user data that was specified as a script.
Retrieve instance user data from your computer
You can retrieve user data for an instance from your own computer. For console directions, see View and update the instance user data. For an example that uses the AWS CLI, see User data and the AWS CLI. For an example that uses the Tools for Windows PowerShell, see User data and the Tools for Windows PowerShell .
