摘要
自动化运维的第一步不是改密、巡检或批量修复,而是建立可信资产源。本文从实际落地出发,讲解如何用 NetBox 作为唯一 CMDB,结合 Ansible 动态 Inventory,并通过华为云 API 同步云主机规格、IP、磁盘等资产信息,最终构建一套可扩展、可审计、边界清晰的自动化资产管理体系。
背景:为什么自动化之前要先管好资产
很多自动化项目一开始就想做密码轮换、基线修复、批量巡检、漏洞加固。但真正落地时会发现,第一个挡在前面的不是 Playbook 怎么写,而是一个更基础的问题:
我到底有哪些机器?它们归属哪个业务?谁负责?哪些允许自动操作?哪些只能人工确认?
如果这些问题没有统一答案,自动化越强,风险越大。
在传统环境里,Ansible 通常依赖静态 hosts.ini。这种方式能快速起步,但随着主机数量上升,会逐渐暴露几个问题:
- 静态主机清单容易过期,IP 变更后无人维护。
- 业务归属、负责人、环境、重要等级等信息散落在 Excel、堡垒机、脚本变量里。
- Ansible 执行边界不清晰,无法判断某台机器是否允许自动改密、自动上传文件或自动修复。
- 云平台里的实例规格、磁盘、IP 等信息与 CMDB 不一致。
- 同一台机器可能在云平台、NetBox、Ansible 静态 hosts 中出现多个名字。
因此,第一阶段的目标不是马上做高危自动化,而是先建立一套可信资产源:
NetBox 作为唯一 CMDB,云平台 API 负责同步客观资产事实,Ansible 通过 NetBox 动态 Inventory 执行任务,所有高风险自动化动作都由 NetBox 策略字段控制。
总体架构设计
最终形成的架构可以拆成三层:
云平台 API 层
负责提供云主机的客观事实,例如实例 ID、实例名称、状态、vCPU、内存、磁盘、主 IP、规格、镜像、VPC 等。这些字段由云平台产生,可信度最高。
NetBox CMDB 层
负责保存资产、业务属性和自动化策略。NetBox 不保存密码,只保存资产事实、归属信息和自动化控制开关。
Ansible 执行层
负责实际连接主机和执行任务。Ansible 不再维护静态 hosts,而是通过 NetBox Dynamic Inventory 自动获取主机、分组和连接变量。
这个架构的关键,不是简单地“把云主机导进 NetBox”,而是明确每个字段由谁负责写入。
字段级权威来源:避免 CMDB 数据打架
在 CMDB 建设中,最容易踩的坑是多个系统同时写同一个字段。例如云平台同步一次、Ansible gather facts 再写一次、人工又在页面改一次,最后谁也不知道哪个值是真的。
因此,我们先定义字段级权威来源。
云平台 API 权威字段
cloud_instance_idnamestatusvcpusmemorydiskprimary_ip4cloud_flavor_idcloud_flavor_namecloud_image_idcloud_image_namecloud_vpc_idcloud_charging_mode
这些字段来自云平台,是云主机的客观资源信息。同步脚本负责更新它们。
Ansible 权威字段
platform- 真实 OS 发行版
- 真实 OS 版本
- 运行时内核、补丁、服务状态等巡检信息
这里特别要注意:云平台返回的镜像名不一定等于真实操作系统。实际环境中可能出现类似 LinuxAgent-2021-10-22-10-42 这样的镜像名,它不适合作为 NetBox 的 Platform。因此 platform 字段应由 Ansible 登录主机后通过 facts 回填。
人工权威字段
environmentbusiness_ownerownercriticalitymaintenance_windowallow_auto_password_changeallow_auto_file_uploadallow_auto_remediationansible_useransible_portansible_becomeansible_become_method
这些字段带有业务含义或执行策略,不应被云平台 API 覆盖。
核心原则:同一个字段只能有一个权威写入方。 这是避免 CMDB 长期混乱的关键。
NetBox 建模:虚拟机应该进 Virtual Machines
一开始很容易把所有资产都导入到 NetBox 的 Devices 里。这样做虽然能看到设备名称和 IP,但对于虚拟机来说并不合适。
NetBox 中更合理的模型是:
- 物理服务器、交换机、防火墙、存储设备进入
DCIM -> Devices - 云主机和虚拟机进入
Virtualization -> Virtual Machines
虚拟机模型天然支持 vCPU、内存、磁盘、Cluster、Primary IP 等字段,更适合承载云主机资产。
NetBox 自定义字段设计
为了支撑自动化控制和云平台同步,需要为 virtualization.virtualmachine 增加一批自定义字段。
业务归属字段
environment:环境,例如dev、test、prodbusiness_owner:业务归属owner:技术负责人criticality:重要等级maintenance_window:维护窗口
这些字段用于资产治理和变更管理。
自动化策略字段
allow_auto_password_change:是否允许自动改密allow_auto_file_upload:是否允许自动上传文件allow_auto_remediation:是否允许自动巡检修复
这些字段决定 Ansible 是否能对某台主机执行高风险动作。
例如后续改密 Playbook 必须显式判断:
when:
- allow_auto_password_change | bool
这样可以避免 Playbook 被错误地打到不允许自动改密的机器上。
Ansible 连接字段
ansible_user:登录用户,例如bsoftansible_port:SSH 端口ansible_become:是否启用 sudo 提权ansible_become_method:提权方式,例如sudologin_protocol:登录协议,例如ssh或winrmansible_platform:Ansible 平台类型,例如linux或windows
这里有一个实际踩坑点:ansible_port 建议使用 Text 类型,而不是 Integer 类型。原因是某些同步和序列化场景下,Ansible 或 NetBox API 会把端口值当字符串处理,Integer 类型容易报类型校验错误。最终在 Dynamic Inventory 中再通过 | int 转换即可。
云平台字段
cloud_providercloud_regioncloud_instance_idcloud_image_idcloud_image_namecloud_flavor_idcloud_flavor_namecloud_vpc_idcloud_charging_mode
其中最重要的是 cloud_instance_id。同步脚本必须用它作为唯一锚点匹配 NetBox 中的 VM,而不是用主机名或 IP。
主机名会变,IP 也可能变,但云实例 ID 是稳定的。CMDB 同步应该以稳定 ID 为锚点。
Ansible 动态 Inventory 配置
NetBox 中有了资产和连接字段后,Ansible 就可以不再依赖静态 hosts.ini。下面是关键的 netbox.yml 配置示例:
plugin: netbox.netbox.nb_inventory
api_endpoint: http://netbox.example.com:8000
token: your_netbox_token
validate_certs: false
config_context: false
interfaces: true
fetch_all: true
query_filters:
- status: active
compose:
ansible_host: primary_ip4.address.split('/')[0]
ansible_connection: "'winrm' if custom_fields.login_protocol == 'winrm' else 'ssh'"
ansible_port: custom_fields.ansible_port | int
ansible_user: custom_fields.ansible_user
ansible_become: custom_fields.ansible_become | bool
ansible_become_method: custom_fields.ansible_become_method | default('sudo')
ansible_become_user: "'root'"
ansible_platform: custom_fields.ansible_platform
login_protocol: custom_fields.login_protocol
maintenance_window: custom_fields.maintenance_window
allow_auto_password_change: custom_fields.allow_auto_password_change
allow_auto_file_upload: custom_fields.allow_auto_file_upload
allow_auto_remediation: custom_fields.allow_auto_remediation
keyed_groups:
- key: custom_fields.environment
prefix: env
- key: platform.name
prefix: os
- key: custom_fields.business_owner
prefix: biz
- key: custom_fields.ansible_platform
prefix: platform
- key: custom_fields.login_protocol
prefix: protocol
这段配置做了几件事:
- 从 NetBox 的
primary_ip4中取出 IP,并去掉/32 - 根据
login_protocol自动选择ssh或winrm - 从 NetBox 自定义字段中读取连接端口、登录用户、提权方式
- 根据环境、系统、业务、平台、协议自动生成 Ansible 分组
如果某台机器在 NetBox 中配置如下:
{
"ansible_host": "10.66.0.10",
"ansible_port": "53802",
"ansible_user": "dev",
"ansible_become": true,
"ansible_become_method": "sudo"
}
Ansible 就能自动以 dev 用户、指定端口登录,并通过免密 sudo 提权到 root。
华为云 API 同步脚本思路
云平台同步脚本的职责是只读读取云主机数据,并写入 NetBox 的 VM 模型。
同步脚本的核心流程如下:
- 使用华为云 SDK 调用 ECS 云主机详情列表接口
- 遍历返回的云主机列表
- 提取实例 ID、名称、状态、规格、IP、镜像、VPC 等信息
- 调用磁盘接口获取挂载磁盘容量
- 以
cloud_instance_id为锚点查找 NetBox VM - 已存在则更新,不存在则创建
- 创建或更新 VM 的
mgmt接口和primary_ip4 - 不覆盖人工维护的业务字段和自动化策略字段
查询云主机列表
华为云 SDK 查询云主机列表的核心代码如下:
import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkcore.region.region import Region
from huaweicloudsdkecs.v2 import EcsClient, ListServersDetailsRequest
def get_env(name):
value = os.environ.get(name)
if not value:
raise RuntimeError(f"Missing environment variable: {name}")
return value
def list_ecs_servers():
ak = get_env("HCLOUD_AK")
sk = get_env("HCLOUD_SK")
project_id = get_env("HCLOUD_PROJECT_ID")
endpoint = get_env("HCLOUD_ECS_ENDPOINT")
region = os.environ.get("HCLOUD_REGION", "region-1")
cred = BasicCredentials(ak, sk, project_id)
client = (
EcsClient.new_builder()
.with_credentials(cred)
.with_region(Region(region, endpoint))
.build()
)
servers = []
offset = 1
limit = 100
while True:
req = ListServersDetailsRequest()
req.offset = offset
req.limit = limit
resp = client.list_servers_details(req)
batch = resp.servers or []
servers.extend(batch)
if len(batch) < limit:
break
offset += 1
return servers
这段代码使用分页方式拉取全部云主机。limit 设置为 100,适合中小规模环境。生产环境如果云主机数量更大,可以继续提高分页健壮性和重试机制。
运行前通过环境变量传入敏感信息:
export HCLOUD_AK="your-ak"
export HCLOUD_SK="your-sk"
export HCLOUD_PROJECT_ID="your-project-id"
export HCLOUD_ECS_ENDPOINT="https://ecs.region.example.com"
export HCLOUD_REGION="region-1"
这里不要把 AK/SK 写死在代码里,更不要提交到 Git。
提取主 IP 地址
ECS 返回的地址结构通常是一个以网络 ID 为 key 的字典,每个网络下有多个地址对象。因此需要提取 IPv4,并优先选择 primary=true 或 fixed 类型地址。
def first_ipv4_address(addresses):
if not addresses:
return None
candidates = []
for _, items in addresses.items():
for item in items:
data = item.to_dict() if hasattr(item, "to_dict") else item
if str(data.get("version")) != "4":
continue
candidates.append(data)
for item in candidates:
if item.get("primary") is True:
return item.get("addr")
for item in candidates:
if item.get("OS-EXT-IPS:type") == "fixed":
return item.get("addr")
return candidates[0].get("addr") if candidates else None
NetBox 中 IP 地址建议使用 CIDR 格式,例如 10.66.0.10/32。Ansible 动态 Inventory 中再通过 split('/')[0] 提取纯 IP。
查询云主机磁盘容量
ECS 详情接口中的 flavor.disk 并不可靠,在实际环境中经常返回 0。因此要调用磁盘接口:
GET /v2.1/servers/{server_id}/block_device
这个接口返回 volumeAttachments,其中每块磁盘都有 size 字段,单位是 GB。
由于 SDK 未必封装该接口,我们采用手写 SDK-HMAC-SHA256 签名方式请求。
import hmac
import hashlib
import datetime
import requests
import urllib3
urllib3.disable_warnings()
def signed_get_json(host, path):
ak = get_env("HCLOUD_AK")
sk = get_env("HCLOUD_SK")
method = "GET"
request_uri = path
canonical_uri = path
if not canonical_uri.endswith("/"):
canonical_uri += "/"
x_sdk_date = datetime.datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
payload_hash = hashlib.sha256(b"").hexdigest()
canonical_headers = f"host:{host}\nx-sdk-date:{x_sdk_date}\n"
signed_headers = "host;x-sdk-date"
canonical_request = "\n".join([
method,
canonical_uri,
"",
canonical_headers,
signed_headers,
payload_hash,
])
hashed_request = hashlib.sha256(canonical_request.encode()).hexdigest()
string_to_sign = "\n".join([
"SDK-HMAC-SHA256",
x_sdk_date,
hashed_request,
])
signature = hmac.new(
sk.encode(),
string_to_sign.encode(),
hashlib.sha256,
).hexdigest()
authorization = (
f"SDK-HMAC-SHA256 Access={ak}, "
f"SignedHeaders={signed_headers}, Signature={signature}"
)
url = f"https://{host}{request_uri}"
headers = {
"Host": host,
"X-Sdk-Date": x_sdk_date,
"Authorization": authorization,
}
resp = requests.get(url, headers=headers, timeout=20, verify=False)
if resp.status_code != 200:
raise RuntimeError(f"GET {path} failed: {resp.status_code} {resp.text}")
return resp.json()
这里最重要的是 request_uri 和 canonical_uri 必须分开。canonical_uri 用于签名,需要补结尾斜杠;request_uri 用于实际请求,不能补结尾斜杠。
基于该签名函数,可以实现磁盘容量统计:
def get_server_disk_mb(server_id):
host = os.environ.get("HCLOUD_ECS_HOST", "ecs.region.example.com")
path = f"/v2.1/servers/{server_id}/block_device"
try:
data = signed_get_json(host, path)
except Exception as exc:
print(f"[WARN] failed to query disk for server {server_id}: {exc}")
return None
attachments = data.get("volumeAttachments", [])
total_gb = 0
for volume in attachments:
total_gb += int(volume.get("size", 0))
return total_gb * 1024
NetBox VM 的 disk 字段单位是 MB,因此这里将 GB 乘以 1024。
写入 NetBox Virtual Machines
同步 NetBox 时,不能用主机名或 IP 作为唯一依据。更合理的做法是使用云平台实例 ID 存入 cloud_instance_id,并通过该字段查找已有 VM。
def get_vm_by_cloud_id(nb, cloud_instance_id):
matches = list(
nb.virtualization.virtual_machines.filter(
cf_cloud_instance_id=cloud_instance_id
)
)
return matches[0] if matches else None
写入 VM 的核心逻辑如下:
def sync_server(nb, server, cluster, apply):
instance_id = server.id
name = server.name
metadata = server.metadata or {}
flavor = server.flavor
primary_ip = first_ipv4_address(server.addresses or {})
disk_mb = get_server_disk_mb(instance_id)
image_id = ""
if server.image:
image_data = server.image.to_dict() if hasattr(server.image, "to_dict") else server.image
image_id = image_data.get("id", "")
image_name = metadata.get("image_name", "")
custom_fields = {
"cloud_provider": "huawei",
"cloud_region": os.environ.get("HCLOUD_REGION", ""),
"cloud_instance_id": instance_id,
"cloud_image_id": image_id,
"cloud_image_name": image_name,
"cloud_flavor_id": flavor.id if flavor else "",
"cloud_flavor_name": flavor.name if flavor else "",
"cloud_vpc_id": metadata.get("vpc_id", ""),
"cloud_charging_mode": metadata.get("charging_mode", ""),
}
data = {
"name": name,
"status": "active" if server.status == "ACTIVE" else "offline",
"cluster": cluster.id if cluster else None,
"vcpus": int(flavor.vcpus) if flavor and flavor.vcpus else None,
"memory": int(flavor.ram) if flavor and flavor.ram else None,
"custom_fields": custom_fields,
}
if disk_mb is not None:
data["disk"] = disk_mb
vm = get_vm_by_cloud_id(nb, instance_id)
if not apply:
action = "update" if vm else "create"
print(f"[DRY-RUN] {action} VM: {name}")
print(f" cloud_instance_id: {instance_id}")
print(f" status: {data['status']}")
print(f" vcpus: {data['vcpus']}")
print(f" memory_mb: {data['memory']}")
print(f" disk_mb: {data.get('disk', 'skipped')}")
print(f" primary_ip: {primary_ip}")
print(f" cloud_flavor_name: {custom_fields['cloud_flavor_name']}")
print(f" cloud_image_name: {custom_fields['cloud_image_name']}")
print(" platform: skipped, managed by Ansible facts")
return
if vm:
for key, value in data.items():
if value is not None:
setattr(vm, key, value)
vm.save()
else:
vm = nb.virtualization.virtual_machines.create(data)
iface = ensure_vm_interface(nb, vm, "mgmt", apply)
ensure_primary_ip(nb, vm, iface, primary_ip, apply)
这里刻意没有写 platform 字段,因为真实操作系统版本后续由 Ansible 回填。
处理主 IP 与 IP 冲突
NetBox 的 IP 地址对象要求使用 CIDR 格式,例如 10.66.0.10/32。同步时需要创建或更新 IP,并绑定到 VM 的 mgmt 接口。
实际落地时,可能遇到某个 IP 已经是旧对象的 primary IP。此时 NetBox 不允许直接将该 IP 改绑到新 VM,否则会报:
Cannot reassign IP address while it is designated as the primary IP for the parent object
更安全的处理方式不是强行抢占,而是跳过并告警:
def ensure_primary_ip(nb, vm, iface, ip_addr, apply):
if not ip_addr:
return
address = f"{ip_addr}/32"
ip_obj = nb.ipam.ip_addresses.get(address=address)
if not apply:
print(f"[DRY-RUN] ensure IP {address} -> {vm.name}/mgmt")
return
if ip_obj:
assigned_object = getattr(ip_obj, "assigned_object", None)
if assigned_object:
assigned_name = (
getattr(assigned_object, "display", None)
or getattr(assigned_object, "name", None)
)
print(
f"[WARN] IP {address} already exists and is assigned to "
f"{assigned_name}. Skip reassignment for VM {vm.name}."
)
return
ip_obj.assigned_object_type = "virtualization.vminterface"
ip_obj.assigned_object_id = iface.id
ip_obj.save()
else:
ip_obj = nb.ipam.ip_addresses.create(
address=address,
status="active",
assigned_object_type="virtualization.vminterface",
assigned_object_id=iface.id,
)
vm.primary_ip4 = ip_obj.id
vm.save()
这段逻辑适合第一轮同步。先把 VM 资产导入,冲突 IP 由人工确认后再清理,避免脚本误抢正式资产的地址。
Dry-run 优先,确认后再 Apply
正式写入 NetBox 前,脚本应默认以 dry-run 模式运行,只打印将要创建或更新的对象。
示例输出:
[DRY-RUN] update VM: ecs-e09b-test
cloud_instance_id: 4aa41969-1601-44af-ae97-dcf78d0a735b
cloud_provider: huawei
cloud_region: region-1
status: active
vcpus: 1
memory_mb: 2048
disk_mb: 40960
primary_ip: 10.66.0.10
cloud_flavor_id: s7n.medium.2
cloud_flavor_name: s7n.medium.2
cloud_image_id: b53be044-002b-4265-bef5-5068f65991fd
cloud_image_name: CentOS 7.9 64bit
cloud_vpc_id: 11fbf5a7-592c-4325-9998-0fa2f777ada7
cloud_charging_mode: 0
platform: skipped, managed by Ansible facts
确认输出无误后,再执行写入:
python3 sync_HCLOUD_ecs_to_netbox.py --apply
建议第一轮导入后,在 NetBox 页面抽查几台 VM,重点确认:
- vCPU、内存、磁盘是否正确
- 主 IP 是否正确
cloud_instance_id是否有值cloud_flavor_name和cloud_image_name是否有值platform是否保持为空或未被云 API 覆盖
关键踩坑总结
ip_location 自定义字段导致 IP 创建失败
NetBox 中已有 IP 地址对象自定义字段 ip_location,并且被设置为必填。脚本创建 IP 时没有传该字段,导致接口报错。
处理方式是将该字段改为非必填,或给它设置默认值。
ansible_port 使用 Integer 类型导致导入失败
一开始将 ansible_port 建成 Integer 类型,但 NetBox API 对自定义字段类型校验很严格。经过 Ansible 和 YAML 序列化后,端口值容易变成字符串,导致报错。
最终方案是将 ansible_port 改为 Text 类型,在动态 Inventory 中通过 | int 转换。
ansible_become 被 Inventory 覆盖
测试时即使命令行加了 -b,执行 id 仍然显示普通用户。这是因为 Inventory 中的 ansible_become=false 优先级高于命令行参数。
解决方式是在 NetBox 中将 ansible_become 设置为 true,并在 compose 中写成:
ansible_become: custom_fields.ansible_become | bool
同时确保目标机普通用户具备免密 sudo。
同步脚本不能覆盖人工策略字段
云同步脚本只应该更新云平台权威字段。业务归属、负责人、环境、维护窗口、自动化开关等字段应保留人工维护结果。
如果脚本每次都覆盖这些字段,会导致 CMDB 变成“云平台镜像”,失去业务管理价值。
云镜像名不等于真实操作系统
云平台返回的 cloud_image_name 可能是 CentOS 7.9 64bit,也可能是模板名或 Agent 镜像名。它适合作为云平台字段保存,但不适合作为 NetBox 的 platform。
真实 OS 应由 Ansible 后续通过 gather_facts 回填。
下一步:用 Ansible 回填真实 Platform
完成云平台同步后,下一步可以写一个只负责 OS 回填的 Playbook:
- 从 NetBox 动态 Inventory 获取主机
- 使用 Ansible 登录主机并
gather_facts - 提取
ansible_distribution和ansible_distribution_version - 组合成类似
CentOS 7.9、Ubuntu 22.04的 Platform - 回写 NetBox VM 的
platform
这样就形成了完整闭环:
云平台 API -> 硬件、规格、网络、磁盘
Ansible -> 真实 OS、运行时信息
NetBox -> 统一 CMDB、业务属性、自动化策略
总结
这套方案的价值不只是“把云主机导进 NetBox”,而是建立一套可长期演进的资产管理边界。
云平台负责提供客观资源事实,NetBox 负责承载 CMDB 和自动化策略,Ansible 负责执行任务并补充运行时事实。三者职责清晰,字段权威明确,才能避免后续自动化越做越乱。
对于自动化运维来说,最重要的不是先写多少 Playbook,而是先回答清楚:
哪些机器存在?它们属于谁?允许自动化做到什么程度?这些答案由谁维护?
当这套资产基座建立起来之后,后续无论是批量巡检、补丁更新、密码轮换还是合规检查,都可以围绕 NetBox 中的资产事实和策略字段展开,做到既高效又可控。