oracle-freetier-instance-creation的main.py源码逐段剖析:Python调用OCI API启动免费实例的5步流程
oracle-freetier-instance-creation的main.py源码逐段剖析:Python调用OCI API启动免费实例的5步流程
oracle-freetier-instance-creation 是一个用于自动创建 Oracle Cloud 免费层(Free Tier)实例的 Python 自动化脚本。本文逐段剖析 main.py 源码,梳理它通过 Python 调用 OCI API 启动免费 ARM 实例的 5 步流程,帮助新手理解脚本如何自动绕开 "Out of host capacity" 容量错误、轮询重试直到实例成功创建。
一、为什么需要这个脚本?🚀
在 Oracle Cloud 控制台创建免费 ARM 实例(2 OCPU / 12 GB RAM)时,热门可用域经常出现如下报错:
Out of host capacityOut of capacity for shape VM.Standard.A1.Flex
手动反复点"创建"既不现实也容易漏掉窗口期。这个脚本的思路是:每隔 60 秒(可由 REQUEST_WAIT_TIME_SECS 配置)调用一次 OCI API 尝试创建,成功即停,并在项目目录生成 INSTANCE_CREATED 文件记录实例详情。
二、项目文件一览
| 文件 | 作用 |
|---|---|
| main.py | 核心脚本,封装全部 OCI API 调用与重试逻辑 |
| oci.env | 环境变量配置(实例名、机型、重试间隔、通知渠道等) |
| setup_init.sh | 一键入口:安装依赖并后台启动 main.py,附带进程监控与通知 |
| setup_env.sh | 交互式生成 oci.env 配置 |
| sample_oci_config | OCI API 配置文件样例(user、fingerprint、tenancy、region、key_file) |
| requirements.txt | 依赖仅 4 个:oci、paramiko、python-dotenv、requests |
| email_content.html | 实例创建成功后发送的 HTML 邮件模板 |
获取代码(如需 clone 仓库):
git clone https://gitcode.com/gh_mirrors/or/oracle-freetier-instance-creation
cd oracle-freetier-instance-creation
三、main.py 开篇:读配置、建客户端
1️⃣ 加载 oci.env 环境变量
脚本第一行实质动作是用 python-dotenv 加载 oci.env(main.py),把十几个配置项统一转成环境变量:
load_dotenv('oci.env')
OCI_COMPUTE_SHAPE = os.getenv("OCI_COMPUTE_SHAPE", ARM_SHAPE).strip()
WAIT_TIME = int(os.getenv("REQUEST_WAIT_TIME_SECS", "0").strip())
新手重点关注的几个变量:
OCI_COMPUTE_SHAPE:机型,VM.Standard.A1.Flex(ARM,默认)或VM.Standard.E2.1.Micro(AMD Micro)REQUEST_WAIT_TIME_SECS:容量报错后的重试间隔(秒)OPERATING_SYSTEM+OS_VERSION或直接OCI_IMAGE_ID:指定操作系统镜像
2️⃣ 校验 oci_config 并初始化 3 个 OCI 客户端
脚本用 configparser 读取 oci_config 中的 user 字段,并做了两个"防手滑"校验:env 值与 config 值中都不允许出现空格,否则写入 ERROR_IN_CONFIG.log 并提示(main.py)。随后创建三个 SDK 客户端(main.py):
iam_client = oci.identity.IdentityClient(config) # 租户 / 可用域
network_client = oci.core.VirtualNetworkClient(config) # 子网
compute_client = oci.core.ComputeClient(config) # 实例 / 镜像
三个客户端恰好覆盖后续 5 步流程所需的全部 API 能力。
四、核心:启动免费实例的 5 步流程
launch_instance() 是整个脚本的心脏,源码里用 Step 1 ~ Step 5 注释标得清清楚楚:
flowchart LR
S1[Step 1<br/>获取 Tenancy] --> S2[Step 2<br/>获取可用域 AD]
S2 --> S3[Step 3<br/>获取 Subnet ID]
S3 --> S4[Step 4<br/>获取 Image ID]
S4 --> S5[Step 5<br/>启动实例 + 轮询状态]
S5 -- 容量错误 --> S5
第 1 步:获取租户 ID(Tenancy)
user_info = execute_oci_command(iam_client, "get_user", OCI_USER_ID)
oci_tenancy = user_info.compartment_id
根据 oci_config 里的 user 反查所属租户的 OCID。OCI 的所有资源都挂在租户之下,后续每一步查询都要带上它。
第 2 步:获取可用域(Availability Domain)
oci_ad_names = itertools.cycle(oci_ad_name)
根据 oci.env 中的 OCT_FREE_AD(如 AD-1,支持逗号分隔多个)筛出具备免费资格的可用域,并用 itertools.cycle 包装成循环迭代器。这是"抢容量"的关键设计:某个 AD 报容量错误后,下一次请求自动换到下一个 AD 尝试。
第 3 步:获取子网 ID
- 若 oci.env 中已填
OCI_SUBNET_ID(本地机器运行时需要),直接使用; - 否则调用
list_subnets列出全部子网并取第一个——这就是官方推荐的"跑在免费 Micro 实例上"的原因:子网现成,无需手工填写。
第 4 步:获取镜像 ID
- 提供了
OCI_IMAGE_ID则直接采用; - 否则按机型调用
list_images,把精简后的镜像列表写入images_list.json留档,再按OPERATING_SYSTEM+OS_VERSION(如 Canonical Ubuntu 22.04)精确匹配出镜像 OCID。
第 5 步:启动实例并轮询状态 ⚡
这一步分三个小环节,也是代码量最大的部分:
- 先做幂等检查:check_instance_state_and_write() 先查询是否已存在 RUNNING / PROVISIONING 状态的实例,有则直接写
INSTANCE_CREATED退出,避免重复创建; - 组装 LaunchInstanceDetails:ARM 固定 2 OCPU + 12 GB,Micro 固定 1 OCPU + 1 GB,同时配置网络(
CreateVnicDetails)、SSH 公钥(metadata)与启动盘大小; - 无限重试循环:调用
launch_instance返回 200 后轮询实例状态,未到 RUNNING 就继续循环:
launch_instance_response = compute_client.launch_instance(
launch_instance_details=oci.core.models.LaunchInstanceDetails(
availability_domain=next(oci_ad_names), # 容量错误后自动切换 AD
compartment_id=oci_tenancy,
...
)
)
五、错误处理:自动绕过容量错误的关键 🔧
execute_oci_command:带重试的通用 API 包装器
所有查询类 API 都经 execute_oci_command() 调用:成功返回 response.data;抛出 ServiceError 时把 status / code / message 整理成 dict 交给 handle_errors 分类处理。
handle_errors:区分"暂时不行"和"真的失败"
handle_errors() 的处理策略如下表:
| 错误场景 | 脚本行为 |
|---|---|
TooManyRequests / Out of host capacity. / InternalError / HTTP 502 |
休眠 WAIT_TIME 秒后重试——这就是自动占坑的核心 |
LimitExceeded(启动时) |
重新检查实例是否已创建:已创建则退出,否则继续重试 |
| 其他未知错误 | 写入 UNHANDLED_ERROR.log、发送邮件通知并抛异常终止 |
一句话总结:容量错误在这里被当作"还没轮到"而不是"失败",这正是它和手动控制台创建的本质区别。
六、SSH 密钥与消息通知
- SSH 密钥自动生成:若
SSH_AUTHORIZED_KEYS_FILE指向的文件不存在,用 paramiko 生成 2048 位 RSA 密钥对(main.py),公钥通过ssh_authorized_keys元数据注入新实例,创建后即可直连; - Gmail 通知:创建成功后按 email_content.html 模板生成 HTML 邮件(实例 ID、名称、AD、机型、状态自动填充);
- Discord / Telegram:setup_init.sh 还支持 webhook 推送,并对进程挂了信号陷阱——脚本被 Ctrl+C 中断或挂起时都会主动发一条"已停止"通知,防止"失联式运行"。
七、运行脚本与产出文件
配置完成后只需一条命令(setup_init.sh 会自动装依赖、后台运行并轮询状态):
./setup_init.sh # 首次:安装依赖 + 后台运行
./setup_init.sh rerun # 报错后:跳过安装直接重跑
运行中值得关注的日志 / 结果文件:
| 文件 | 含义 |
|---|---|
INSTANCE_CREATED |
🎉 创建成功标志,内含实例 ID、名称、AD、机型、状态 |
launch_instance.log |
每次 launch_instance 调用的原始输出 |
setup_and_info.log |
tenancy、AD、subnet、image 等关键参数记录 |
ERROR_IN_CONFIG.log |
配置文件格式错误提示 |
UNHANDLED_ERROR.log |
未处理异常详情(可据此反馈 issue) |
images_list.json |
匹配镜像的快照,自动生成 |
八、给新手的速记清单 ✅
main.py的 5 步流程——取租户 → 取可用域 → 取子网 → 取镜像 → 启动实例,本身就是一份 OCI Python SDK 最小实战示例;itertools.cycle循环 AD + 容量错误休眠重试,是自动占坑的两大支柱;- 每次启动前先做幂等检查,脚本可安全重复运行;
- 配置只需两份文件:oci.env(可用 setup_env.sh 交互式生成)和 oci_config(含 API Key 绝对路径),其余交给
setup_init.sh。
