Documentation
¶
Overview ¶
Package group implements host groups: operator-curated SITES (manual membership) and OS CATEGORIES (auto membership derived from hosts.os_family, or manual workload groups). A host belongs to many groups. The service owns CRUD, membership, the maintenance flag, and the per-group rollups the Groups page renders.
Spec: api-groups v1.0.0.
Index ¶
- Variables
- type CreateInput
- type FleetSummary
- type Group
- type GroupWithRollup
- type Kind
- type MemberChip
- type Membership
- type Rollup
- type Service
- func (s *Service) AddMember(ctx context.Context, groupID, hostID uuid.UUID) error
- func (s *Service) Create(ctx context.Context, in CreateInput) (Group, error)
- func (s *Service) Delete(ctx context.Context, id uuid.UUID) error
- func (s *Service) Get(ctx context.Context, id uuid.UUID) (Group, error)
- func (s *Service) List(ctx context.Context, orgDefault string) ([]GroupWithRollup, error)
- func (s *Service) RemoveMember(ctx context.Context, groupID, hostID uuid.UUID) error
- func (s *Service) ScopeGroup(ctx context.Context, groupID uuid.UUID) (string, []uuid.UUID, error)
- func (s *Service) ScopeGroupIn(ctx context.Context, q db.Queryer, groupID uuid.UUID) (string, []uuid.UUID, error)
- func (s *Service) SetMaintenance(ctx context.Context, id uuid.UUID, on bool) (Group, error)
- func (s *Service) SetTarget(ctx context.Context, id uuid.UUID, family string) (Group, error)
- func (s *Service) Summary(ctx context.Context, orgDefault string) (FleetSummary, error)
- func (s *Service) Update(ctx context.Context, id uuid.UUID, in UpdateInput) (Group, error)
- type UpdateInput
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("group: not found") ErrInvalidKind = errors.New("group: kind must be site or os_category") ErrInvalidMembership = errors.New("group: membership must be manual or auto") ErrAutoNeedsFamily = errors.New("group: auto membership requires a match_family") ErrManualHasFamily = errors.New("group: manual membership must not set match_family") ErrSiteMustBeManual = errors.New("group: a site must use manual membership") ErrDuplicateFamily = errors.New("group: an auto group already exists for that OS family") ErrEmptyName = errors.New("group: name is required") ErrTargetOnlyOnSite = errors.New("group: only a site group may carry a compliance target") ErrInvalidTarget = errors.New("group: target_framework is too long or has invalid characters") )
Sentinel errors. Handlers map these to HTTP status codes.
Functions ¶
This section is empty.
Types ¶
type CreateInput ¶
type CreateInput struct {
Name string
Kind Kind
Subtype string
Color string
Membership Membership
MatchFamily string
}
CreateInput is the payload to create a group.
type FleetSummary ¶
type FleetSummary struct {
Groups int
Sites int
OSCategories int
HostsMaintenance int
// Score is GET /fleet/score's own answer, whole. The Groups page and the
// fleet KPI cannot disagree because there is only one computation and one
// mapping.
Score fleetrollup.Score
Ungrouped int
}
FleetSummary backs the Groups-page KPI row.
type Group ¶
type Group struct {
ID uuid.UUID
Name string
Kind Kind
Subtype string
Color string
Membership Membership
MatchFamily string // "" for manual groups
Maintenance bool
// TargetFramework is the compliance TARGET family a member host is held to
// (Phase 3). "" means no group target. Only a site group may carry one
// (D1); the service rejects a target on an os_category group.
TargetFramework string
CreatedAt time.Time
UpdatedAt time.Time
}
Group is one row of the groups table.
type GroupWithRollup ¶
GroupWithRollup is a group plus its computed metrics.
type Kind ¶
type Kind string
Kind distinguishes a site (environment/topology) from an os_category (platform/workload).
type MemberChip ¶
type MemberChip struct {
HostID uuid.UUID
Hostname string
// Status is the host's monitoring band (online/degraded/critical/
// down/...) or "unknown" when never probed.
Status string
}
MemberChip is a compact member-host descriptor for the card preview.
type Membership ¶
type Membership string
Membership is how a group's hosts are determined.
const ( // MembershipManual: hosts are assigned explicitly (group_members). MembershipManual Membership = "manual" // MembershipAuto: hosts are every host whose os_family == MatchFamily, // computed live (no stored membership, no backfill). MembershipAuto Membership = "auto" )
type Rollup ¶
type Rollup struct {
Hosts int
Online int
Down int
CriticalHosts int
// Score is the group's compliance average in the SAME shape the fleet uses:
// the number, the outcomes behind it, the coverage status, the population,
// and the lens. Sharing the shape is what lets one wire mapper serve both,
// so a group average cannot ship without the metadata a fleet average
// carries.
Score fleetrollup.Score
Members []MemberChip
}
Rollup is the computed member summary the list view shows per group.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service owns group CRUD, membership, and the per-group rollups.
func NewService ¶
func (*Service) AddMember ¶
AddMember assigns a host to a MANUAL group. Auto groups reject manual membership (their members are derived).
func (*Service) RemoveMember ¶
RemoveMember removes a host from a manual group.
func (*Service) ScopeGroup ¶
ScopeGroup resolves a group id to its display name and the set of active member host ids, for callers that scope a fleet computation to one group (e.g. a scoped Reports executive summary). Manual groups read group_members; auto groups derive from hosts.os_family == match_family. Returns ErrNotFound when the group does not exist. An empty group yields a non-nil, empty id slice (a valid "no hosts" scope), distinct from the unscoped all-hosts case the caller models as no group at all.
func (*Service) ScopeGroupIn ¶ added in v0.8.0
func (s *Service) ScopeGroupIn(ctx context.Context, q db.Queryer, groupID uuid.UUID) (string, []uuid.UUID, error)
ScopeGroupIn is ScopeGroup against a caller-supplied queryer, so the group name and its member set can be read inside the caller's transaction.
func (*Service) SetMaintenance ¶
SetMaintenance toggles a group's maintenance flag.
func (*Service) SetTarget ¶ added in v0.5.0
SetTarget sets (or clears, when family is "") the group's compliance target framework. Only a site group may carry a target (D1): an os_category group is an automatic OS grouping, not a statement of compliance intent, so a target on one is rejected with ErrTargetOnlyOnSite.
type UpdateInput ¶
UpdateInput patches a group's editable fields.