parser

Documentation

Overview

Package parser reads fleet-gitops YAML files, resolves path: references, and produces normalized ParsedRepo structures for diffing. The schema and validation rules are derived from Fleet's Go source code, not documentation.

Index

• Variables
• func IsNoTeam(name, sourceFile string) bool
• func MatchesAnyTeam(name string, filters []string) bool
• func NormalizeSoftwarePath(p string) string
• func ValidateLogging(logging string) bool
• func ValidatePlatform(platform string) []string
• type ParseError
  • func (e ParseError) Error() string
• type ParsedAppStoreApp
• type ParsedFleetApp
• type ParsedGlobal
• type ParsedLabel
• type ParsedPolicy
• type ParsedProfile
• type ParsedQuery
• type ParsedRepo
  • func ParseRepo(root string, teamFilters []string, defaultFile string) (*ParsedRepo, error)
• type ParsedScript
• type ParsedSoftware
• type ParsedSoftwarePackage
• type ParsedTeam

Variables

var ValidLabelMembershipTypes = map[string]bool{
	"dynamic":     true,
	"manual":      true,
	"host_vitals": true,
}

ValidLabelMembershipTypes lists the label membership types Fleet accepts (from server/fleet/labels.go).

var ValidLogging = map[string]bool{
	"snapshot":                     true,
	"differential":                 true,
	"differential_ignore_removals": true,
}

ValidLogging lists the query logging types Fleet accepts (from server/fleet/queries.go).

var ValidPlatforms = map[string]bool{
	"darwin":  true,
	"windows": true,
	"linux":   true,
	"chrome":  true,
}

ValidPlatforms lists the platform identifiers Fleet accepts (from server/fleet/policies.go and queries.go).

var ValidTopLevelKeys = map[string]bool{
	"name":          true,
	"team_settings": true,
	"org_settings":  true,
	"agent_options": true,
	"controls":      true,
	"policies":      true,
	"queries":       true,
	"software":      true,
	"labels":        true,

	"settings": true,
	"reports":  true,
}

ValidTopLevelKeys lists the top-level YAML keys fleetctl gitops accepts (from pkg/spec/gitops.go).

Functions

func IsNoTeam

func IsNoTeam(name, sourceFile string) bool

IsNoTeam reports whether a parsed team file describes Fleet's special "hosts not assigned to any team" bucket rather than a real team.

Fleet calls this bucket "No team" in the teams/ layout (teams/no-team.yml) and "Unassigned" in the fleets/ layout (fleets/unassigned.yml) — fleetctl logs its work on that file as "... for unassigned hosts". Either way it always exists, is never created, and is NOT returned by GET /teams, so callers must not treat its absence there as a new team.

Matched on the team name and, as a fallback for a file whose name: key was spelled differently, the source file's base name.

func MatchesAnyTeam

func MatchesAnyTeam(name string, filters []string) bool

MatchesAnyTeam reports whether name case-insensitively matches any filter.

func NormalizeSoftwarePath

func NormalizeSoftwarePath(p string) string

NormalizeSoftwarePath canonicalizes team YAML software package paths so they match Fleet API's software.packages[].referenced_yaml_path format. Example: "../software/mac/slack/slack.yml" -> "software/mac/slack/slack.yml"

func ValidateLogging

func ValidateLogging(logging string) bool

ValidateLogging checks if a logging value is valid.

func ValidatePlatform

func ValidatePlatform(platform string) []string

ValidatePlatform checks if a platform string contains only valid identifiers.

Types

type ParseError

type ParseError struct {
	File    string
	Line    int
	Message string
}

ParseError represents a parse/validation error with file context.

func (ParseError) Error

func (e ParseError) Error() string

type ParsedAppStoreApp

type ParsedAppStoreApp struct {
	AppStoreID  string   `yaml:"app_store_id"`
	SelfService bool     `yaml:"self_service"`
	Categories  []string `yaml:"categories"`
}

ParsedAppStoreApp represents an App Store app.

type ParsedFleetApp

type ParsedFleetApp struct {
	Slug              string   `yaml:"slug"`
	SelfService       bool     `yaml:"self_service"`
	Categories        []string `yaml:"categories"`
	InstallScript     string   `yaml:"-"` // resolved file content
	UninstallScript   string   `yaml:"-"`
	PreInstallQuery   string   `yaml:"-"`
	PostInstallScript string   `yaml:"-"`
	SourceFiles       []string `yaml:"-"` // all referenced file paths (for changed-file filtering)
}

ParsedFleetApp represents a Fleet-maintained app.

type ParsedGlobal

type ParsedGlobal struct {
	OrgSettings  map[string]any // raw org_settings as nested map
	AgentOptions map[string]any // raw agent_options as nested map
	Controls     map[string]any // raw controls as nested map
	Policies     []ParsedPolicy
	Queries      []ParsedQuery
	SourceFile   string
}

ParsedGlobal holds global configuration parsed from default.yml.

type ParsedLabel

type ParsedLabel struct {
	Name                string `yaml:"name"`
	Description         string `yaml:"description"`
	Query               string `yaml:"query"`
	Platform            string `yaml:"platform"`
	LabelMembershipType string `yaml:"label_membership_type"`
	SourceFile          string `yaml:"-"`
}

ParsedLabel represents a label from YAML.

type ParsedPolicy

type ParsedPolicy struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Resolution  string `yaml:"resolution"`
	Query       string `yaml:"query"`
	Platform    string `yaml:"platform"`
	Critical    bool   `yaml:"critical"`
	// Type is "patch" for Fleet patch policies, whose query and platform
	// Fleet generates from the maintained-app catalog; empty otherwise.
	Type             string   `yaml:"type"`
	LabelsIncludeAny []string `yaml:"labels_include_any"`
	LabelsExcludeAny []string `yaml:"labels_exclude_any"`
	SourceFile       string   `yaml:"-"`
}

ParsedPolicy represents a policy from YAML.

type ParsedProfile

type ParsedProfile struct {
	Path       string `yaml:"path"`
	Name       string `yaml:"-"` // extracted from file content (PayloadDisplayName, etc.)
	Platform   string `yaml:"-"` // inferred from file extension
	Content    string `yaml:"-"` // raw file content, for content-level diffing
	SourceFile string `yaml:"-"`
	// Label scoping, copied from the profile reference in the team file.
	LabelsIncludeAll []string `yaml:"-"`
	LabelsIncludeAny []string `yaml:"-"`
	LabelsExcludeAny []string `yaml:"-"`
}

ParsedProfile represents an MDM profile reference.

type ParsedQuery

type ParsedQuery struct {
	Name       string `yaml:"name"`
	Query      string `yaml:"query"`
	Interval   uint   `yaml:"interval"`
	Platform   string `yaml:"platform"`
	Logging    string `yaml:"logging"`
	SourceFile string `yaml:"-"`
}

ParsedQuery represents a query from YAML.

type ParsedRepo

type ParsedRepo struct {
	Teams  []ParsedTeam
	Labels []ParsedLabel
	Global *ParsedGlobal // from default.yml (org_settings, agent_options, controls, policies, queries)
	Errors []ParseError
}

ParsedRepo represents the fully parsed fleet-gitops repository.

func ParseRepo

func ParseRepo(root string, teamFilters []string, defaultFile string) (*ParsedRepo, error)

ParseRepo parses the fleet-gitops repository at the given root directory. If teamFilters is non-empty, only matching teams are parsed. If defaultFile is non-empty, it is used as the path to default.yml (the pre-merged global config). Otherwise, the parser looks for default.yml in the repo root directory.

type ParsedScript

type ParsedScript struct {
	Name       string // filename extracted from path (e.g., "foo.ps1")
	Path       string // resolved absolute path
	Content    string // file content (read at parse time)
	SourceFile string // team YAML that referenced it
}

ParsedScript represents a script under controls.scripts.

type ParsedSoftware

type ParsedSoftware struct {
	Packages        []ParsedSoftwarePackage `yaml:"packages"`
	FleetMaintained []ParsedFleetApp        `yaml:"fleet_maintained_apps"`
	AppStoreApps    []ParsedAppStoreApp     `yaml:"app_store_apps"`
}

ParsedSoftware holds all software types for a team.

type ParsedSoftwarePackage

type ParsedSoftwarePackage struct {
	URL         string   `yaml:"url"`
	HashSHA256  string   `yaml:"hash_sha256"`
	SelfService bool     `yaml:"self_service"`
	Categories  []string `yaml:"categories"`
	SourceFile  string   `yaml:"-"`
	RefPath     string   `yaml:"-"`
	SourceFiles []string `yaml:"-"` // all referenced file paths (install/uninstall scripts, pre_install_query)
}

ParsedSoftwarePackage represents a custom software package.

type ParsedTeam

type ParsedTeam struct {
	Name string
	// Settings holds the team's `settings:` block (or the older
	// `team_settings:` spelling) as a nested map: webhook_settings,
	// host_expiry_settings, integrations, features. Diffed field by field
	// against the matching keys on the Fleet team object.
	Settings map[string]any
	// Controls holds the team's `controls:` block as a nested map. Scripts
	// and profiles are also resolved into Scripts and Profiles; the rest
	// (macos_updates, enable_disk_encryption, ...) is diffed as settings.
	Controls map[string]any
	// AgentOptions holds the team's `agent_options:`, with a `path:`
	// reference already replaced by the file it points to.
	AgentOptions map[string]any
	Policies     []ParsedPolicy
	Queries      []ParsedQuery
	Software     ParsedSoftware
	Profiles     []ParsedProfile
	Scripts      []ParsedScript
	SourceFile   string
}

ParsedTeam represents a single team's configuration.