Initialize an instance with custom data - - Alibaba Cloud Documentation Center

Custom data

Custom data is a script or configuration file that you pass to an RDS Custom instance to run automated initialization tasks on the first boot. RDS Custom instances use the cloud-init component to read and process custom data to apply these configurations. The following are common data formats:

User-Data script: Suitable for running simple shell scripts.
Cloud-config data: Provides a structured way to configure instances using the YAML format. You can manage packages, users, networks, and more.
include file: Uses the #include directive to reference one or more URLs that point to User-Data scripts or Cloud-config data, such as an Object Storage Service (OSS) URL.
Gzip compressed content: If a User-Data script or Cloud-config data exceeds 32 KB, you can compress it into a .gz file and reference it using an include file.
MIME multi-part file: Bundles multiple data types, such as Cloud-config data and a User-Data script, into a single file.

The execution frequency of custom data depends on the data type and the scenario:

Data format	Start instance	Change operating system	Re-initialize system disk
User-Data script	Runs only when the instance is started for the first time. It does not run on subsequent reboots.	Runs automatically.	Runs automatically.
Cloud-config data	The execution of tasks depends on the frequency setting of the corresponding module. once-per-instance: Runs only when the instance is started for the first time. always: Runs every time the instance starts.	Runs automatically.	Runs automatically.
include file	Execution depends on the linked content (User-Data script or Cloud-config data).	Runs automatically.	Runs automatically.
Gzip compressed content	Execution depends on the file content (User-Data script or Cloud-config data).	Runs automatically.	Runs automatically.
MIME multi-part file	Execution depends on the file content (User-Data script or Cloud-config data).	Runs automatically.	Runs automatically.

Important

The script does not run automatically in the following scenarios:

When you replace the operating system with a custom image created from the original instance, the system does not consider this the instance's first boot, so the script does not run.
When you re-initialize the system disk of an instance created from a custom image, the system does not consider it a first boot because the disk already contains data. As a result, the script does not run.

For more information about custom data formats, see the cloud-init documentation for User-Data Formats.

Limitations

The instance must use a public image or a custom image created from a public image. The operating system must be one of the following:

Alibaba Cloud Linux, CentOS Stream, Ubuntu, Debian

Use custom data during instance creation

Step 1: Prepare the custom data

User-Data script

Format

The first line of the script must be #!.
User-Data script examples
- Run a custom script. This example writes the system time to the userdata_test.txt file when the instance is first started.
```
#!/bin/sh
echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt
```
- Customize the yum repository, DNS configuration, and time synchronization service
  
  The following example uses CentOS Stream 9. Replace the configurations with those for your operating system.
  Important
  The system automatically configures the default yum repository, NTP service, and DNS service when the instance starts. You can use instance custom data to change these default settings. However, note the following:
  - If you customize the yum repository, Alibaba Cloud will no longer provide support for the yum repository.
  - If you customize the NTP service, Alibaba Cloud will no longer provide support for time synchronization.
```
#!/bin/sh
# Modify DNS
echo "nameserver 114.114.114.114" | tee /etc/resolv.conf
# Modify yum repo and update
cp /etc/yum.repos.d/centos.repo /etc/yum.repos.d/centos.repo.bak
cp /etc/yum.repos.d/centos-addons.repo /etc/yum.repos.d/centos-addons.repo.bak
sed -i "s@http://mirrors.cloud.aliyuncs.com/centos-stream/@https://mirror.stream.centos.org/@g" /etc/yum.repos.d/centos.repo
sed -i "s@http://mirrors.cloud.aliyuncs.com/centos-stream/@https://mirror.stream.centos.org/@g" /etc/yum.repos.d/centos-addons.repo
yum update -y
# Modify NTP Server
echo "server ntp1.aliyun.com" | tee /etc/ntp.conf
systemctl restart ntpd.service
```
  Note
  In this example, 114.114.114.114 is the DNS server address, https://mirror.stream.centos.org is the CentOS Stream yum repository address, and server ntp1.aliyun.com is the Alibaba Cloud NTP server address. Replace them with the actual values for your environment.
  
  You can also use Cloud-config data to change the yum repository. However, this method is less flexible and may not work in scenarios where Alibaba Cloud has pre-configured certain yum repositories. We recommend that you use a User-Data script instead.
- Create a custom administrator account
  
  By default, RDS Custom instances use the root user as the administrator. You can use custom data to create an additional administrative user.
```
#!/bin/sh
useradd test-user
echo "test-user   ALL=(ALL)        NOPASSWD:ALL" | tee -a /etc/sudoers
mkdir /home/test-user/.ssh
touch /home/test-user/.ssh/authorized_keys
echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCRnnUveAis****" | tee -a /home/test-user/.ssh/authorized_keys
```
  Note
  Replace the example public key ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCRnnUveAis**** with your public key.

Cloud-config data

Format
- The first line must be #cloud-config, with no leading spaces.
- The content must use valid YAML syntax.
Cloud-config data examples
- Customize the software repository
  
  To configure a custom software repository, enter the following content in the Custom Data area. This example is for an Ubuntu image. If you use a different image, replace the content with the appropriate module configuration.
```
#cloud-config
apt:
  preserve_sources_list: false
  disable_suites:
    - $RELEASE-updates
    - backports
    - $RELEASE
    - mysuite
  primary:
    - arches:
        - amd64
        - i386
        - default
      uri: http://us.archive.ubuntu.com/ubuntu
```
- Automatically install the nginx service
  
  Enter the following content in the Custom Data area to automatically install the nginx service.
```
#cloud-config
packages: 
 - nginx 
runcmd: 
 - systemctl start nginx.service
```
- Configure a custom hostname
  
  Enter the following content in the Custom Data area to set a custom hostname.
```
#cloud-config
hostname: my-instance
fqdn: my-instance.localdomain
```
- Automatically run a custom script
  
  Enter the following content in the Custom Data area to automatically run a shell script every time the instance starts.
```
#cloud-config
bootcmd:
- echo "Hello World. The time is now $(date -R)!" | tee /root/userdata_test.txt
```

Include file

Format

The first line must be #include, with no leading spaces.
include file example This example shows a URL that points to a script stored in an Object Storage Service (OSS) bucket in the China (Hangzhou) region.
```
#include
https://ecs-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.sh
```

Gzip compressed content

Format

The first line must be #include, and must not have any leading spaces.
Gzip compressed content example This example shows a URL that points to a Gzip compressed file stored in an Object Storage Service (OSS) bucket in the China (Hangzhou) region.
```
#include
https://rc-image-test.oss-cn-hangzhou.aliyuncs.com/userdata/myscript.gz
```

MIME multi-part file

Format
- The first line must be Content-Type: multipart/mixed; boundary="****", with no leading spaces. The boundary can be customized.
- The second line, MIME-Version: 1.0, specifies the version. This field is typically required in every MIME message.

MIME multi-part file example

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
#cloud-config
runcmd:
- [ mkdir, /test-cloudinit ]
write_files:
- path: /test-cloudinit/cloud-init.txt
  content: |
    Created by cloud-init
  append: true
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/bash
mkdir test-userscript
touch /test-userscript/userscript.txt
echo "Created by bash shell script" >> /test-userscript/userscript.txt
--//--

This example MIME multi-part file contains cloud-init directives and a Bash shell script:

The cloud-init directives create a file (/test-cloudinit/cloud-init.txt) and write Created by cloud-init to it.
The Bash shell script creates a file (/test-userscript/userscript.txt) and writes Created by bash shell script to it.

Step 2: Use custom data

Create an instance in the console

When you create an RDS Custom instance, expand the More section and enter your custom data in the Custom Data area.

Important
If your custom data is already Base64-encoded, select The preceding input is Base64-encoded.. The size of the custom data before encoding cannot exceed 32 KB. If your data is not encoded, leave this option unselected, and the system will automatically encode the content.
Create an instance using the API

If you create an instance using the API, specify the UserData parameter in the RunRCInstances operation.

Step 3 (Optional): Verify custom data execution

This section uses the following User-Data script as an example.

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

In this example, the User-Data script writes the current system time to the userdata_test.txt file when the instance is first started. To verify the result, run the cat userdata_test.txt command and view the script output.

View custom data

You can call the DescribeRCInstanceAttribute operation to query the custom data of an RDS Custom instance.

:Initialize an instance using custom data