Skip to main content

Understanding groups in Infrahub

Groups represent a fundamental organizational concept in Infrahub, providing a way to create logical collections of infrastructure objects. This topic explores how groups work, their underlying architecture, and the design principles that make them a powerful tool for infrastructure management.

What are groups?​

At their core, groups are containers that establish relationships between objects in your infrastructure. Think of them as dynamic collections that can span across different object types - you might group together devices, locations, and configurations that share a common purpose or characteristic.

Unlike traditional static lists, Infrahub groups are first-class objects in the graph database, meaning they have their own attributes, relationships, and lifecycle. This design allows groups to participate in the broader infrastructure model as active entities rather than passive containers.

The group architecture​

CoreGroup - the foundation​

Every group in Infrahub inherits from CoreGroup, a generic model that provides the essential structure. This inheritance model creates consistency while allowing specialization.

The CoreGroup defines two primary relationships:

  • Members: Objects that belong to the group
  • Subscribers: Objects that observe or react to changes in the group

This dual-relationship model reflects a key design decision: groups aren't just about membership, they're about creating actionable connections between objects.

Bidirectional relationships​

When an object becomes a member of a group, Infrahub automatically creates inverse relationships. Every object gains:

  • member_of_groups: A computed relationship showing all groups containing this object
  • subscriber_of_groups: A computed relationship showing all groups this object subscribes to

These automatic relationships enable powerful graph traversals. You can easily answer questions like "What groups does this device belong to?" or "What objects are affected by changes to this group?"

query {
  device(id: "device-123") {
    member_of_groups {
      name
      description
    }
  }
}

Types of groups​

Infrahub implements several specialized group types, each serving distinct purposes:

Standard groups​

Standard groups (CoreStandardGroup) are the general-purpose groups that users create and manage directly. They represent logical collections based on business needs - perhaps grouping all devices in a specific data center or all interfaces participating in a particular service.

Standard groups embody the principle of user control. You define the membership criteria, manage the members, and determine how the group integrates with your workflows.

Generator groups​

Generator groups (CoreGeneratorGroup) represent a different paradigm: dynamic membership based on generation rules. Rather than manually adding members, a generator creates objects and automatically adds them to the group.

This design solves the problem of maintaining consistency between generated objects and their logical groupings. When a generator creates 100 interfaces based on a template, they automatically belong to a group that tracks their origin and purpose.

Query groups​

Query groups (CoreGraphQLQueryGroup) introduce the concept of dynamic membership based on query results. The group's membership changes as the underlying data changes, maintaining a live view of objects matching specific criteria.

This approach reflects a shift from imperative (explicitly adding members) to declarative (defining membership criteria) group management.

The visibility model​

Infrahub distinguishes between two visibility levels for groups:

Default groups​

User-managed groups appear in the standard interface and are intended for direct interaction. These groups represent the organizational structure that users actively maintain and reference in their daily operations.

Internal groups​

System-managed groups operate behind the scenes, supporting Infrahub's internal processes. They track relationships that the system needs but users don't typically interact with directly.

The decision to hide internal groups by default reflects a focus on user experience - reducing visual complexity while maintaining the power of the underlying system. Users can toggle visibility when needed for debugging or advanced operations.

Groups as integration points​

Groups serve as a bridge between different Infrahub features, creating a unified way to target operations across the system.

Artifact generation​

When an artifact definition needs to generate configurations for multiple devices, it targets a group. This design decouples the artifact logic from specific device lists, making definitions more reusable and maintainable.

Transformation targets​

Transformations can operate on entire groups, applying consistent changes across all members. The group becomes the unit of operation, simplifying bulk updates and ensuring consistency.

Check definitions​

Validation checks can target groups, running the same validation logic across all members. This approach scales validation from individual objects to entire collections without duplicating logic.

Further reading​