Documentation
¶
Overview ¶
Package fleetcontract assembles the one statement of what this fleet offers.
It exists because a consumer -- github-device-sync, which pins this repository as a submodule -- had no artifact to point at. Its pin has been frozen since 2d277bd, 108 commits back, waiting for "an immutable surface:5 handoff that defines the supported runner label, the admission and authorization contract, the rollout state, and the exact module commit with its acceptance evidence" (example-org/github-device-sync#172).
Almost all of it is derived. config/fleet-contract.yaml holds only what cannot be: which promises are contractual, which are not, and what is still open. The runner classes, the tenants, the artifact identities and the required merge context all come from the code and manifests that already state them, so the contract cannot disagree with the fleet it describes.
Index ¶
- Constants
- func ValidateConfig(contract Contract, platform platformconfig.Config) error
- type Artifacts
- type Blocker
- type Contract
- type Declaration
- type Execution
- type Guarantee
- type Lifecycle
- type Merge
- type Observability
- type ResourceSemantics
- type Resources
- type RunnerClass
- type Sources
- type TenantEntry
- type Warm
Constants ¶
const DefaultDeclarationPath = "config/fleet-contract.yaml"
DefaultDeclarationPath is the declared half, relative to the repository root.
Variables ¶
This section is empty.
Functions ¶
func ValidateConfig ¶
func ValidateConfig(contract Contract, platform platformconfig.Config) error
ValidateConfig proves that one deployment overlay implements this exact public contract without making private topology part of the public source.
Types ¶
type Artifacts ¶
type Artifacts struct {
GARMVersion string `json:"garm_version"`
GARMBinarySHA256 string `json:"garm_binary_sha256"`
ProviderVersion string `json:"provider_version"`
ProviderCommit string `json:"provider_commit"`
ProviderBinarySHA256 string `json:"provider_binary_sha256"`
ProviderInterface string `json:"provider_interface"`
IncusSDKVersion string `json:"incus_sdk_version"`
}
type Contract ¶
type Contract struct {
SchemaVersion int `json:"schema_version"`
ContractVersion int `json:"contract_version"`
Repository string `json:"repository"`
// Commit is the tree this contract describes. A consumer pins that commit;
// anything else would be a contract about a tree nobody named.
Commit string `json:"commit"`
RunnerClasses []RunnerClass `json:"runner_classes"`
Tenants []TenantEntry `json:"tenants"`
Artifacts Artifacts `json:"artifacts"`
Merge Merge `json:"merge"`
Execution Execution `json:"execution"`
ResourceSemantics ResourceSemantics `json:"resource_semantics"`
Lifecycle Lifecycle `json:"lifecycle"`
Observability Observability `json:"observability"`
Guarantees []Guarantee `json:"guarantees"`
NotContractual []string `json:"not_contractual"`
OpenBlockers []Blocker `json:"open_blockers"`
}
Contract is the assembled statement: the declaration plus everything derived.
type Declaration ¶
type Declaration struct {
SchemaVersion int `json:"schema_version" yaml:"schema_version"`
ContractVersion int `json:"contract_version" yaml:"contract_version"`
Execution Execution `json:"execution" yaml:"execution"`
ResourceSemantics ResourceSemantics `json:"resource_semantics" yaml:"resource_semantics"`
Lifecycle Lifecycle `json:"lifecycle" yaml:"lifecycle"`
Observability Observability `json:"observability" yaml:"observability"`
Guarantees []Guarantee `json:"guarantees" yaml:"guarantees"`
NotContractual []string `json:"not_contractual" yaml:"not_contractual"`
OpenBlockers []Blocker `json:"open_blockers" yaml:"open_blockers"`
}
Declaration is config/fleet-contract.yaml.
func LoadDeclaration ¶
func LoadDeclaration(path string) (Declaration, error)
func (Declaration) Validate ¶
func (d Declaration) Validate() error
type Execution ¶
type Execution struct {
WorkerKind string `json:"worker_kind" yaml:"worker_kind"`
Ephemeral bool `json:"ephemeral" yaml:"ephemeral"`
JobsPerWorker int `json:"jobs_per_worker" yaml:"jobs_per_worker"`
ExecutedWorkerDisposition string `json:"executed_worker_disposition" yaml:"executed_worker_disposition"`
WarmWorkerReuse string `json:"warm_worker_reuse" yaml:"warm_worker_reuse"`
}
type Lifecycle ¶
type Lifecycle struct {
States []string `json:"states" yaml:"states"`
PhaseSources map[string]string `json:"phase_sources" yaml:"phase_sources"`
AmbiguousAuthoritativeState string `json:"ambiguous_authoritative_state" yaml:"ambiguous_authoritative_state"`
CapacityRelease string `json:"capacity_release" yaml:"capacity_release"`
}
type Merge ¶
type Merge struct {
Branch string `json:"branch"`
RequiredContexts []string `json:"required_contexts"`
Strict bool `json:"strict"`
PullRequest bool `json:"pull_request_required"`
EnforceAdmins bool `json:"enforce_admins"`
}
Merge is what a commit on the default branch has been proven to satisfy. A consumer pinning a commit is relying on this, so it is part of the contract.
type Observability ¶
type Observability struct {
PhaseCounts bool `json:"phase_counts" yaml:"phase_counts"`
PhaseOldestAge bool `json:"phase_oldest_age" yaml:"phase_oldest_age"`
TransitionHistograms bool `json:"transition_histograms" yaml:"transition_histograms"`
BoundedCorrelationIdentity bool `json:"bounded_correlation_identity" yaml:"bounded_correlation_identity"`
ContainerAdmissionReadiness string `json:"container_admission_readiness" yaml:"container_admission_readiness"`
VMPilotReadiness string `json:"vm_pilot_readiness" yaml:"vm_pilot_readiness"`
}
type ResourceSemantics ¶
type ResourceSemantics struct {
MemoryCommitment string `json:"memory_commitment" yaml:"memory_commitment"`
HardMemoryExcludesEmergencySwap bool `json:"hard_memory_excludes_emergency_swap" yaml:"hard_memory_excludes_emergency_swap"`
EmergencySwapSchedulable bool `json:"emergency_swap_schedulable" yaml:"emergency_swap_schedulable"`
CPUMode string `json:"cpu_mode" yaml:"cpu_mode"`
CPUHardQuota bool `json:"cpu_hard_quota" yaml:"cpu_hard_quota"`
PressureSignals []string `json:"pressure_signals" yaml:"pressure_signals"`
AdmissionHysteresisRequired bool `json:"admission_hysteresis_required" yaml:"admission_hysteresis_required"`
}
type Resources ¶
type Resources struct {
// VCPU is the portable default. Deployments may tune CPU within the
// published envelope from real workload telemetry without changing the
// class's trust, capability, memory or storage contract.
VCPU int `json:"vcpu"`
VCPUMin int `json:"vcpu_min"`
VCPUMax int `json:"vcpu_max"`
MemoryMiB int `json:"memory_mib"`
DiskGiB int `json:"disk_gib"`
}
type RunnerClass ¶
type RunnerClass struct {
Label string `json:"label"`
Image string `json:"image"`
WorkerKind string `json:"worker_kind"`
Ephemeral bool `json:"ephemeral"`
JobsPerWorker int `json:"jobs_per_worker"`
Trust string `json:"trust"`
Credentials string `json:"credentials"`
NetworkPolicy string `json:"network_policy"`
CacheWriteScope string `json:"cache_write_scope"`
// Docker reports whether a job of this class can run containers and service
// containers. It is the one capability difference a consumer chooses on.
Docker bool `json:"docker"`
Resources Resources `json:"resources"`
Warm Warm `json:"warm"`
}
RunnerClass is one label a consumer may put in `runs-on`.
type Sources ¶
type Sources struct {
Root string
}
Sources are the paths Build reads, all relative to the repository root.