condition

package
v2.0.0 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2024 License: Apache-2.0 Imports: 12 Imported by: 8

Documentation

Index

Constants

View Source 
const (
	// BiosControl identifies the Condition kind to configure the BIOS.
	BiosControl Kind = "biosControl"

	// ResetBiosConfig will reset the BIOS to default settings.
	ResetConfig BiosControlAction = "reset_config"

	// SetBiosConfig will set a new BIOS config
	SetConfig BiosControlAction = "set_config"
)
View Source 
const (
	Broker Kind = "broker"

	// These two Kinds are added just to enable the Condition API, Orchestrator to differentiate
	// between the two Kinds when applying an Update.
	//
	// https://github.com/metal-toolbox/conditionorc/blob/92f9b1619074b7c4ef4b35f39c3beab3c254966f/internal/store/nats.go#L263
	//
	BrokerAcquireServer Kind = "broker.acquireServer"
	BrokerReleaseServer Kind = "broker.releaseServer"

	// PurposeFirmwareInstall tells the target controller to take necessary steps
	// to ensure the server is reserved for a firmware install.
	PurposeFirmwareInstall BrokerActionPurpose = "firmwareInstall"

	// Acquire indicates the server is to be flagged into a state where its unavailable to other systems.
	AcquireServer BrokerAction = "acquireServer"
	// ReleaseServer indicates the server is to be reverted to its previous state.
	ReleaseServer BrokerAction = "releaseServer"
)
View Source 
const (
	// condition status considered stale after this period
	StatusStaleThreshold = StaleThreshold

	// controller considered dead after this period
	LivenessStaleThreshold = StaleThreshold
)
View Source 
const (
	// Condition kind
	Inventory Kind = "inventory"

	// Inventory methods
	InbandInventory    InventoryMethod = "inband"
	OutofbandInventory InventoryMethod = "outofband"
)
View Source 
const (
	// ServerControl identifies the Condition kind to power on/off/cycle servers and set the next boot device.
	ServerControl Kind = "serverControl"

	// SetPowerState sets the server power state
	//
	// Accepted ActionParameter value, one of:
	// - on
	// - off
	// - cycle
	// - reset
	// - soft
	SetPowerState ServerControlAction = "set_power_state"

	// GetPowerState retrieves the current power state on the server.
	GetPowerState ServerControlAction = "get_power_state"

	// SetNextBootDevice sets the next boot device
	//
	// Required: false
	//
	// Accepted ActionParameter value, one of:
	// - bios
	// - cdrom
	// - diag
	// - floppy
	// - disk
	// - none
	// - pxe
	// - remote_drive
	// - sd_card
	// - usb
	// - utilities
	SetNextBootDevice ServerControlAction = "set_next_boot_device"

	// Set PXE boot persistent and power on/cycle the server
	PxeBootPersistent ServerControlAction = "pxe_boot_persistent"

	// PowerCycleBMC power cycles the BMC
	PowerCycleBMC ServerControlAction = "power_cycle_bmc"

	// Run a basic firmware test
	ValidateFirmware ServerControlAction = "validate_firmware"
)
View Source 
const (
	TaskVersion1 = "1.0"
	// Task KV bucket name
	TaskKVRepositoryBucket = "tasks"
)
View Source 
const (
	ServerResourceType    string = "servers"
	ConditionResourceType string = "condition"

	ConditionCreateEvent events.EventType = "create"
	ConditionUpdateEvent events.EventType = "update"

	// ConditionStructVersion identifies the condition struct revision
	ConditionStructVersion string = "1.1"

	// StaleConditionThreshold is the period after which the Condition Orchestrator will reconcile the Condition.
	StaleThreshold = 2 * time.Hour
)
View Source 
const (
	// VirtualMediaMount condition kind uploads, mounts a virtual media disk image/iso.
	VirtualMediaMount Kind = "virtualMediaMount"

	MediaTypeFloppy VirtualMediaType = "floppy"
	MediaTypeISO    VirtualMediaType = "iso"

	// MountMethodUpload identifies the means of mounting the virtual media by uploading it onto the BMC.
	MountMethodUpload VirtualMediaMountMethod = "upload"

	// MountMethodUpload identifies the means of mounting the virtual media by linking the BMC to the given URL.
	MountMethodURL VirtualMediaMountMethod = "url"
)
View Source 
const (
	StatusValueVersion int32 = 1
)

Variables

View Source 
var (
	ErrInvalidStatusRecord = errors.New("invalid status record")
)

Functions

func MustDefaultInventoryJSON 

func MustDefaultInventoryJSON(assetID uuid.UUID) []byte

func MustInventoryJSON 

func MustInventoryJSON(assetID uuid.UUID, method InventoryMethod, collectFirmwareStatus, collectBiosCfg bool) []byte

func StateIsComplete 

func StateIsComplete(s State) bool

StateComplete returns true when the given state is considered to be final.

func StateIsValid 

func StateIsValid(s State) bool

StateValid validates the State.

func StatusValueKVKey 

func StatusValueKVKey(facilityCode, conditionID string) string

KV Key for the Condition Status Values

func StreamSubject 

func StreamSubject(facilityCode string, conditionKind Kind) string

Returns the stream subject with which the condition is to be published.

func TaskKVRepositoryKey 

func TaskKVRepositoryKey(facilityCode string, conditionKind Kind, serverID string) string

Types

type BiosControlAction 

type BiosControlAction string

type BiosControlTaskParameters 

type BiosControlTaskParameters struct {
	// Identifier for the Asset in the Asset store.
	//
	// Required: true
	AssetID uuid.UUID `json:"asset_id"`

	// The bios control action to be performed
	//
	// Required: true
	Action BiosControlAction `json:"action"`

	// The URL for the bios configuration settings file.
	// Needed for BiosControlAction.SetConfig
	//
	// Required: false
	BiosConfigURL *url.URL `json:"bios_config_url,omitempty"`
}

BiosControlTaskParameters are the parameters that are passed for the BiosControl condition.

func NewBiosControlParametersFromCondition 

func NewBiosControlParametersFromCondition(condition *Condition) (*BiosControlTaskParameters, error)

func NewBiosControlTaskParameters 

func NewBiosControlTaskParameters(assetID uuid.UUID, action BiosControlAction, configURL *url.URL) *BiosControlTaskParameters

func (*BiosControlTaskParameters) Marshal 

func (p *BiosControlTaskParameters) Marshal() (json.RawMessage, error)

func (*BiosControlTaskParameters) MustJSON 

func (p *BiosControlTaskParameters) MustJSON() []byte

func (*BiosControlTaskParameters) Unmarshal 

func (p *BiosControlTaskParameters) Unmarshal(r json.RawMessage) error

type BrokerAction 

type BrokerAction string

BrokerAction identifies the kind of boot image action to be taken.

type BrokerActionPurpose 

type BrokerActionPurpose string

BrokerActionPurpose hints the controller as to the reason for the action.

type BrokerTaskParameters 

type BrokerTaskParameters struct {
	AssetID       uuid.UUID           `json:"asset_id"`
	Action        BrokerAction        `json:"action"`
	Purpose       BrokerActionPurpose `json:"action_purpose"`
	ServerAcquire *ServerAcquire      `json:"acquire,omitempty"`
	ServerRelease *ServerRelease      `json:"release,omitempty"`
}

func NewBrokerTaskParameters 

func NewBrokerTaskParameters(assetID uuid.UUID, action BrokerAction, purpose BrokerActionPurpose, info string) *BrokerTaskParameters

func (*BrokerTaskParameters) MapStringInterfaceToStruct 

func (p *BrokerTaskParameters) MapStringInterfaceToStruct(m map[string]interface{}) error

func (*BrokerTaskParameters) Marshal 

func (p *BrokerTaskParameters) Marshal() (json.RawMessage, error)

func (*BrokerTaskParameters) MustMarshal 

func (p *BrokerTaskParameters) MustMarshal() json.RawMessage

func (*BrokerTaskParameters) Unmarshal 

func (p *BrokerTaskParameters) Unmarshal(r json.RawMessage) error

type Condition 

type Condition struct {
	// Version identifies the revision number for this struct.
	Version string `json:"version"`

	// Client is the user/jwt user that requested the condition.
	Client string `json:"client"`

	// TraceID enables tracking a Condition and any associated Conditions
	TraceID string `json:"traceID"`

	// SpanID enables tracking a Condition and any associated Conditions
	SpanID string `json:"spanID"`

	// ID is the identifier for this condition.
	ID uuid.UUID `json:"id"`

	// Target is the identifier for the target server this Condition is applicable for.
	Target uuid.UUID `json:"target"`

	// Kind is one of Kind.
	Kind Kind `json:"kind,omitempty"`

	// Parameters is a JSON object that is agreed upon by the controller
	// reconciling the condition and the client requesting the condition.
	Parameters json.RawMessage `json:"parameters,omitempty"`

	// State is one of State
	State State `json:"state,omitempty"`

	// Status is a JSON object that is agreed upon by the controller
	// reconciling the condition and the client requesting the condition.
	Status json.RawMessage `json:"status,omitempty"`

	// Should the worker executing this condition fail if its unable to checkpoint
	// the status of work on this condition.
	FailOnCheckpointError bool `json:"failOnCheckpointError,omitempty"`

	// Fault is used to introduce faults into the controller when executing on a condition.
	Fault *Fault `json:"fault,omitempty"`

	// UpdatedAt is when this object was last updated.
	UpdatedAt time.Time `json:"updatedAt,omitempty"`

	// CreatedAt is when this object was created.
	CreatedAt time.Time `json:"createdAt,omitempty"`
}

Condition defines model for Condition.

nolint:govet // fieldalignment struct is easier to read in the current format

func (*Condition) IsComplete 

func (c *Condition) IsComplete() bool

IsComplete returns true if the condition has a state that is final.

func (*Condition) MustBytes 

func (c *Condition) MustBytes() []byte

MustBytes returns an encoded json representation of the condition or panics

func (*Condition) StateValid 

func (c *Condition) StateValid() bool

StateValid validates the Condition State field.

func (*Condition) StreamPublishRequired 

func (c *Condition) StreamPublishRequired() bool

Returns bool for when a Condition should be published to the Jetstream.

func (*Condition) StreamPublishSubject 

func (c *Condition) StreamPublishSubject(facilityCode string) string

type Definition 

type Definition struct {
	Kind                  Kind `mapstructure:"kind"`
	FailOnCheckpointError bool `mapstructure:"failOnCheckpointError"`
}

Definition holds the default parameters for a Condition.

type Definitions 

type Definitions []*Definition

Definitions is the list of conditions with helper methods.

func (Definitions) FindByKind 

func (c Definitions) FindByKind(k Kind) *Definition

type ErrQueryStatus 

type ErrQueryStatus struct {
	// contains filtered or unexported fields
}

func (*ErrQueryStatus) Error 

func (e *ErrQueryStatus) Error() string

type Fault 

type Fault struct {
	//  will cause the condition execution to panic on the controller.
	Panic bool `json:"panic"`

	// Introduce specified delay in execution of the condition on the controller.
	//
	// accepts the string format of time.Duration - 5s, 5m, 5h
	DelayDuration string `json:"delayDuration,omitempty"`

	// FailAt is a controller specific task/stage that the condition should fail in execution.
	//
	// for example, in the flasher controller, setting this field to `init` will cause the
	// condition task to fail at initialization.
	FailAt string `json:"failAt,omitempty"`
}

Fault is used to introduce faults into the controller when executing on a condition.

Note: this depends on controllers implementing support to honor the given fault.

nolint:govet // fieldalignment struct is easier to read in the current format

type Firmware 

type Firmware struct {
	ID            string   `yaml:"id" json:"id"`
	Vendor        string   `yaml:"vendor" json:"vendor"`
	FileName      string   `yaml:"filename" json:"filename"`
	Version       string   `yaml:"version" json:"version"`
	URL           string   `yaml:"URL" json:"URL"`
	Component     string   `yaml:"component" json:"component"`
	Checksum      string   `yaml:"checksum" json:"checksum"`
	Models        []string `yaml:"models" json:"models"`
	InstallInband bool     `yaml:"install_inband" json:"install_inband"`
	Oem           bool     `yaml:"oem" json:"oem"`
}

Firmware holds attributes for a firmware object

type FirmwareInstallTaskParameters 

type FirmwareInstallTaskParameters struct {
	// Inventory identifier for the asset to install firmware on.
	AssetID uuid.UUID `json:"asset_id"`

	// Reset device BMC before firmware install
	ResetBMCBeforeInstall bool `json:"reset_bmc_before_install,omitempty"`

	// Force install given firmware regardless of current firmware version.
	ForceInstall bool `json:"force_install,omitempty"`

	// When defined, flasher will not perform any disruptive actions on the asset,
	// it will download the firmware to be installed and determine if the firmware is applicable for the device.
	//
	// No firmware installs will be attempted and if the device is powered off, it will not be powered on.
	DryRun bool `json:"dry_run,omitempty"`

	// When true, flasher will expect the host to be powered off before proceeding,
	// if the host is not already powered off - the install task will be failed.
	RequireHostPoweredOff bool `json:"require_host_powered_off,omitempty"`

	// Firmwares is the list of firmwares to be installed.
	Firmwares []Firmware `json:"firmwares,omitempty"`

	// FirmwareSetID specifies the firmware set to be applied.
	FirmwareSetID uuid.UUID `json:"firmware_set_id,omitempty"`
}

FirmwareTaskParameters are the parameters set for a firmwareInstall condition

nolint:govet // fieldalignment struct is easier to read in the current format

func (*FirmwareInstallTaskParameters) MapStringInterfaceToStruct 

func (p *FirmwareInstallTaskParameters) MapStringInterfaceToStruct(m map[string]interface{}) error

func (*FirmwareInstallTaskParameters) Marshal 

func (p *FirmwareInstallTaskParameters) Marshal() (json.RawMessage, error)

func (*FirmwareInstallTaskParameters) MustJSON 

func (p *FirmwareInstallTaskParameters) MustJSON() []byte

func (*FirmwareInstallTaskParameters) Unmarshal 

func (p *FirmwareInstallTaskParameters) Unmarshal(r json.RawMessage) error

type InventoryMethod 

type InventoryMethod string

type InventoryTaskParameters 

type InventoryTaskParameters struct {
	// CollectBiosCfg defaults to true
	CollectBiosCfg bool `json:"collect_bios_cfg"`

	// CollectFirmwareStatus defaults to true
	CollectFirwmareStatus bool `json:"collect_firmware_status"`

	// Method defaults to Outofband
	Method InventoryMethod `json:"inventory_method"`

	// Asset identifier.
	AssetID uuid.UUID `json:"asset_id"`
}

InventoryTaskParameters are the parameters set for an inventory collection condition

nolint:govet // prefer readability over fieldalignment for this case

func NewInventoryTaskParameters 

func NewInventoryTaskParameters(assetID uuid.UUID, method InventoryMethod, collectFirmwareStatus, collectBiosCfg bool) *InventoryTaskParameters

type Kind 

type Kind string

Kind holds the value for the Condition Kind field. 

const (
	FirmwareInstall       Kind = "firmwareInstall"
	FirmwareInstallInband Kind = "firmwareInstallInband"
)

type Parameters 

type Parameters interface {
	Validate() error
}

Parameters is an interface for Condition Parameter types

type ServerAcquire 

type ServerAcquire struct {
	Info                 string `json:"info"`
	CustomIpxe           bool   `json:"custom_ipxe"`
	PersistentCustomIpxe bool   `json:"persistent_custom_ipxe"`
}

type ServerConditions 

type ServerConditions struct {
	Conditions []*Condition
	ServerID   uuid.UUID
}

ServerConditions is a type to hold a server ID and the conditions associated with it.

type ServerControlAction 

type ServerControlAction string

type ServerControlTaskParameters 

type ServerControlTaskParameters struct {
	// Identifier for the Asset in the Asset store.
	//
	// Required: true
	AssetID uuid.UUID `json:"asset_id"`

	// The server control action to be performed
	//
	// Required: true
	Action ServerControlAction `json:"action"`

	// Action parameter to the ServerControlAction
	//
	// Required for SetPowerState, SetNextBootDevice actions
	ActionParameter string `json:"action_parameter"`

	// Persist next boot device
	// For use with SetNextBootDevice action.
	// Required: false
	SetNextBootDevicePersistent bool `json:"set_next_boot_device_persistent"`

	// Set next boot device to be UEFI
	// For use with SetNextBootDevice action.
	// Required: false
	SetNextBootDeviceEFI bool `json:"set_next_boot_device_efi"`

	// The timeout for a ValidateFirmware action
	// Required for ValidateFirmware.
	ValidateFirmwareTimeout time.Duration `json:"validate_firmware_timeout"`

	// The firmware set identifier for the validate firmware action
	// Required for ValidateFirmware
	ValidateFirmwareID uuid.UUID `json:"validate_firmware_id"`
}

ServerControlTaskParameters are the parameters that are passed for the ServerControl condition. nolint:govet // prefer readability over fieldalignment for this case

func NewServerControlTaskParameters 

func NewServerControlTaskParameters(assetID uuid.UUID, action ServerControlAction, controlParam string, bootDevicePersistent, efiBoot bool) *ServerControlTaskParameters

func (*ServerControlTaskParameters) Marshal 

func (p *ServerControlTaskParameters) Marshal() (json.RawMessage, error)

func (*ServerControlTaskParameters) MustJSON 

func (p *ServerControlTaskParameters) MustJSON() []byte

func (*ServerControlTaskParameters) Unmarshal 

func (p *ServerControlTaskParameters) Unmarshal(r json.RawMessage) error

type ServerRelease 

type ServerRelease struct {
	Info string `json:"info"`
}

type State 

type State string

State is the state value of a Condition 

const (
	Pending   State = "pending"
	Active    State = "active"
	Failed    State = "failed"
	Succeeded State = "succeeded"
)

Defines holds the value for the Condition State field.

func States 

func States() []State

States returns available condition states.

func (State) TransitionValid 

func (current State) TransitionValid(next State) bool

Transition valid returns a bool value if the state transition is allowed.

type StatusMsg 

type StatusMsg struct {
	Timestamp time.Time `json:"ts,omitempty"`
	Msg       string    `json:"msg,omitempty"`
}

StatusMsg is a single record within the StatusRecord

type StatusRecord 

type StatusRecord struct {
	StatusMsgs []StatusMsg `json:"records"`
}

StatusRecord holds status information for a Condition

func NewTaskStatusRecord 

func NewTaskStatusRecord(s string) StatusRecord

func StatusRecordFromMessage 

func StatusRecordFromMessage(m json.RawMessage) (*StatusRecord, error)

func (*StatusRecord) Append 

func (sr *StatusRecord) Append(s string)

func (*StatusRecord) Last 

func (sr *StatusRecord) Last() string

func (*StatusRecord) Marshal 

func (sr *StatusRecord) Marshal() (json.RawMessage, error)

func (*StatusRecord) MustMarshal 

func (sr *StatusRecord) MustMarshal() json.RawMessage

func (*StatusRecord) Update 

func (sr *StatusRecord) Update(currentMsg, newMsg string)

type StatusValue 

type StatusValue struct {
	CreatedAt  time.Time       `json:"created"`
	UpdatedAt  time.Time       `json:"updated"`
	WorkerID   string          `json:"worker"`
	Target     string          `json:"target"`
	TraceID    string          `json:"traceID"`
	SpanID     string          `json:"spanID"`
	State      string          `json:"state"`
	Status     json.RawMessage `json:"status"`
	MsgVersion int32           `json:"msgVersion"`
}

StatusValue is the canonical structure for reporting status of an ongoing task

func UnmarshalStatusValue 

func UnmarshalStatusValue(b []byte) (*StatusValue, error)

func (*StatusValue) MustBytes 

func (v *StatusValue) MustBytes() []byte

MustBytes sets the version field of the StatusValue so any callers don't have to deal with it. It will panic if we cannot serialize to JSON for some reason.

type Task 

type Task[P, D any] struct {
	// StructVersion indicates the Task object version and is used to determine Task  compatibility.
	StructVersion string `json:"task_version"`

	// Task unique identifier, this is set to the Condition identifier.
	ID uuid.UUID `json:"id"`

	// Kind is the type of Condition this Task is derived from
	Kind Kind `json:"kind"`

	// state is the state of the install
	State State `json:"state"`

	// status holds informational data on the state
	Status StatusRecord `json:"status"`

	// Data holds Condition Task specific data
	Data D `json:"data,omitempty"`

	// Parameters holds Condition specific parameters for this task
	Parameters P `json:"parameters,omitempty"`

	// Fault is a field to inject failures into a flasher task execution,
	// this is set from the Condition only when the worker is run with fault-injection enabled.
	Fault *Fault `json:"fault,omitempty"`

	// FacilityCode identifies the facility this task is to be executed in.
	FacilityCode string `json:"facility_code"`

	// Server holds attributes about target server this task is for.
	Server *rtypes.Server `json:"server,omitempty"`

	// WorkerID is the identifier for the worker executing this task.
	WorkerID string `json:"worker_id,omitempty"`

	TraceID string `json:"traceID"`
	SpanID  string `json:"spanID"`

	CreatedAt   time.Time `json:"created_at,omitempty"`
	UpdatedAt   time.Time `json:"updated_at,omitempty"`
	CompletedAt time.Time `json:"completed_at,omitempty"`
}

func NewTaskFromCondition 

func NewTaskFromCondition(cond *Condition) *Task[any, any]

func TaskFromMessage 

func TaskFromMessage(msg json.RawMessage) (*Task[any, any], error)

TaskFromMessage converts a Task json.RawMessage object into its Task equivalent

func (*Task[P, D]) Marshal 

func (t *Task[P, D]) Marshal() (json.RawMessage, error)

func (*Task[P, D]) SetState 

func (t *Task[P, D]) SetState(state State)

SetState implements the Task runner interface

func (*Task[P, D]) Update 

func (t *Task[P, D]) Update(update *Task[P, D]) error

Update validates and applies the given changes to the Task object

nolint:gocyclo // field validation is cyclomatic

type TaskState 

type TaskState int

TaskState holds the value for the task state in the KV.

note: this differs from the condition.State, can these be merged? 

const (
	NotStarted    TaskState = iota
	InProgress              // another worker has started it, is still around and updated recently
	Complete                // task is done
	Orphaned                // the worker that started this task doesn't exist anymore
	Indeterminate           // we got an error in the process of making the check
)

func CheckConditionInProgress 

func CheckConditionInProgress(conditionID, facilityCode, kvBucket string, js nats.JetStreamContext) (TaskState, error)

CheckConditionInProgress returns the status of the task from the KV store

type VirtualMediaMountMethod 

type VirtualMediaMountMethod string

type VirtualMediaTaskParameters 

type VirtualMediaTaskParameters struct {
	// MountMethod specifies the means of obtaining the image to be mounted
	//
	// Required: true
	MountMethod VirtualMediaMountMethod `json:"mount_method"`

	// ImageURL is a URL accessible to the Disko controller and the BMC to download the image.
	//
	// Required: true
	ImageURL string `json:"image_uri"`

	// MediaType indicates the kind of media being uploaded/mounted
	//
	// Required: true
	MediaType VirtualMediaType `json:"media_type"`

	// Identifier for the Asset in the Asset store.
	//
	// Required: true
	AssetID uuid.UUID `json:"asset_id"`
}

VirtualMediaTaskParameters are the parameters set for a VirtualMedia condition.

nolint:govet // prefer readability over fieldalignment for this case

func NewVirtualMediaTaskParameters 

func NewVirtualMediaTaskParameters(assetID uuid.UUID, imageURL string, mediaType VirtualMediaType, mountMethod VirtualMediaMountMethod) *VirtualMediaTaskParameters

type VirtualMediaType 

type VirtualMediaType string

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.