Fixes around wording

Signed-off-by: Jacob Weinstock <[email protected]>

api/v1alpha2/hardware.go

@@ -6,8 +6,9 @@ import (
 )
 
 type HardwareSpec struct {
-	// NetworkInterfaces defines the desired DHCP and netboot configuration for a network interface.
+	// NetworkInterfaces defines the desired IPAM and netboot configuration for a network interface.
 	// +kubebuilder:validation:MinPoperties=1
+	// +listType=map
 	NetworkInterfaces NetworkInterfaces `json:"networkInterfaces,omitempty"`
 
 	// OSIE describes the Operating System Installation Environment (OSIE) to be used when booting.
@@ -43,7 +44,7 @@ type OSIE struct {
 	// +optional
 	KernelParams []string `json:"kernelParams,omitempty"`
 
-	// ISOURL is the URL of the ISO that will be used for the installation environment.A spec.BmcRef must be provided.
+	// ISOURL is the URL of the ISO that will be used for the installation environment. A spec.BmcRef must be specified and exist.
 	// +kubebuilder:validation:Format=url
 	// +optional
 	ISOURL string `json:"isoUrl,omitempty"`

api/v1alpha2/pipeline.go

@@ -74,14 +74,15 @@ const (
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:categories=tinkerbell,shortName=pl
-// +kubebuilder:printcolumn:name="Hardware",type="string",JSONPath=".status.currentHardware",description="Hardware that is currently that corresponds to the current Agent and Workflow"
+// +kubebuilder:printcolumn:name="Hardware",type="string",JSONPath=".status.currentHardware",description="Hardware that corresponds to the current Agent and Workflow"
 // +kubebuilder:printcolumn:name="Workflow",type="string",JSONPath=".status.CurrentWorkflow",description="Workflow that is currently be run by the associated Agent"
 // +kubebuilder:printcolumn:name="AgentID",type="string",JSONPath=".status.CurrentAgent",description="ID of the Agent that is running the current Workflow"
 // +kubebuilder:printcolumn:name="State",type="string",JSONPath=".status.state",description="Overall state of the Pipeline such as Pending,Running etc"
-// +kubebuilder:printcolumn:name="Action",type="string",JSONPath=".status.currentAction",description="Action that currently being executed"
+// +kubebuilder:printcolumn:name="Action",type="string",JSONPath=".status.currentAction",description="Action that is currently being executed"
 
-// Pipeline describes a set of actions to be run on a specific Hardware. Workflows execute
-// once and should be considered ephemeral.
+// Pipeline describes a set of Workflows to be run by corresponding Agents. Workflows in the Pipeline are execute sequentially. Each Workflow executes until it succeeds or fails.
+// A failed Worfklow will stop the Pipeline from executing further Workflows.
+// The Pipeline is considered successful if all Workflows succeed. The Pipeline is considered failed if any Workflow fails.
 type Pipeline struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -170,8 +171,8 @@ type PipelineStatus struct {
 	// CurrentAgent is the agent that is currently being used.
 	CurrentAgent string `json:"currentAgent,omitempty"`
 
-	// BootOptions holds the state of any boot options.
-	BootOptions BootOptionsStatus `json:"bootOptions,omitempty"`
+	// BootOptions holds the state of any boot options. TODO(jacobweinstock): this should probably map to each workflow.
+	BootOptions map[string]BootOptionsStatus `json:"bootOptions,omitempty"`
 
 	// WorkflowRendering indicates whether the Workflow was rendered successfully.
 	// Possible values are "succeeded" or "failed" or "unknown".

api/v1alpha2/workflow.go

@@ -17,7 +17,7 @@ type WorkflowSpec struct {
 	Volumes []Volume `json:"volumes,omitempty"`
 
 	// Env defines environment variables to be available in all Actions. If an Action specifies
-	// the same environment variable it will take precedence.
+	// the same environment variable, the Action's environment variable will take precedence.
 	// +optional
 	Env map[string]string `json:"env,omitempty"`
 
@@ -36,12 +36,11 @@ type Action struct {
 	Image string `json:"image"`
 
 	// Cmd defines the command to use when launching the image. It overrides the default command
-	// of the Action. It must be a unix path to an executable program.
+	// defined in the Image.
 	// +optional
 	Cmd *string `json:"cmd,omitempty"`
 
-	// Args are a set of arguments to be passed to the command executed by the container on
-	// launch.
+	// Args are a set of arguments to be passed to the command executed by the container on launch.
 	// +optional
 	Args []string `json:"args,omitempty"`
 
@@ -63,11 +62,11 @@ type Action struct {
 	// +kubebuilder:validation:Minimum=0
 	TimeoutSeconds *int64 `json:"timeout,omitempty"`
 
-	// Background true will run the container in background. The Agent will immediately report the Action as succeeded.
+	// Background true will run the container in the background or as some runtimes call it detached mode. When set to true, the Agent will immediately report the Action as having succeeded.
 	// +optional
 	Background *bool `json:"background,omitempty"`
 
-	// Retries defines the number of times to retry the Action if it fails. Retries are only attempted on non-zero exit codes.
+	// Retries defines the number of times the Agent will retry the Action if it fails, not including Timeouts. Retries are only attempted on non-zero exit codes.
 	// +optional
 	Retries *int32 `json:"retries,omitempty"`
 }
@@ -101,19 +100,19 @@ type Namespace struct {
 
 // Logging defines
 type Logging struct {
-	// Driver is the logging driver to use for the container.
+	// Driver is the logging driver to use for Action containers.
 	Driver string `json:"driver,omitempty"`
 
-	// Options are the logging options to use for the container.
+	// Options are the logging options to use for Action containers.
 	Options map[string]string `json:"options,omitempty"`
 }
 
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:categories=tinkerbell,shortName=bp
 
-// Workflow defines a set of Actions to be run on a target machine. The Workflow is rendered
+// Workflow defines a set of Actions to be run by an Agent. The Workflow is rendered
 // prior to execution where it is exposed to Hardware and user defined data. Most fields within the
-// WorkflowSpec may contain templates values excluding .Workflow.Spec.Actions[].Name.
+// WorkflowSpec may contain template values excluding .Workflow.Spec.Actions[].Name.
 // See https://pkg.go.dev/text/template for more details.
 type Workflow struct {
 	metav1.TypeMeta   `json:",inline"`