实例自定义数据是指用户上传给实例的脚本、指令或配置文件等数据,可用来完成实例初始化或其他配置,例如实例首次启动时,自动运行服务启动脚本、安装软件、打印日志等。本文介绍如何将自定义数据传入ECS实例、修改自定义数据、如何查看自定义数据等。
实例首次启动时会自动运行自定义数据,部分自定义数据格式还支持在Linux实例每次启动时都运行。详细说明,请参见自定义数据格式及运行频率。
使用限制
实例的网络类型必须为专有网络VPC。
实例必须使用公共镜像或基于公共镜像创建的自定义镜像,且操作系统需为以下类型之一:
Alibaba Cloud Linux、CentOS、CentOS Stream、Ubuntu、SUSE Linux Enterprise Server、Red Hat Enterprise Linux、OpenSUSE、Debian、AlmaLinux、Rocky Linux、Fedora
Windows Server 2008 R2及更高版本
已停售的实例规格中,仅I/O优化实例支持实例自定义数据功能,非I/O优化实例不支持该功能。更多信息,请参见已停售的实例规格。
使用自定义数据
将自定义数据传入ECS实例
准备实例自定义数据。
支持的自定义数据格式、任务被执行频率及其说明,请参见自定义数据格式及运行频率。
重要自定义数据内容可不经过Base64编码,且在未经过Base64编码前的大小不能超过32 KB。
将自定义数据传入ECS实例。
创建新实例时传入:数据会在实例首次启动时、更换操作系统、重新初始化系统盘时被执行。
修改已有实例的自定义数据:数据会在实例更换操作系统、重新初始化系统盘时被执行。
部分自定义数据格式还支持在Linux实例每次重启时被执行。详细说明,请参见自定义数据格式及运行频率。
确保实例处于已停止状态。
重要如果实例的计费方式为按量付费、网络类型为专有网络,停止实例时,停止模式建议选择普通停机模式,选择节省停机模式会因计算资源(vCPU和内存)被回收,再次启动实例时可能因为库存不足导致启动失败。更多信息,请参见节省停机模式。
在实例页面,选择
,然后在用户数据区域输入自定义数据。根据设置的脚本内容验证自定义数据的运行效果。
说明当User-Data执行遇到问题时,可以通过云助手公共命令ACS-ECS-UserData-Check-for-linux.sh来获取失败相关的错误日志。如果返回有错误信息表示脚本执行有问题,如果没有返回错误信息表示执行没有报错,需要排查其他方面。关于云助手公共命令的更多信息,请参见查看和执行公共命令。
例如我们在Linux实例中传入了User-Data脚本,内容如下:
#!/bin/sh echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt
您可以运行
cat userdata_test.txt
命令来查看效果,系统已经向userdata_test.txt
文件写入系统时间。
创建新实例时传入自定义数据
在实例购买页展开高级选项区域,在自定义数据区域输入实例自定义数据。
如果实例自定义数据已进行Base64编码,请勾选输入已采用Base64编码,且在进行Base64编码前自定义数据内容的大小不能超过32 KB。否则,无需勾选,系统会自动对内容进行Base64编码。
修改已有实例的自定义数据
查看实例的自定义数据
自定义数据传入实例后,您可以通过元数据或控制台查看实例的自定义数据信息。
通过元数据获取(普通模式)
Linux实例
curl http://100.100.100.200/latest/user-data
Windows实例
Invoke-RestMethod http://100.100.100.200/latest/user-data
通过元数据获取(加固模式)
假设,设置元数据服务器访问凭证有效期
为180秒。
Linux实例
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:180"` curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/user-data
Windows实例
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "180"} -Method PUT –Uri http://100.100.100.200/latest/api/token Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/user-data
通过控制台获取
确保实例处于已停止状态。
重要如果实例的计费方式为按量付费、网络类型为专有网络,停止实例时,停止模式建议选择普通停机模式,选择节省停机模式会因计算资源(vCPU和内存)被回收,再次启动实例时可能因为库存不足导致启动失败。更多信息,请参见节省停机模式。
在实例页面,选择
,然后在用户数据区域查看已设置的自定义数据。
关于元数据的更多说明,请参见实例元数据。
Linux脚本使用示例
示例一:使用User-Data脚本自定义yum源、NTP服务和DNS服务
示例二:使用User-Data脚本自定义管理员账号
自定义数据格式及运行频率
Linux实例
Linux实例是通过cloud-init组件控制实例的启动行为。在实例首次启动过程中,系统会自动运行自定义数据。实例重启时,自定义数据是否会被执行,由自定义数据的格式决定。
常见的几种Linux实例自定义数据格式如下:
自定义数据格式的详细说明,可参见cloud-init文档User-Data Formats。
如果您的User-Data脚本、Cloud Config数据或Include文件内容的大小超过32 KB,数据类型建议选择Gzip压缩内容。
如果任务需要在实例每次启动时都执行,数据类型建议选择Cloud Config数据或Upstart Job。
User-Data脚本
简介
User-Data脚本传入Linux实例后直接作为Shell脚本执行,且仅在实例首次启动时运行一次。
运行频率
启动实例:仅在实例首次启动时运行一次,重启实例不会再自动运行。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行均以
#!
开头。User-Data脚本示例
#!/bin/sh echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt
示例User-Data脚本的效果是在实例首次启动时,向userdata_test.txt文件写入系统时间。
Cloud Config数据
简介
在Cloud-init中,定义了一系列的功能模块,来完成部分需要执行的任务和配置,例如安装软件包、设置网络等。执行哪些模块及具体的执行逻辑,由Cloud Config数据决定,可从vendordata、自定义数据、内核参数中获取。在创建ECS实例时,用户可自定义Cloud Config数据,指定需要执行的模块和任务,并作为自定义数据提供给实例。实例启动时,cloud-init会读取并解析Cloud Config数据,并按照配置文件中的指示运行对应模块并执行配置任务,自动配置和部署ECS实例。
运行频率
启动实例:Cloud Config数据中的任务是否会被执行,取决于这些任务对应模块的频率设置。各模块的说明,请参见Modules。
频率为once-per-instance:仅在实例首次启动时运行。例如配置的是Apt、Set Passwords等模块,运行频率为once-per-instance,重启实例时不会运行。
频率为always:实例每次启动都运行。例如配置的是Bootcmd、Update Etc Hosts等模块,运行频率为always,实例每次启动都运行。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行为
#cloud-config
,且起始位置不能有空格。必须遵循YAML语法编写内容。
Cloud Config数据示例
#cloud-config apt: primary: - arches: [default] uri: https://us.archive.ubuntu.com/ubuntu/ bootcmd: - echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt
示例Cloud Config数据的效果是修改默认的软件源,并在实例每次启动时向userdata_test.txt文件写入最新的系统时间。
Include文件
简介
通过Include文件指向一个或多个User-Data脚本或Cloud Config数据的链接,多个链接按行分隔。实例启动时,cloud-init会逐个解析并读取链接里的内容。如果在读取某一个链接的内容时出错,则停止读取剩余的链接。
说明您可以通过阿里云对象存储OSS,上传User-Data脚本或Cloud Config数据、获取链接、设置链接有效期等。具体操作,请参见OSS控制台快速入门。
运行频率
启动实例:执行频率由链接里的内容决定。例如,链接的内容为User-Data脚本,则仅在实例首次启动时运行一次;脚本类型链接的内容为Cloud Config数据,则遵循Cloud Config数据的运行频率。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行为
#include
,且起始位置不能有空格。Include文件示例
#include https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.sh
示例Include文件包含一个脚本链接,该脚本为User-Data脚本,则仅在实例首次启动时运行一次。
说明如果您采用Include文件或Gzip压缩内容的方式,需要使用存储服务上传脚本、获取脚本链接、设置链接有效期等操作,推荐您使用阿里云对象存储OSS。具体操作,请参见OSS控制台快速入门。
Gzip压缩内容
简介
如果您的User-Data脚本、Cloud Config数据或Include文件内容的大小超过32 KB,可以采用Gzip压缩内容(
.gz
格式)并做成链接,然后以Include文件的形式输入。cloud-init会自动解压Gzip压缩内容,运行解压后内容的效果和直接传入后运行没有区别。说明您可以通过阿里云对象存储OSS,上传User-Data脚本或Cloud Config数据、获取链接、设置链接有效期等。具体操作,请参见OSS控制台快速入门。
运行频率
启动实例:由脚本类型和模块类型决定。例如,Gzip压缩内容链接的脚本类型为User-Data脚本,则仅在实例首次启动时运行一次。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行为
#include
,且起始位置不能有空格。Gzip压缩内容示例
#include https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.gz
示例Gzip压缩内容表示Include文件包含一个Gzip压缩内容链接,cloud-init读取该Gzip压缩内容后会自动解压并运行,该Gzip压缩内容由User-Data脚本压缩得到,所以仅在实例首次启动时运行一次。
Upstart Job
如需使用Upstart Job,您需要为实例安装upstart服务,支持采用upstart服务管理启动行为的操作系统有CentOS 6、Ubuntu 10/12/14以及Debian 6/7。
简介
Upstart是一个事件驱动型的初始化系统,Upstart Job是一个配置文件,定义了一个服务或任务何时启动、停止和如何运行。它通常放置在/etc/init/目录下,文件扩展名为.conf。
运行频率
启动实例:实例每次启动都会自动运行。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行为
#upstart-job
,且起始位置不能有空格。Upstart Job内容示例
#upstart-job description "upstart test" start on runlevel [2345] #在运行级别2、3、4、5执行 stop on runlevel [!2345] #在运行级别2、3、4、5以外不执行 exec echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt
示例Upstart Job表示在系统进入指定的运行级别时输出一条包含时间戳的消息,并将该消息记录到
/root/output.txt
文件中。当系统离开这些运行级别时,作业会停止执行。
Windows实例
Windows实例是通过Vminit组件的Plugin_Main_CloudinitUserData
组件来运行自定义数据脚本,该插件仅支持在实例首次启动时运行。更多信息,请参见Vminit组件说明。
Windows自定义数据脚本支持Bat和PowerShell两种类型。
Bat脚本
运行频率
启动实例:实例首次启动时运行一次,重启实例不会自动运行。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行为
[bat]
,且起始位置不能有空格。只能输入半角字符,不能有多余字符。
写入数据的路径不能为
C:\Users
目录,否则自定义数据会执行失败。说明在Windows系统中,
C:\Users
及其子目录是用户配置文件和数据的默认存储位置,需要登录系统后才可以访问,而在系统初始化执行userdata阶段实际还未登录系统,所以写入数据到C:\Users
目录会失败。
Bat脚本示例
[bat] echo "bat test" > C:\userdata_test.txt
示例Bat脚本的效果是在实例首次启动时向userdata_test.txt文件写入内容
"bat test"
。
PowerShell脚本
运行频率
启动实例:实例首次启动时运行一次,重启实例不会自动运行。
更换操作系统:自动运行。
重新初始化系统盘:自动运行。
重要以下情况不会自动运行脚本:
如果更换操作系统使用的是自定义镜像且来源于原实例,更换操作系统时会判断实例不是初次启动,因此不会自动运行脚本。
如果创建使用的是自定义镜像,则创建实例时系统盘就有数据,初始化系统盘时会判断实例不是初次启动,因此不会自动运行脚本。
格式
首行为
[powershell]
,且起始位置不能有空格。只能输入半角字符,不能有多余字符。
写入数据的路径不能为
C:\Users
目录,否则自定义数据会执行失败。说明在Windows系统中,
C:\Users
及其子目录是用户配置文件和数据的默认存储位置,需要登录系统后才可以访问,而在系统初始化执行userdata阶段实际还未登录系统,所以写入数据到C:\Users
目录会失败。
PowerShell脚本示例
[powershell] write-output "powershell test" | Out-File C:\userdata_test.txt
示例PowerShell脚本的效果是在实例首次启动时向userdata_test.txt文件写入内容
powershell test
。
相关文档
您可以调用DescribeUserData接口查询一台ECS实例的自定义数据。
您也可以通过弹性伸缩的自定义数据功能,让多台ECS实例在启动时自动执行配置的脚本或命令,确保ECS实例配置的一致性,简化了运维工作。更多信息,请参见使用实例自定义数据自动配置ECS实例。
如果希望服务或脚本因程序异常、服务器重启、掉电等被中断时,及时恢复运行,云助手插件
ecs-tool-servicekeepalive
实现。具体操作,请参见自动恢复服务。