Environment Preparation

Prerequisites

Before encapsulating an Debian 13 system template, obtain the required ISO image and add the image to ZStack Cloud. Notice the following points when you perform this operation:

Download the Debian 13 installation image (Debian 13) from the official Debian 13 website and comply with the applicable license terms.
This Tutorial references debian-13.6.0-amd64-netinst.iso.

About this task

To prepare for Debian 13 template encapsulation, follow these steps:

Add an installation image.
Create a disk offering.

Procedure

Add an installation image.
On the main menu of ZStack Cloud, choose Resource Center > Resource Pool > Compute Configuration > Image. On the Image page, click Add Image. Then, the Add Image page is displayed.
On the displayed page, set the following parameters:
- Name: Enter a name for the image.
- Description: Optional. Enter a description for the image.
- Image Type: Select an image type. Here, select System Image.
- Image Format: Select an image format. Here, Select iso.
- CPU Architecture: Select x86_64.
- Platform: Select an image platform. Here, select Linux.
- OS: Select an operating system that is consistent with the image.
- VirtIO: Choose whether to enable VirtIO according to your actual operating system and platform. Here, enable VirtIO.
- Image Storage: Select an image storage added before.
- Image Path: Enter a URL or upload a local file. Here, upload a local ISO image.
  Note: When you add a local file as an image, the browser uploads the image as an intermediate transfer. Do not refresh or close the browser, and do not stop the Management Node service. Otherwise, the image upload fails.
- BIOS Mode: Select a BIOS mode. Here, select Legacy.
Figure 1. Add Image
Create a disk offering.
On the main menu of ZStack Cloud, choose Resource Center > Resource Pool > Compute Configuration > Disk Offering. On the Disk Offering page, click Create Disk Offering. Then, the Create Disk Offering page is displayed.
On the displayed page, set the following parameters:
- Name: Enter a name for the disk offering.
- Description: Optional. Enter a description for the disk offering.
- Disk Size: Set the capacity of a volume.
- Note: This example uses a 40 GiB root volume.
- Set Disk Bandwidth: Optional. Set an upper limit for the I/O bandwidth of a volume.
- Set Disk IOPS: Optional. Set an upper limit of the disk reads/writes per second (IOPS).
- Advanced Parameter: Optional. You can set this parameter by configuring a JSON file.
Figure 2. Create a Disk Offering

Template

Install an Operating System

About this task

To install an operating system, follow these steps:

Create a VM Instance
Install Debian 13

Procedure

Create a VM Instance.

Create a VM Instance on ZStack Cloud and boot it from the installation image. For more information, see Create a VM Instance in the User Guide. This example uses 2 vCPUs, 4 GiB of memory, a 40 GiB root volume, and one NIC with IPv4 DHCP.
Install Debian 13.
1. Start the graphical installer.
  
  Boot from the ISO, select Graphical install, and press Enter promptly to start the graphical installer.
  
  See Figure 3.
  
  Figure 3. Debian Graphical Installer
2. Select the language, location, and keyboard.
  
  Select English. Choose other, Asia, and China for the location. Under Configure locales, select United States with en_US.UTF-8. Select American English for the keyboard.
  
  See Figure 4.
  
  Figure 4. Select en_US.UTF-8
3. Install Debian.
  
  Configure networking with DHCP. Set a hostname and leave Domain empty if no domain is used. Create an administrator account; if no root password is set, verify sudo access for the first user. Then partition the new root volume as follows.
  
  Select Guided - use entire disk and click Continue.
  
  Verify that the target is the new root volume, select it, and click Continue. This example uses vda, displayed as 42.9 GB by the installer, corresponding to the 40 GiB volume created earlier.
  
  Select All files in one partition (recommended for new users) and click Continue.
  
  Review the generated partitions. This example has a 40.7 GB ext4 root partition mounted at / and a 2.2 GB swap partition. Actual sizes depend on the selected disk and installer result. Select Finish partitioning and write changes to disk and click Continue.
  
  Note: The swap partition follows the root partition in this example, which is suitable for a fixed-capacity template. Increasing the volume size does not automatically make space at the end of the disk available to the root partition. If automatic root partition expansion is required, plan a layout with the root partition last during installation and validate both partition and filesystem expansion. Do not move or delete partitions on the installed example system.
  
  See Figure 5.
  
  Figure 5. Review the Guided Partitioning Summary
  
  Confirm again that every partition to be formatted belongs to the intended new disk. Select Yes and click Continue to write the changes and begin base system installation. This overwrites data on the target partitions.
  
  In the later software selection, select SSH server and standard system utilities without a desktop environment. Network installation requires a reachable Debian mirror. Install GRUB on the target root disk.
  
  If the network mirror is unavailable, go back and select Yes for Continue without a network mirror to proceed offline. The software list may then contain only standard system utilities, with no SSH server option. Select the available standard utilities and continue. Query and install the required template components after booting; this offline selection does not establish that the SSH server is installed.
  
  See Figure 6.
  
  Figure 6. Software Selection Without a Network Mirror
  
  When installing GRUB, select the root disk containing the installed system, /dev/vda in this example, and click Continue.
  
  Wait for the Installation complete message. Remove the installation media, set HardDisk first in the boot order, and click Continue to reboot. Verify boot from the root volume in the next step without another shutdown and startup.
  
  See Figure 7.
  
  Figure 7. Debian Installation Complete
4. Boot from the root volume and check the system.
  
  Detach the installation ISO and set HardDisk first in the boot order. Sign in to the installed system through the console, then configure the template.

Configure the Template System

Prerequisites

Sign in as root through the console, or run sudo -i with an account that has sudo privileges. Run the following commands one at a time and resolve failures before continuing.

About this task

Configure the template system by using the following steps:

Set the Hostname.
(Optional) Install cloud-init.
Configure networking.
(Optional) Install GuestTools.

Procedure

Set the Hostname.
Run the following command to set the template hostname:
```
hostnamectl set-hostname localhost.localdomain
```
(Optional) Install cloud-init.
To initialize VM Instances with User Data or SSH public keys, install cloud-init from repositories matching the OS release.
```
apt-get update
apt-get install -y cloud-init isc-dhcp-client cloud-guest-utils
```
Note: For offline installation, prepare repositories and dependencies for the same release. The netinst media does not contain every required component.

Note: For SSH access, also install and enable openssh-server. Without cloud-init, automatic User Data and SSH public key injection are unavailable.
Configure networking.
If cloud-init is installed, configure networking as follows. Otherwise, retain the installer network configuration, ensure DHCP and automatic connection are enabled, and skip the cloud-init configuration and cleanup commands in this step.
This example uses ifupdown with one NIC and IPv4 DHCP. Run ip -br link to identify the NIC. Add the following to /etc/cloud/cloud.cfg.d/99-ipv4-only.cfg, replacing ens3 with the actual interface name.
```
network:
  version: 2
  ethernets:
    ens3:
      dhcp4: true
      dhcp6: false
```
Note: This overrides datasource network configuration and applies only to the single-NIC IPv4 scenario. Adjust it for multiple NICs, static addresses, or dual-stack networking. Check /etc/network/interfaces and interfaces.d to avoid duplicate interface definitions.
If cloud-init has already generated network configuration, back it up and run:
```
cloud-init clean --configs network
```
Move any remaining old generated file, such as 50-cloud-init, outside interfaces.d; retain loopback and source configuration. This reruns initialization and applies only to the current template builder.
After configuring the network, run systemctl reboot to restart the VM Instance.
(Optional) Install GuestTools.
Before installing GuestTools, install the following dependencies:
```
apt-get update
apt-get install -y --no-install-recommends \
  python3 tar libglib2.0-0t64 libatomic1 sudo
```
Attach the current platform GuestTools ISO on the VM Instance details page. Confirm that /dev/cdrom refers to it and /mnt/cdrom has no other media mounted, then run the following commands.
```
mkdir -p /mnt/cdrom
mount /dev/cdrom /mnt/cdrom
cd /mnt/cdrom
bash ./zs-tools-install.sh
```
If the installer asks whether to link python3 to python, enter y. After installation, leave the directory and unmount the media.
```
cd ~
umount /mnt/cdrom
```
Figure 8. GuestTools Installer Output and Compatibility Warning

Note: A zs-tools is not verified for os message means the tools have not been verified for the OS. Successful installation does not establish official compatibility.

Create a System Template

About this task

To create a system template, follow these steps:

Create an image.
Export the image.

Procedure

Create an Image.
Run the following commands as root to clear template identity and shut down. Remove temporary credentials and retain a login account for new VM Instances. Do not restart the template VM Instance after cleanup.

Note: Without cloud-init, these commands retain SSH host keys to avoid preventing SSH from starting without a key-generation mechanism. Arrange host-key regeneration for each VM Instance created from such an image; cloud-init initialization is unavailable.

If cloud-init is installed, confirm that initialization succeeds and the ssh module generates SSH host keys on first boot before cleanup.
```
sh -eu <<'CLEANUP'
test "$(id -u)" -eq 0
dbus_id=/var/lib/dbus/machine-id
if [ -L "$dbus_id" ]; then
    test "$(readlink -f "$dbus_id")" = /etc/machine-id
elif [ -e "$dbus_id" ]; then
    test -f "$dbus_id"
fi
if command -v cloud-init >/dev/null 2>&1; then
    cloud-init clean --logs --machine-id
    rm -f /etc/ssh/ssh_host_*
else
    printf 'uninitialized\n' > /etc/machine-id
fi
if [ -d /var/lib/dbus ] && [ ! -L "$dbus_id" ]; then
    rm -f "$dbus_id"
    ln -s /etc/machine-id "$dbus_id"
fi
sync
systemctl poweroff
CLEANUP
```
On the details page of the VM instance created, choose Actions > Image and ISO > Create Image. Then, the Create Image page is displayed.
On the displayed page, set the following parameters:
- Name: Enter a name for the image.
- Description: Optional. Enter a description for the image.
- Image Type: Select System Image here.
- Image Storage: Select an image storage created before.
Figure 9. Create an Image
Export the image.
You can use the image exported to create VM instances on other cloud platforms directly. The method to export images varies according to image storage types.
- ImageStore image storage.
  On the Image page, choose Actions > Export Image. This button helps export the image.
  After generating the image, you can copy the URL of the image exported on the Overview page to download the image. Or, you can copy the URL of the exported image on the Exported page. You can also click Download on the page to download the image directly.
- Ceph image storage. If you use a Ceph image storage, you can export the image on the UI or from the image storage.
  - Export on the UI:
    On the Image page, choose Actions > Export Image. This button helps export the image.
    After generating the image, you can copy the URL of the image exported on the Overview page to download the image. Or, you can copy the URL of the exported image on the Exported page. You can also click Download on the page to download the image directly.
  - Export from the image storage:
    
    On the Overview page of the created image, copy Installation Path.
    
    Login to the terminal of the Ceph image storage, run rbd export to export the image. For example:
    If you obtain the installation path ceph://bak-t-cac5eee23a204c1a914d1743f1584644/7232237c0059409babcd1c7a69452b98, you can run the following commands to export the image:
    [root@ceph-node1 ~]# rbd export bak-t-cac5eee23a204c1a914d1743f1584644/7232237c0059409babcd1c7a69452b98 /root/export-test.qcow2 [root@ceph-node1 ~]# # bak-t indicates the installation path of the image [root@ceph-node1 ~]# # /root/export-test.qcow2 indicates the target path and the file name of the exported image
    Note: The command rbd export does not include such a prefix as ceph://.

What to do next

Now, you have completed the encapsulation of an Debian 13 system template. You can use this image to create VM instances in bulk.

PreviousZStack Cloud NextZStack Cloud