摘要

自动化运维的第一步不是改密、巡检或批量修复,而是建立可信资产源。本文从实际落地出发,讲解如何用 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_id
  • name
  • status
  • vcpus
  • memory
  • disk
  • primary_ip4
  • cloud_flavor_id
  • cloud_flavor_name
  • cloud_image_id
  • cloud_image_name
  • cloud_vpc_id
  • cloud_charging_mode

这些字段来自云平台,是云主机的客观资源信息。同步脚本负责更新它们。

Ansible 权威字段

  • platform
  • 真实 OS 发行版
  • 真实 OS 版本
  • 运行时内核、补丁、服务状态等巡检信息

这里特别要注意:云平台返回的镜像名不一定等于真实操作系统。实际环境中可能出现类似 LinuxAgent-2021-10-22-10-42 这样的镜像名,它不适合作为 NetBox 的 Platform。因此 platform 字段应由 Ansible 登录主机后通过 facts 回填。

人工权威字段

  • environment
  • business_owner
  • owner
  • criticality
  • maintenance_window
  • allow_auto_password_change
  • allow_auto_file_upload
  • allow_auto_remediation
  • ansible_user
  • ansible_port
  • ansible_become
  • ansible_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、prod
  • business_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:登录用户,例如 bsoft
  • ansible_port:SSH 端口
  • ansible_become:是否启用 sudo 提权
  • ansible_become_method:提权方式,例如 sudo
  • login_protocol:登录协议,例如 ssh 或 winrm
  • ansible_platform:Ansible 平台类型,例如 linux 或 windows

这里有一个实际踩坑点:ansible_port 建议使用 Text 类型,而不是 Integer 类型。原因是某些同步和序列化场景下,Ansible 或 NetBox API 会把端口值当字符串处理,Integer 类型容易报类型校验错误。最终在 Dynamic Inventory 中再通过 | int 转换即可。

云平台字段

  • cloud_provider
  • cloud_region
  • cloud_instance_id
  • cloud_image_id
  • cloud_image_name
  • cloud_flavor_id
  • cloud_flavor_name
  • cloud_vpc_id
  • cloud_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 中的资产事实和策略字段展开,做到既高效又可控。