module

package
v0.0.0-...-ad34417 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const ModuleTypeAuthOnly = "authOnly"

ModuleTypeAuthOnly marks a module that only manages authentication for an already-existing, non-provisionable cluster (e.g. k3d, a pre-existing cloud cluster). Such modules typically have no create/delete/status — the reconciler treats an empty HYVE_CLUSTER_STATUS as ACTIVE for them rather than requiring a status op to say so explicitly.

Variables

This section is empty.

Functions

func CacheDir 

func CacheDir() (string, error)

func CachePath 

func CachePath(sha256 string) (string, error)

func DefaultKubeconfigPath 

func DefaultKubeconfigPath() (string, error)

DefaultKubeconfigPath returns the path kubectl uses when KUBECONFIG is unset.

func DownloadAndExtract 

func DownloadAndExtract(url, destDir, repo, ref, subdir string) error

func InitModuleSkeleton 

func InitModuleSkeleton(repoPath, name string, authOnly bool) (dir string, err error)

InitModuleSkeleton scaffolds a new module directory at repoPath/modules/<name>/ with a starter module.yaml and no-op operation scripts. When authOnly is true, it scaffolds only module.yaml (with metadata.type: authOnly) and auth.sh — appropriate for a module that only configures kubeconfig access to an already-existing, non-provisionable cluster (e.g. k3d) and has no create/delete/status/scale of its own.

func InstallModules 

func InstallModules(repoPath string, refs []ModuleRef) (locked []LockedModuleRef, alreadyLocked []ModuleRef, resolveErrors []string, err error)

InstallModules resolves and locks every module referenced by templates or cluster definitions that isn't already in hyve.lock. It returns the newly locked entries and the refs that were already locked (both empty if hyve.lock was already up to date and nothing needed resolving). The caller is responsible for committing the repo when len(locked) > 0.

refs is the deduplicated (source, version) list to consider — the caller gathers this from templates.Spec.Driver and clusterDefs.Spec.Driver, since that traversal already depends on internal/template and internal/state types this package does not import.

func IsCached 

func IsCached(sha256 string) bool

func IsLocalSource 

func IsLocalSource(source string) bool

IsLocalSource reports whether a module source string names a local path ("./...", "../...", or an absolute path) rather than a remote Git reference. "../" is recognized alongside "./" so a module can live in a sibling checkout outside the consuming repo (e.g. "../../hyve-some- module") without needing to be a remote Git source at all — useful when the module's real repo is private and reconcile always runs from a machine that already has it checked out locally.

func LockKey 

func LockKey(source, version string) string

func RemoveModule 

func RemoveModule(repoPath, source, version string) (removed bool, err error)

RemoveModule removes a locked source@version entry from hyve.lock. removed is false if no such entry existed (in which case hyve.lock is left untouched). The caller is responsible for committing the repo afterward.

func ResolveRef 

func ResolveRef(host, org, repo, version string) (string, error)

ResolveRef resolves a version string to a git ref. - "" or "latest": picks the highest semver tag; falls back to "HEAD" if no tags exist. - semver constraint (e.g. "~> 1.2", ">= 1.0"): picks the highest matching tag. - anything else: treated as an exact tag or commit ref.

func SaveLockFile 

func SaveLockFile(repoDir string, lf *LockFile) error

func StoreInCache 

func StoreInCache(sha256, srcDir string) error

func ValidateModule 

func ValidateModule(repoPath, source, version string) (validationErrors []string, err error)

ValidateModule resolves a locked (or local) module and checks it has the expected structure: a valid module.yaml, at least one operation file, and (if present) a structurally valid auth.yaml. err is non-nil only for infrastructure failures (can't load hyve.lock, can't resolve the module); structural problems are returned as validation error strings instead.

func ValidateToolRequirements 

func ValidateToolRequirements(tools []ToolRequirement) error

ValidateToolRequirements checks that every required tool is present on PATH. Deliberately does not enforce ToolRequirement.Version — no module.yaml in the wild sets it yet, and duplicating workflow.RequirementValidator's semver-ish comparison logic for an unused field isn't worth the complexity. Version/Description are still surfaced in the error message for context.

Types

type AuthMethod 

type AuthMethod struct {
	Name        string        `yaml:"name"`
	Description string        `yaml:"description,omitempty"`
	Deps        []string      `yaml:"deps,omitempty"`
	Auth        BootstrapSpec `yaml:"auth"`
	Exports     string        `yaml:"exports,omitempty"`
}

AuthMethod is a single named auth path within a ClusterAuth manifest.

type BootstrapSpec 

type BootstrapSpec struct {
	Script string `yaml:"script"`
}

type ClusterAuth 

type ClusterAuth struct {
	APIVersion string          `yaml:"apiVersion"`
	Kind       string          `yaml:"kind"`
	Metadata   ClusterAuthMeta `yaml:"metadata"`
	Spec       ClusterAuthSpec `yaml:"spec"`
}

ClusterAuth is parsed from auth.yaml (kind: ClusterAuth).

type ClusterAuthMeta 

type ClusterAuthMeta struct {
	Name string `yaml:"name"`
}

type ClusterAuthSpec 

type ClusterAuthSpec struct {
	// Legacy single-method fields (kept for backward compat)
	Bootstrap BootstrapSpec `yaml:"bootstrap"`
	Verify    *VerifySpec   `yaml:"verify,omitempty"`
	// Multi-method list — takes precedence over Bootstrap/Verify when present
	Methods []AuthMethod `yaml:"methods,omitempty"`
}

type EnvRequirement 

type EnvRequirement struct {
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Injected    bool   `yaml:"injected,omitempty" json:"injected,omitempty"`
}

type Executor 

type Executor struct {
	ModuleDir  string
	Env        []string // HYVE_* vars as "KEY=VALUE" strings
	WorkDir    string   // repo root
	AuthMethod string   // optional: name of auth method to use; empty means first
}

Executor runs module operations in host mode.

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, op OperationType) (*OperationResult, error)

Execute runs a named operation and returns captured outputs.

type LockFile 

type LockFile struct {
	Version   int                        `yaml:"version" json:"version"`
	Modules   map[string]*LockedModule   `yaml:"modules" json:"modules"`
	Workflows map[string]*LockedWorkflow `yaml:"workflows,omitempty" json:"workflows,omitempty"`
}

LockFile represents hyve.lock.

func LoadLockFile 

func LoadLockFile(repoDir string) (*LockFile, error)

func (*LockFile) FindLockedWorkflowsByName 

func (lf *LockFile) FindLockedWorkflowsByName(name string) []LockedWorkflowMatch

FindLockedWorkflowsByName returns every locked workflow entry whose declared Name matches. Used by `hyve workflow run <name>` after the local workflows/ directory lookup misses — multiple results mean the name is ambiguous and the caller must require the full source string.

func (*LockFile) GetLocked 

func (lf *LockFile) GetLocked(source, version string) *LockedModule

func (*LockFile) GetLockedWorkflow 

func (lf *LockFile) GetLockedWorkflow(source, version string) *LockedWorkflow

func (*LockFile) RemoveLocked 

func (lf *LockFile) RemoveLocked(source, version string)

func (*LockFile) RemoveLockedWorkflow 

func (lf *LockFile) RemoveLockedWorkflow(source, version string)

func (*LockFile) SetLocked 

func (lf *LockFile) SetLocked(source, version string, m *LockedModule)

func (*LockFile) SetLockedWorkflow 

func (lf *LockFile) SetLockedWorkflow(source, version string, w *LockedWorkflow)

type LockedModule 

type LockedModule struct {
	Source   string       `yaml:"source" json:"source"`
	Resolved string       `yaml:"resolved" json:"resolved"`
	SHA256   string       `yaml:"sha256" json:"sha256"`
	Runner   LockedRunner `yaml:"runner,omitempty" json:"runner,omitempty"`
}

func AddModule 

func AddModule(repoPath, source, version string) (lockVersion string, entry *LockedModule, alreadyLocked bool, err error)

AddModule resolves source@version and locks it into hyve.lock. If an entry for the resolved lock version is already present, it is left untouched and alreadyLocked is true. The caller is responsible for committing the repo (hyve.lock changed on disk when alreadyLocked is false and err is nil).

func UpdateModule 

func UpdateModule(repoPath, source, version string) (*LockedModule, error)

UpdateModule forces a re-resolve of an already-locked source@version pair, refreshing its SHA256 (and resolved URL) in hyve.lock. The caller is responsible for committing the repo afterward.

type LockedModuleRef 

type LockedModuleRef struct {
	ModuleRef
	Entry *LockedModule
}

LockedModuleRef pairs a ModuleRef with the LockedModule entry InstallModules resolved and locked for it.

type LockedRunner 

type LockedRunner struct {
	Image  string `yaml:"image,omitempty" json:"image,omitempty"`
	Digest string `yaml:"digest,omitempty" json:"digest,omitempty"`
}

type LockedWorkflow 

type LockedWorkflow struct {
	Name     string `yaml:"name" json:"name"`
	Source   string `yaml:"source" json:"source"`     // canonical "host/org/repo//path/file.yaml" — never a directory
	Resolved string `yaml:"resolved" json:"resolved"` // full download URL for this exact file at the pinned ref
	SHA256   string `yaml:"sha256" json:"sha256"`     // sha256 of this file's raw bytes only
}

LockedWorkflow is one resolved, content-hashed remote workflow file. Unlike LockedModule, it carries a Name — `hyve workflow run <name>` must be able to find a locked entry by bare name, which modules never need since a cluster's driver is always referenced by an explicit source+version.

type LockedWorkflowMatch 

type LockedWorkflowMatch struct {
	Source  string
	Version string
	Locked  *LockedWorkflow
}

LockedWorkflowMatch pairs a LockedWorkflow with the (source, version) pair needed to re-resolve it via workflowref.Resolve.

type ModuleManifest 

type ModuleManifest struct {
	APIVersion string         `yaml:"apiVersion" json:"apiVersion"`
	Kind       string         `yaml:"kind" json:"kind"`
	Metadata   ModuleMetadata `yaml:"metadata" json:"metadata"`
	Spec       ModuleSpec     `yaml:"spec" json:"spec"`
}

ModuleManifest is parsed from module.yaml inside a module directory.

func LoadManifestForSource 

func LoadManifestForSource(source, version, repoRoot string, lf *LockFile) (*ModuleManifest, error)

LoadManifestForSource resolves a module's directory and reads its module.yaml. For local paths the directory is read directly; for Git sources the cached directory (looked up via lf) is used. Returns nil without error when the module cannot be found locally (not yet installed).

func ModuleInfo 

func ModuleInfo(repoPath, source, version string) (manifest *ModuleManifest, resolvedDir string, err error)

ModuleInfo resolves a locked (or local) module and returns its parsed module.yaml manifest along with the resolved on-disk directory.

type ModuleMetadata 

type ModuleMetadata struct {
	Name        string   `yaml:"name" json:"name"`
	Version     string   `yaml:"version" json:"version"`
	Description string   `yaml:"description,omitempty" json:"description,omitempty"`
	Author      string   `yaml:"author,omitempty" json:"author,omitempty"`
	License     string   `yaml:"license,omitempty" json:"license,omitempty"`
	Tags        []string `yaml:"tags,omitempty" json:"tags,omitempty"`
	Type        string   `yaml:"type,omitempty" json:"type,omitempty"`
}

type ModuleRef 

type ModuleRef struct {
	Source  string
	Version string
}

ModuleRef identifies one module a template or cluster references — the input shape for InstallModules.

func GatherModuleRefs 

func GatherModuleRefs(stateMgr *state.Manager, repoPath string) ([]ModuleRef, error)

GatherModuleRefs collects the deduplicated (source, version) driver references from every template and cluster definition in the repo — the input InstallModules expects.

type ModuleRequirements 

type ModuleRequirements struct {
	Env   []EnvRequirement  `yaml:"env,omitempty" json:"env,omitempty"`
	Tools []ToolRequirement `yaml:"tools,omitempty" json:"tools,omitempty"`
}

type ModuleSpec 

type ModuleSpec struct {
	Runner         RunnerConfig       `yaml:"runner,omitempty" json:"runner,omitempty"`
	Params         []ParamSpec        `yaml:"params,omitempty" json:"params,omitempty"`
	Requirements   ModuleRequirements `yaml:"requirements,omitempty" json:"requirements,omitempty"`
	StatusCacheTTL string             `yaml:"statusCacheTTL,omitempty" json:"statusCacheTTL,omitempty"`
}

type OperationResult 

type OperationResult struct {
	Outputs  map[string]string
	ExitCode int
}

OperationResult holds HYVE_KEY=value outputs captured from an operation.

type OperationType 

type OperationType string

OperationType identifies which module operation to run. 

const (
	OperationCreate OperationType = "create"
	OperationDelete OperationType = "delete"
	OperationStatus OperationType = "status"
	OperationAuth   OperationType = "auth"
	OperationScale  OperationType = "scale"
)

type ParamSpec 

type ParamSpec struct {
	Name        string   `yaml:"name" json:"name"`
	Description string   `yaml:"description,omitempty" json:"description,omitempty"`
	Default     string   `yaml:"default,omitempty" json:"default,omitempty"`
	Required    bool     `yaml:"required,omitempty" json:"required,omitempty"`
	Choices     []string `yaml:"choices,omitempty" json:"choices,omitempty"`
}

type ResolvedModule 

type ResolvedModule struct {
	Dir      string
	SHA256   string
	Resolved string
	Runner   LockedRunner
	Version  string // canonical resolved version (e.g. "v1.2.3"); empty for local paths
}

ResolvedModule points to the local directory containing the module files.

func Resolve 

func Resolve(source, version string, locked *LockedModule, repoRoot string) (*ResolvedModule, error)

Resolve fetches and caches a module, returning its local directory. For local paths (starting with "./" or absolute): returns the dir directly, no caching. For Git sources: downloads, hashes, and caches under ~/.hyve/module-cache/{sha256}/.

type RunnerConfig 

type RunnerConfig struct {
	Image string `yaml:"image,omitempty" json:"image,omitempty"`
}

type ToolRequirement 

type ToolRequirement struct {
	Name        string `yaml:"name" json:"name"`
	Version     string `yaml:"version,omitempty" json:"version,omitempty"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
}

type VerifySpec 

type VerifySpec struct {
	Command string `yaml:"command"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.