Fleet 标签Labels完全指南用动态、手动与 Host Vitals 标签精准定向你的主机【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet在 Fleet开源设备管理平台中标签Labels是把主机划分成可定向分组的核心机制——你可以用它来定向软件安装、策略policies、报告reports与配置描述文件configuration profiles也可以用它过滤主机列表视图。本文将基于官方标签文档并结合仓库中的源码与配置示例系统讲解标签的三种类型、定向语义、全局/专属作用域以及如何在配置描述文件上用标签做“先包含、再排除”的精细控制帮助你用 GitOps 或 UI 真正落地一套可维护、无冲突的标签体系。Fleet 官方建议优先使用标签而不是单独创建多个 fleet作为定向软件、策略、报告和配置描述文件的主要手段。标签的三种类型在 Fleet 中标签按照成员如何被加入分为三类对应源码 server/fleet/labels.go 中的LabelMembershipType枚举动态标签Dynamic基于查询query自动填充任何执行该标签 SQL 查询并返回结果的宿主机都会被自动纳入。可选地通过platform限定平台darwin、windows、linux、ubuntu、centos。其中linux会匹配任意Linux 发行版的主机。源码中ValidLabelPlatformVariants见 labels.go明确列出了合法取值其中空字符串代表“所有平台”这也是默认行为。手动标签Manual通过显式的主机列表指定成员主机可用hardware_serial、uuid或 Fleet 主机 ID 标识。适合一次性分组例如试点组pilot group。注意hostname作为主机标识符已被弃用请改用id、hardware_serial或uuid。Host vitals 标签根据单个 host vital 的取值仅支持精确匹配自动应用到主机。内置支持end_user_idp_department、end_user_idp_group需要接入 IdPOkta、Microsoft Entra ID、Google Workspace、authentik 或任意 SCIM 提供方可参考 foreign-vitals-map-idp-users-to-hosts.md也支持你自定义的任何 custom host vital。在 UI 中修改动态标签的查询/平台或修改 host vitals 标签的 criteria都需要先删除再重新创建该标签。此外Fleet 还区分了标签的label_typeLabelTypeRegular用户创建、可修改与LabelTypeBuiltInFleet 内置、不可修改见 labels.go。三种类型的 GitOps 定义方式在 docs/Configuration/yaml-files.md 中标签的每个字段语义如下name标签名称必须在所有全局与专属标签中唯一。在 GitOps 中修改name会导致标签被删除重建、成员关系被临时清空——建议先在 UI 中改名再改 YAML。platform额外平台过滤仅dynamic类型支持合法值同上。label_membership_typedynamic、manual、host_vitals默认dynamic。querySQL 语法过滤查询仅dynamic支持。hosts主机标识符列表id、hardware_serial、uuid仅manual支持。省略则保留现有成员不变提供但为空数组则清空所有成员。criteriahost vitals 标签的匹配条件命中vital数据与value相等的主机入组。若要匹配自定义 host vital需设置vital: custom_host_vital并额外指定custom_host_vital_id。约束query、hosts、criteria三者只能指定其中一个若都不指定将创建一个无成员的手动标签。这一约束在源码 ValidateLabelMembershipFields 中有完整校验——例如声明为manual却带query、声明为dynamic却带criteria或hosts、声明为host_vitals却缺少criteria都会返回带字段定位的InvalidArgumentError。labels: - name: Arm64 platform: darwin description: macOS hosts on the Arm64 architecture query: SELECT 1 FROM system_info WHERE cpu_type LIKE arm64% OR cpu_type LIKE aarch64% label_membership_type: dynamic - name: C-Suite description: Hosts belonging to the C-Suite label_membership_type: manual hosts: - IR7M6ZGQJM - JMFWY8VZ09 - name: Engineering department description: Hosts used by engineers label_membership_type: host_vitals criteria: vital: end_user_idp_department value: Engineering - name: Point of sale terminals description: Hosts whose Function custom host vital is set to Point of sale label_membership_type: host_vitals criteria: vital: custom_host_vital custom_host_vital_id: 2 value: Point of sale上面是default.yml中的内联写法也可以把标签拆到独立文件中再用path:单文件或paths:glob 通配引用例如lib/labels-name.labels.yml配合default.yml中的labels: - path: ./lib/labels/*.yml。仓库中还提供了一个真实的手动标签示例 docs/solutions/labels/pinned-canaries.labels.yml用于把特定主机固定进首批灰度与软件标题的labels_include_any配合使用。用标签定向与排除主机每个功能条目软件、策略、报告、配置描述文件使用一种作用域模式来定向或排除主机。配置描述文件额外支持通过 “Include any” 与 “Exclude any” 做自定义定向Scope行为可用于Include any定向拥有任意一个标签的主机软件、策略、报告、配置描述文件Include all定向拥有全部标签的主机软件、策略、报告、配置描述文件Exclude any排除拥有任意一个标签的主机软件、策略、配置描述文件注意上述表格中“报告reports”不支持Exclude any而软件、策略、报告、配置描述文件四者都支持Include any与Include all。在 docs/Configuration/yaml-files.md 中软件与 App Store 应用也通过labels_include_all/labels_include_any/labels_exclude_any字段复用同一套语义三者只能设置一个都不设置则定向所有主机。例如 App Store 应用Fleet Premium可按标签仅推送给 Product 与 Marketing 团队见 yaml-files.md。标签作用域全局 vs 专属标签的作用域取决于它在哪里创建而不是它的名字全局Global对所有 fleet 可用。由全局用户在 UI 创建或在default.yml中定义。专属FleetFleet Premium仅作用于单个 fleet且只与该 fleet 的全局标签并列可见。在该 fleet 的fleets/fleet-name.yml中定义。在这里定义只是把它限定到该 fleet并不会变成全局标签。源码层面Label结构体中的TeamID字段在 JSON 序列化时被renameto:fleet_id见 labels.go即专属标签在 API 层面对应fleet_id正是这种作用域设计的实现证据。建议标签名称共享同一个命名空间因此创建与已有全局或专属标签同名的标签会失败。若多个团队独立管理标签为避免冲突可采取两种策略——要么按负责人/fleet 加前缀如[Workstations] Kiosk、ws-kiosk要么把所有标签集中到一处如在default.yml中引用一个统一的labels/目录作为唯一事实来源让冲突在单个 PR 中暴露。管理标签的三种入口Fleet UI点击顶部导航右侧的头像选择Labels即可添加或编辑标签。REST API通过 Fleet 的 Labels API 端点进行增删改查。GitOps推荐实践通过fleetctl gitops以 YAML 管理标签。GitOps 下labels是可选键其行为受Settings Integrations Change management中的 labels exception 控制labels exception 关闭时标签由 git 管理。若default.yml包含labels则其中未列出的既有全局标签会被删除fleets/fleet-name.yml同理。省略labels键同样会删除该文件既有标签。GitOps 模式开启时Fleet UI 会禁止创建与编辑标签。labels exception 开启时标签在 git 之外管理。fleetctl gitops会保留既有标签且若 YAML 中包含labels键会直接失败UI 允许创建编辑标签即使 GitOps 模式开启。另外只要其他章节如policies、reports、software引用了某个标签该标签必须出现在labels章节中。用标签定向配置描述文件Fleet Premium配置描述文件configuration profiles自定义 OS 设置可以用标签控制哪些主机接收。Fleet 提供三种定向选项Include all仅拥有全部指定标签的主机接收labels_include_all。Include any拥有任意一个指定标签的主机接收labels_include_any。Exclude any拥有任意一个指定标签的主机被排除labels_exclude_any。未指定任何标签定向时配置描述文件会投递到该平台上的所有主机。组合 include 与 exclude你可以在同一个配置描述文件上把labels_exclude_any与labels_include_all或labels_include_any组合使用从而先包含一大组主机、再轻松划出例外而不必编写复杂的标签查询。labels_include_all与labels_include_any不能同时出现在同一个配置描述文件上。例如向 “Engineering” 或 “Product” 标签中的所有主机投递描述文件但跳过 “Macs on Sequoia” 标签中的主机controls: apple_settings: configuration_profiles: - path: ../lib/macos-profile.mobileconfig labels_include_any: - Engineering - Product labels_exclude_any: - Macs on Sequoia又如只向同时拥有Sonoma与Managed两个标签的主机投递同时排除标为 “Contractors” 的主机controls: apple_settings: configuration_profiles: - path: ../lib/macos-profile.mobileconfig labels_include_all: - Sonoma - Managed labels_exclude_any: - Contractors除了 GitOps YAML你还可以在 Fleet UI 的Controls OS settings Configuration profiles中添加或编辑配置描述文件时设置标签定向或通过 REST API 的 create-configuration-profile 端点完成。实践建议小结把标签当作首要定向原语避免为分组创建多个 fleet。动态标签适合“按属性自维护”的群体架构、平台、IdP 部门手动标签适合试点与例外场景host vitals 标签适合按 IdP 或自定义 vital 精确匹配。在 GitOps 中集中管理标签统一labels/目录用命名前缀避免跨团队冲突。配置描述文件的“Include any/All Exclude any”组合是划例外最省力的方式无需为每个例外重写查询。修改动态标签的查询/平台或 host vitals 的 criteria 需要删除重建改名则建议先在 UI 完成以保留成员关系。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
