You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/IMAGE_STARTUP_SCRIPTS.md

50 lines
3.6 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 镜像首次启动脚本
管理员可在「云镜像模版」中点击对应镜像的「设置启动脚本」,为不同镜像保存不同的 Bash 脚本。超级管理员可保存,普通管理员只读。保存空字符串停用;最大 32 KiB UTF-8,Windows CRLF 换行在保存时转换为 LF。
## 生效范围
- 仅新建云镜像实例的首次启动执行。引擎在准备该次创建的镜像副本时读取配置,将脚本封装进这个实例的 NoCloud seed;已经生成的 seed 不随目录设置变化。
- 现有实例、普通重启、改密码、改主机名、换公网 IP 和加入/退出 VPC 不会重新领取镜像目录里的新脚本。
- 本功能不在系统重装、救援 ISO 或用户 ISO 安装时注入脚本。
- 脚本通过 `/bin/bash` 在来宾内以 root 身份执行。镜像需要预装并启用 cloud-init 和 Bash;依赖网络的命令还需要有效网络及软件源。它不依赖 QGA,也不会在面板或宿主机执行。
- 脚本和设置只通过管理员接口提供,用户创建请求不能覆盖。脚本会写入来宾,来宾 root 可以读取,因此不要写入平台密钥或其他租户的凭据。
## 执行与排查
cloud-init 的 final 阶段通过 `runcmd` 调用面板生成的启动包装脚本。普通 `runcmd` 会在实例标识改变后重新运行,而现有密码和主机名设置会改变 NoCloud 的 `instance-id`,因此包装脚本在系统盘中使用独立、原子创建的 `started` 目录记录首次尝试。
首次尝试失败或中断也不会自动重跑任意管理员脚本。管理员确认现场状态后,可在来宾内人工处理;不要仅为重跑而清除标记。如果镜像是从已有实例制作的,应在制模板阶段清理 `/var/lib/virt-cloud/startup/` 的运行记录,避免克隆继承已执行标记。
来宾内相关路径:
| 路径 | 用途 |
| --- | --- |
| `/var/lib/virt-cloud/startup.sh` | 封存的管理员脚本,root:root 0600 |
| `/var/lib/virt-cloud/startup-runner.sh` | 一次执行包装脚本,root:root 0700 |
| `/var/lib/virt-cloud/startup/started/` | 已开始尝试的标记 |
| `/var/lib/virt-cloud/startup/output.log` | 本次脚本 stdout/stderr |
| `/var/lib/virt-cloud/startup/exit-code` | 退出码;0 表示成功,非 0 表示失败,存在 started 但无退出码表示仍运行或被中断 |
示例脚本内容:
```bash
#!/bin/bash
set -e
mkdir -p /opt/example
printf '%s\n' '初始化完成' > /opt/example/initialized.txt
```
脚本运行不属于引擎创建完成条件:VM 创建成功不代表初始化脚本成功。脚本失败不会制造电源任务锁。本版结果仅保存在来宾,尚未增加面板脚本状态回报。
## 存储与并发
配置使用引擎现有加密镜像目录记录,不新增数据库表。保存携带镜像 `created_at` 和脚本 `expected_revision`;旧编辑页面不能覆盖另一管理员的修改或删除后重新导入的镜像。删除镜像同时移除脚本设置;普通镜像目录、导入任务及租户响应不携带脚本正文。
## 官方依据与验证边界
- [cloud-init 启动命令](https://docs.cloud-init.io/en/latest/reference/yaml_examples/boot_cmds.html):`runcmd` 首次启动执行,`bootcmd` 默认每次启动执行。
- [user-data script](https://docs.cloud-init.io/en/latest/explanation/format/user-data-script.html):用户脚本在 final 阶段运行。
回归测试覆盖脚本保存、权限和版本冲突、创建派发、seed 改写、成功/失败/中断后的重复执行保护。模拟 libvirt 和本地包装脚本测试不能替代真实镜像的 cloud-init 验收;上线后应分别用实际支持的发行版检查脚本、网络和日志。