infrahub-managing-checks

Infrahub 检查创建器

概述

为创建 Infrahub 检查提供专家指导。检查是 用户定义的验证逻辑（Python + GraphQL），会作为 提议变更流水线的一部分运行。如果检查记录了任何 错误，提议的变更就无法合并。

项目上下文

Infrahub 配置： !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

现有检查： !find . -name "*.py" -path "*/checks/*" 2>/dev/null | head -20

现有查询： !find . -name "*.gql" -path "*/queries/*" 2>/dev/null | head -20

适用场景

• 为提议的变更编写验证逻辑
• 创建数据质量防护措施（例如，检测机架冲突）
• 构建验证某一类型所有对象的全局检查
• 构建验证特定分组对象的定向检查
• 调试检查失败，或了解检查的生命周期

规则类别

优先级	类别	前缀	描述
CRITICAL	架构	architecture-	三个组成部分、全局检查与定向检查、执行流程
CRITICAL	Python 类	python-	InfrahubCheck 基类、validate()、log_error/log_info
HIGH	API 参考	api-	类属性、实例属性、方法、生命周期，以及哪些 API 会触发拒绝（GraphQL 错误的状态码为 200）
HIGH	注册	registration-	.infrahub.yml 配置、查询名称匹配、参数
MEDIUM（对于 patterns-shared-module 为 HIGH）	模式	patterns-	错误收集、共享实用工具、作用域验证、关系遍历验证、跨制品类型共享模块
HIGH	测试	testing-	Resources Testing Framework（由 YAML 驱动的测试）、infrahubctl 检查命令、提议变更的检查所运行的仓库提交

此技能依赖的架构功能

检查只有在能够获取并验证正确数据时才有用。大多数部署时的检查失败 实际上都源于架构侧的缺失：

如果检查……	架构（或 .infrahub.yml）必须……	参见
通过 GraphQL 读取属性	在架构节点上公开该属性，且名称相同（路径形如 name__value）	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
遍历关系以验证相关对象	定义关系的两端，并使用匹配的标识符；否则遍历不会返回任何内容	../infrahub-managing-schemas/rules/relationship-identifiers.md
根据相关节点的状态验证节点（子节点与父节点生命周期、对等节点一致性）	在查询中通过遍历关系获取相关节点的比较属性；检查只运行一个查询，不会延迟获取数据	rules/patterns-relationship-traversal.md
是定向检查（针对单个对象）	在 .infrahub.yml 中将 CoreStandardGroup 注册为 targets:，并映射 parameters: 以绑定 GraphQL 变量	rules/registration-config.md
需要按类型节点为 GraphQL 响应建立索引	在查询中选择 id 和 __typename — SDK 依赖这两项	../infrahub-common/graphql-queries.md
不应阻止合并，而只需添加说明	使用 self.log_info() 而非 log_error()；log_warning() 不存在	rules/python-validate.md

编写 Python 之前

如果可以用成本更低的层来表达约束，就用它。 Schema 约束会在加载时应用于每条写入 路径；Python 检查只会在提议变更的流程中运行， 因此通过其他路径创建的不合规数据会漏网。在使用 InfrahubCheck 之前，先看看这个简短的选择顺序：

信号	成本更低的层	参见规则
验证单个属性的唯一性、是否存在、允许值或正则表达式	Schema 约束（uniqueness_constraints、optional: false、kind: Dropdown 选项、regex）	yagni-python-validator-vs-schema-constraint
检查逻辑仅包含 GraphQL 查询和一条 if len(...) > 0: raise	一个 .gql 文件加 5 行 Python	yagni-redundant-check-that-graphql-can-answer
强制关系为单端关联或不可选	Schema cardinality: one、kind: Parent / Component、optional: false	yagni-python-validator-vs-schema-constraint

只有以上情况都不适用时，才应编写 Python 检查。rules/python-validate.md 中介绍的跨节点业务规则、 带外协调和有状态断言才是合理的使用场景。

如果检查通过 SDK 读取对象（而不只是使用其 GraphQL 查询），请使用生成的协议类为这些调用提供类型，而不是使用字符串 kind——例如 client.get(DcimDevice, ...)，而不是 kind="DcimDevice"。确保 --sync 协议变体与检查所用的客户端匹配。参见 protocols-adopt-typed-kinds。

检查基础

每项检查包含三个部分：

1. GraphQL 查询（.gql 文件）——获取要 验证的数据，并在 .infrahub.yml 的顶层 queries: 部分中注册
2. Python 类——继承自 InfrahubCheck， 设置 query = "<query_name>"，实现 validate()
3. 配置——在 .infrahub.yml 的 check_definitions 下声明（该部分不接受 query: 字段——见下文）

from infrahub_sdk.checks import InfrahubCheck


class MyCheck(InfrahubCheck):
    query = "my_query"  # Must match queries[].name in .infrahub.yml

    def validate(self, data: dict) -> None:
        # Validation logic here
        if something_is_wrong:
            self.log_error(
                message="Problem description"
            )

**查询绑定位置：**Python 类中的 query = "..."，而不是 check_definitions。仓库 配置模型使用 extra="forbid"，因此在 check_definitions: 下添加 query: 会导致 整个仓库配置验证失败。这是最常见的混淆点，与 generator_definitions: 不同，后者 确实接受顶层的 query:。参见 rules/registration-config.md。

工作流

创建检查时，请遵循以下步骤：

1. 了解验证目标 — 哪种数据 条件应阻止拟议的更改？确定 这是全局检查（针对某种类型的所有对象） 还是定向检查（针对特定分组）。阅读 rules/architecture-types.md。
2. 编写 GraphQL 查询 — 创建一个 .gql 文件， 用于获取要验证的数据。查询模式请参阅 ../infrahub-common/graphql-queries.md。 如果规则需要将某个节点与关联节点的状态进行比较（子节点与父节点的 生命周期、对等节点的一致性），则查询必须通过遍历关系 获取该关联属性——检查只运行一次查询，不会在之后获取数据。请参阅 rules/patterns-relationship-traversal.md。
3. 实现 Python 类 — 继承 InfrahubCheck，实现 validate()。类模式请参阅 rules/python-validate.md， 可用方法请参阅 rules/api-reference.md。如果检查会回调 Infrahub，也请阅读 rules/api-error-surfaces.md：被拒绝的 GraphQL 请求仍会返回 HTTP 200，因此依据状态码进行分支判断，会导致检查在本应捕获的失败情况下通过。如果逻辑与生成器或转换器共用，请先阅读 rules/patterns-shared-module.md，再考虑使用相对导入。
4. 在 .infrahub.yml 中注册 — 在 check_definitions 下添加检查。查询名称必须与 Python 类的 query 属性一致。请参阅 rules/registration-config.md。
5. 添加测试 — 在检查旁创建由 YAML 驱动的测试定义 （冒烟测试、单元测试、集成测试），以便在拟议更改 流水线中自动验证。请参阅 rules/testing-resource-framework.md。
6. 在本地测试 — 运行 infrahubctl check，针对功能分支进行验证。 请参阅 rules/testing-commands.md。 如需针对现有拟议更改运行已修改的检查，请阅读 rules/testing-proposed-change-commit.md： 流水线运行的是源分支仓库提交中的代码，而不是 main 中的代码；在通过 Git 同步的分支上进行分支变基也不会改变该提交。

参考资料

• reference.md —— 类 API、 log_error/log_info（没有 log_warning）、生命周期、 .infrahub.yml 注册方式（其中不含 query:， 与 generator_definitions 的格式不同）
• examples.md —— 完整的检查模式 （全局、定向、最简）
• ../infrahub-common/graphql-queries.md —— GraphQL 查询编写参考
• ../infrahub-common/infrahub-yml-reference.md —— .infrahub.yml 项目配置
• ../infrahub-common/rules/ —— 适用于所有技能的 共享规则 （Git 集成、缓存注意事项）
• ../infrahub-common/rules/workflow-information-priority.md —— 优先使用技能内容；遇到确实缺少的信息时（例如删除节点），如何查阅 docs.infrahub.app
• ../infrahub-managing-schemas/SKILL.md —— 架构定义检查所验证的内容
• rules/ —— 按类别前缀组织的各项规则