Add maskless `IPAddress` attribute kind

Merged
AJ
4mo ago
+788-93

partner PR in the SDK repo https://github.com/opsmill/infrahub-sdk-python/pull/1222

Why

IPHost is the only IP-address attribute kind, and it is backed by ipaddress.ip_interface(), so it always carries a prefix: 192.0.2.1 is stored as 192.0.2.1/32. Wherever the prefix is not part of the data — a DNS record target, a syslog destination, a BGP neighbour — that suffix leaks into display labels, HFIDs and API payloads with no way to opt out.

Adds an IPAddress attribute kind that accepts only a bare address and rejects anything carrying a prefix or netmask.

Non-goals: no change to IPHost/IPNetwork behaviour, no new IPAM capability, and no core schema attribute switches to the new kind.

Closes IFC-2947

What changed

Behavioral changes:

  • New IPAddress attribute kind. 10.0.0.1 and 2001:db8::1 are accepted; 10.0.0.1/32, 10.0.0.1/24, 10.0.0.0/255.255.255.0 and leading-zero forms such as 010.0.0.1 are rejected. IPv6 is normalized to its compressed lowercase form (2001:0DB8::0001 → 2001:db8::1), and an IPv4-mapped address keeps its family (::ffff:10.0.0.1).
  • Exposed as a distinct GraphQL type (__typename: "IPAddress") with value and version. The filter surface is identical to IPHost — __value, __values, __isnull, __source__id, __owner__id, __is_protected — because filters are derived generically and IPHost never exposed a prefix filter.
  • In the UI it renders as a plain text input, appears as a list-view column, and offers a text filter. A prefixed value is rejected inline in the form rather than round-tripping to a backend 400.
  • Changing an attribute's kind is now rejected when the stored values are not already canonical for the new kind. A kind change runs no data migration, so switching to IPHost previously left a bare 10.0.0.1 in the database while the canonical form is 10.0.0.1/32, silently breaking __value filters and uniqueness comparisons. This is the one pre-existing behaviour this PR changes, and it affects conversions into IPHost, IPNetwork, IPAddress and MacAddress — for example Text → MacAddress over aa-bb-cc-dd-ee-ff is now refused.
  • GraphQL rejects a prefixed value with 10.0.0.1/24 is not a valid IPAddress at target, and a schema load that flips IPAddress → IPHost (or the reverse) is refused per node with the offending value, leaving the schema and data unchanged.

Implementation notes:

  • The new kind reuses the existing AttributeIPHost value vertex in cypher rather than introducing its own label. prefixlen is stored as the family maximum because the shared MERGE interpolates it and neo4j rejects a null property; it is deliberately absent from the GraphQL type and from get_allowed_property_in_path(), so it is not queryable.
  • The canonicality check needs no list of the kinds it applies to. Kinds that do not normalize inherit an identity _normalize_value(), so the check is a no-op for them and a future normalizing kind is covered without touching the validator. _normalize_value() became a classmethod so a value can be checked without constructing an attribute; no override used instance state, so behaviour is unchanged.
  • ATTRIBUTE_PYTHON_TYPES["IPAddress"] is IPvAnyAddress, which is genuinely correct here — unlike the existing IPHost entry, which uses the same type despite IPvAnyAddress rejecting 10.0.0.1/32, the canonical IPHost value.

What stayed the same: no graph migration, no GRAPH_VERSION change, no new DB label or index, no change to IPHost/IPNetwork semantics, and no core schema node adopts the kind. backend/tests/component/core/graph/test_graph_constraints.py and test_graph_version.py pass unmodified, which is the evidence for that.

Suggested review order

  1. backend/infrahub/types.py and backend/infrahub/core/attribute.py — the kind itself and why it reuses the IPHost vertex.
  2. backend/infrahub/core/validators/attribute/kind.py — the only pre-existing behaviour this PR changes.
  3. frontend/app/src/entities/schema/domain/rules/validation/validate-ip-address-attribute.ts — hand-rolled IPv4/IPv6 parsing.
  4. Everything under schema/, docs/docs/reference/ and frontend/app/src/shared/api/*/generated/ is generated output.

How to review

Focus on the vertex-sharing decision and the kind-change rejection; those carry the risk. The frontend validator deserves scrutiny too — cubic caught two real IPv6 group-counting bugs there (a trailing dotted quad stands for two groups, and :: must stand for at least one), both fixed with regression tests.

Mechanical: the whole of commit chore(generated). Note that graphql-cache.d.ts shows ~132 changed lines, none of which mention IPAddress — it is gql.tada rehashing every cached document because the schema changed.

Worth a second opinion: sharing AttributeIPHost means the label no longer maps one-to-one to a kind, so new Cypher against it must gate on node kind or attribute name, as core/query/ipam.py already does. The alternative was a dedicated label, which costs a GRAPH_VERSION bump plus a migration and would have been silently incomplete anyway, since AttributeKindUpdateMigrationQuery never applies the IP labels on a kind change.

Impact & rollout

  • Backward compatibility: additive for the new kind. The kind-change rejection is the exception — schema updates that previously succeeded while corrupting stored values will now fail with a validation error naming each node. Normalize the values first, then change the kind.
  • Performance: unchanged. The kind shares the existing indexed vertex. Values sort lexically rather than numerically (10.0.0.10 before 10.0.0.2), since the binary index is only reachable through IPAM's own queries.
  • Config/env changes: none.
  • Deployment notes: requires a coordinated release with the SDK. AttributeSchema.kind is typed to the generated AttributeKind enum, so an SDK without IPADDRESS cannot load a schema using the kind. opsmill/infrahub-sdk-python#1222 must merge first; this PR's submodule pointer references it. No database migration is needed.

Checklist

  • Tests added/updated
  • Changelog entry added (uv run towncrier create ...)
  • External docs updated (if user-facing or ops-facing change)
  • Internal .md docs updated (internal knowledge and AI code tools knowledge)
  • I have reviewed AI generated content

Summary by cubic

Adds a new IPAddress attribute kind for bare IPs and enforces canonical-value checks on kind changes to prevent stale comparisons. Updates the python_sdk submodule to the merged SDK release that includes this kind.

  • New Features

    • New IPAddress kind stores a bare IP (no prefix/netmask). IPv6 normalizes to compressed lowercase. Values sort lexically.
    • Reuses AttributeIPHost for storage; writes family max prefix internally (not exposed).
    • GraphQL: new IPAddress type with value and version; REST/OpenAPI and python_sdk updated.
    • Frontend: input, list/table display, text filters, and validation (rejects values with “/” and malformed IPs).
    • Canonical-value check when changing kind; applies to IPHost, IPNetwork, IPAddress, and MacAddress.
  • Bug Fixes

    • Frontend IPAddress validator: correct IPv6 group counting and dotted-quad handling, and require "::" to cover at least one group, aligning with backend parsing.