实例自定义数据

实例自定义数据，是阿里云 ECS 为您提供的一种自定义实例启动行为及传入数据的功能，该功能兼容 Windows 实例及 Linux 实例，主要有两种用途：

• 作为实例自定义脚本，在启动实例时执行
• 作为普通数据，将一定的信息传入实例中，您可以在实例中引用这些数据

本文档介绍了：

• 实例自定义数据的使用说明
• 怎么使用实例自定义脚本，包括：
  • Linux 实例自定义脚本 和 使用示例
  • Windows 实例自定义脚本 和 使用示例
• 如何查看实例自定义数据，包括：
  • 查看 Linux 实例自定义数据
  • 查看 Windows 实例自定义数据

1. 实例自定义数据使用说明

• 使用条件：只有满足以下所有条件的实例才能使用实例自定义数据。

  • 网络类型：必须是专有网络（VPC）。
  • 实例规格：必须是系列 I 的 I/O 优化实例或系列 II 以后的实例规格。
  • 镜像：必须是 系统镜像 或 继承于系统镜像的自定义镜像。
  • 操作系统必须是以下各个操作系统类型中的一种：

    Windows	Linux
    Windows Server 2016 64位 Windows Server 2012 64位 Windows Server 2008 64位	CentOS Ubuntu SUSE Linux Enterprise OpenSUSE Debian Aliyun Linux

  • 如果您要定制实例自定义脚本，那么您应按照操作系统类型和相关脚本类型输入 自定义数据。
    • 如果您要输入的数据已经采用 Base64 编码，应勾选 输入已采用 base64 编码。

      注意：在 Base64 编码前，实例自定义脚本不能超过 16 KB。

    • Linux 实例：必须满足相应 Linux 实例自定义脚本类型 的格式要求。
    • Windows 实例：只能以 [bat] 或 [powershell] 开头。
    • 注意：只能输入半角英文字符，而且不应有多余的字符。

• 实例启动后，运行命令查看：

  • 实例自定义脚本的执行结果。
  • 传入实例的普通数据。

• 控制台：您可以在控制台修改实例自定义数据的内容。如果是自定义脚本类型，修改过的脚本是否要重新执行取决于脚本类型。比如，如果修改的是 Linux 的 Cloud Config 中的 bootcmd 类型的脚本，那么每次实例重启时都会自动执行。

• OpenAPI：您也可以通过 OpenAPI 使用实例自定义数据，详情参考 CreateInstance 和 ModifyInstanceAttribute。

2. Linux 实例自定义脚本

阿里云的 Linux 实例自定义脚本采用开源的 cloud-init 架构实现，该架构以 实例元数据 为数据来源，对 Linux 实例进行各项自动化配置。自定义脚本类型兼容开源 cloud-init。详情请参考 cloud-init 开源说明：http://cloudinit.readthedocs.io/en/latest/topics/format.html。

2.1 Linux 实例自定义脚本说明

实例自定义脚本执行时间节点：实例 running 后，/etc/init 执行前。

Linux 实例自定义脚本默认将以 root 用户权限执行。

2.2 Linux 实例自定义脚本类型

User-Data Script

• 描述：以脚本作为自定义配置的手段，如 shell 脚本。
• 格式：首行必须是 #!，如 #!/bin/sh。
• 限制：在 Base64 编码前，脚本内容（包括首行在内）不能超过 16 KB。
• 频率：仅在首次启动实例时执行一次。
• 示例：

  #!/bin/sh
  echo "Hello World.  The time is now $(date -R)!" | tee /root/output10.txt

Cloud Config Data

• 描述：cloud-init 中预定义的对实例的部分服务进行配置的手段，如 yum 源、SSH 密钥。
• 格式：首行必须是 #cloud-config。
• 限制：在 Base64 编码前，脚本内容（包括首行在内）不能超过 16 KB。
• 频率：配置的服务不同，执行频率也会不同。
• 示例：

  #cloud-config
  apt:
  primary:
    - arches: [default]
      uri: http://us.archive.ubuntu.com/ubuntu/

Include

• 描述：实例自定义脚本可以以文本文件的形式将具体的配置内容保存起来，然后以 URL 的形式传入 cloud-init 中进行处理。
• 格式：首行必须是 #include。
• 限制：在 Base64 编码前，脚本内容（包括首行在内）不能超过 16 KB。
• 频率：由实际文本文件中脚本的类型决定执行频率。
• 示例：

  #include
  http://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/cloudconfig

Gzip 压缩格式

• 描述：由于 cloud-init 对各类自定义脚本的内容有 16 KB 大小的限制，所以您可以选择把脚本文件压缩之后再传入到实例自定义脚本中。
• 格式：.gz 文件的形式，以 #include 的 URL 的方式传入实例自定义脚本。
• 频率：由压缩文件中所包含的脚本内容决定。
• 示例：

  #include
  http://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/config.gz

3. 查看 Linux 实例自定义数据

要查看某个 Linux 实例自定义数据，您可在实例中执行如下命令：

curl http://100.100.100.200/latest/user-data

4. Windows 实例自定义脚本

阿里云的 Windows 实例自定义脚本是阿里云自主研发的一套为 Windows 实例提供执行初始化脚本的能力。

Windows 实例自定义脚本有 2 种类型，包括：

• Bat 批处理程序：以 [bat] 开头且作为首行。在 Base64 编码前，所有脚本内容必须小于 16 KB。

• PowerShell 脚本：以 [powershell] 开头且作为首行。在 Base64 编码前，所有脚本内容必须小于 16 KB。

5. 查看 Windows 实例自定义数据

要查看某个 Windows 实例自定义数据，您可以在实例中执行如下 PowerShell 命令：

Invoke-RestMethod http://100.100.100.200/latest/user-data/

6. 附 1：Linux 实例自定义脚本使用示例

假设您在创建一个 Linux 实例，需要输入实例自定义脚本。

实例的信息如下：

• 网络类型：VPC。
• 实例规格：系列 II（是 I/O 优化实例）。
• 镜像：CentOS 7.2 64 位。
• 创建实例时，选择 使用文本形式 输入 自定义数据。

以下示例将说明如何以不同的格式输入实例自定义脚本，并查看脚本的执行结果。

User-Data Script

1. 在 自定义数据 输入框中输入如下脚本。注意：必须以 #! 开头。

   #!/bin/sh
   echo "Hello World.  The time is now $(date -R)!" | tee /root/output.txt

   

2. 实例创建完成后，连接并启动实例，执行命令 cat [file]，查看脚本的执行结果。

   [root@XXXXX2z ~]# cat output.txt
   Hello World.  The time is now Mon, 24 Jul 2017 13:03:19 +0800!

Cloud Config Data

1. 在 自定义数据 输入框中输入如下内容。注意：必须以 #cloud-config 作为第一行，且前面不应有空格。

   #cloud-config
   bootcmd:
   - echo 192.168.1.130 us.archive.ubuntu.com >> /etc/hosts

2. 实例创建完成后，连接并启动实例，查看运行结果。
   

Upstart Job

Upstart Job 类型的实例自定义脚本会将您的脚本或服务放到 /etc/init 目录下，成为每次开机都会启动的初始化脚本。

1. 在 自定义数据 输入框中输入如下内容。注意：必须以 #upstart-job 作为第一行，且前面不应有空格。

   #upstart-job
   #!/bin/sh
   echo "Hello World.  The time is now $(date -R)!" | tee /root/output.txt

2. 实例创建完成后，连接并启动实例，查看执行结果。
   
   从上面的结果中您可以看到，在实例的 /etc/init 文件夹中生成了一个 part-001.conf 启动任务文件。

Include

您可以将上述各种不同类型的实例自定义脚本以文件的形式存在一个链接中，再将这个链接作为 自定义数据 的文本，从而更好地管理和维护脚本，同时也可以减少对于脚本大小的限制。

1. 在 自定义数据 输入框中输入如下内容。注意：必须以#include作为第一行，且前面不应有空格。

   #include
   http://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/UserData/myscript.sh

2. 实例创建完成后，连接并启动实例，查看执行结果。

   注意：

   • 必须以 #include 作为第一行，且前面不要有空格。
   • 每一行为一个完整的 URL，该 URL 为一个脚本文件的存放地址，存放着您需要进行各项配置的脚本。您可以参考 Linux 实例自定义脚本类型“Include”中的 URL 文件制作示例 制作脚本文件并获取 URL。
   • 每个脚本文件的大小不能超过 16 KB。
   • 必须确保实例可以访问所有的 URL。

Gzip

当 include URL 中的脚本文件的大小超过了 16 KB，您可以使用 gzip 命令压缩脚本文件。

1. 在 自定义数据 输入框中输入如下内容。注意：必须以 #include 作为第一行，且前面不应有空格。

   #include
   http://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/UserData/myscript.sh.gz

2. 实例创建完成后，连接并启动实例，查看执行结果。

   注意：其中 URL 链接到一个压缩后的脚本文件，如本示例中的“myscript.sh.gz”。

关于 Linux 实例自定义脚本的更多信息，请参考如下开源帮助：http://cloudinit.readthedocs.io/en/latest/topics/format.html。

7. Linux 实例自定义脚本类型“Include”文件中的 URL 文件制作示例

1. 创建文本文件，在 Windows 上使用 Notepad++ 打开。

2. 在 Notepad++ 中编辑文件内容，第一行必须满足实例自定义脚本的格式要求，比如：#!/bin/sh、#cloud-config、#upstart-job。

3. 保存文本文件，并上传到 OSS 的 Object 中。
   

4. 获取 OSS Object 的 URL 访问地址。
   

   注意：

   • 每个文件只能是一种实例自定义脚本格式。
   • 以上只是示例，您可以根据需要自行配置文件 URL 的获取方式。
   • OSS Object 的文件 URL 链接存在有效期限制。

8. Windows 实例自定义脚本使用示例

假设您在创建一个 Windows 实例，需要输入实例自定义脚本。

实例的信息如下：

• 网络类型：VPC。
• 实例规格：系列 II（是 I/O 优化实例）。
• 镜像：Windows Server 2012 64位。
• 创建实例时选择 使用文本形式 输入 自定义数据。

以下示例将说明如何以不同的格式输入实例自定义脚本，并查看脚本的执行结果。

Bat 脚本

1. 在 自定义数据 输入框中输入如下内容。注意：必须以 [bat] 作为第一行，且前面不应有空格。

   [bat]
   echo "bat test" > c:\1.txt

2. 实例创建完成后，连接实例查看执行结果：在 C:\ 盘添加了一个名称为 “1” 的文本文件。
   

3. 连接实例后，您可以在 Windows PowerShell 里使用如下命令查看输入的实例自定义脚本。

   Invoke-RestMethod http://100.100.100.200/latest/user-data/

Windows PowerShell

1. 在 自定义数据 输入框中输入如下内容。注意：必须以 [powershell] 作为第一行，且前面不应有空格。

   [powershell]
   write-output "Powershell Test" | Out-File C:\2.txt

2. 连接实例后，您可以在 Windows PowerShell 里使用如下命令查看输入的实例自定义脚本。

   Invoke-RestMethod http://100.100.100.200/latest/user-data/