Class SetupController<NodeMetadata>

Manages a cluster setup operation consisting of a series of setup steps while displaying status to the Console.

Inheritance

object

Dictionary<string, object>

ObjectDictionary

SetupController<NodeMetadata>

Implements

ISetupController

IObjectDictionary

Inherited Members

ObjectDictionary.Get<TValue>(string)

ObjectDictionary.Get<TValue>(string, TValue)

ObjectDictionary.TryGetValue<TValue>(string, out TValue)

Namespace: Neon.Kube.Setup

Assembly: Neon.Kube.dll

Syntax

public class SetupController<NodeMetadata> : ObjectDictionary, ISetupController, IObjectDictionary where NodeMetadata : class

Type Parameters

Name	Description
NodeMetadata	Specifies the node metadata type.

Remarks

This class inherits from ObjectDictionary which can be used to maintain state that can be accessed by the setup step actions. This dictionary is keyed by case-sensitive strings and can store and retrieve objects with differing types.

Constructors

SetupController(string, IEnumerable<NodeSshProxy<NodeMetadata>>, string, bool)

Constructor.

Declaration

public SetupController(string operationTitle, IEnumerable<NodeSshProxy<NodeMetadata>> nodes, string logFolder, bool disableConsoleOutput = false)

Parameters

Type	Name	Description
string	operationTitle	Summarizes the high-level operation being performed.
IEnumerable<NodeSshProxy<NodeMetadata>>	nodes	The node proxies for the cluster nodes being manipulated.
string	logFolder	Specifies the path to the log folder.
bool	disableConsoleOutput	Optionally disables status output to the console. This is typically enabled for non-console applications.

SetupController(string[], IEnumerable<NodeSshProxy<NodeMetadata>>, string, bool)

Constructor.

Declaration

public SetupController(string[] operationTitle, IEnumerable<NodeSshProxy<NodeMetadata>> nodes, string logFolder, bool disableConsoleOutput = false)

Parameters

Type	Name	Description
string[]	operationTitle	Summarizes the high-level operation being performed.
IEnumerable<NodeSshProxy<NodeMetadata>>	nodes	The node proxies for the cluster nodes being manipulated.
string	logFolder	Specifies the path to the log folder.
bool	disableConsoleOutput	Optionally disables status output to the console. This is typically enabled for non-console applications.

Properties

CancellationToken

Returns the CancellationToken that will be signalled when setup is cancelled.

Declaration

public CancellationToken CancellationToken { get; }

Property Value

Type	Description
CancellationToken

ConsoleWriter

Returns the console updater used internally to write the setup status to the Console without flickering. This will be null for non-console applications.

Declaration

public SetupConsoleWriter ConsoleWriter { get; }

Property Value

Type	Description
SetupConsoleWriter

CurrentStepNumber

Returns the current step number or -1 for quiet steps or when setup hasn't started yet.

Declaration

public int CurrentStepNumber { get; }

Property Value

Type	Description
int

DisablePendingTasks

This controls whether AddPendingTaskAsync(string, Task, string, string, INodeSshProxy) actually holds pending tasks to be awaited by a future step (the default) or whether the AddPendingTaskAsync(string, Task, string, string, INodeSshProxy) awaits the task itself. This is useful for debugging because executing a bunch of tasks in parallel is likely to mess with the node and global logs since those are not really structured to handle parallel operations at this time.

Declaration

public bool DisablePendingTasks { get; set; }

Property Value

Type	Description
bool

GlobalStatus

Returns any status for the overall setup operation.

Declaration

public string GlobalStatus { get; }

Property Value

Type	Description
string

HasNodeSteps

Returns true if the controller has an nodes with setup steps.

Declaration

public bool HasNodeSteps { get; }

Property Value

Type	Description
bool

IsCancelPending

Indicates that setup as been cancelled due to a previous call to Cancel().

Declaration

public bool IsCancelPending { get; }

Property Value

Type	Description
bool

IsFaulted

Indicates whether cluster setup is faulted due to a global problem or when any node is faulted.

Declaration

public bool IsFaulted { get; }

Property Value

Type	Description
bool

LastProgressError

Returns the last error message logged by LogProgressError(string).

Declaration

public string LastProgressError { get; }

Property Value

Type	Description
string

LogBeginMarker

Optionally specifies the line written as the first line of log files.

Declaration

public string LogBeginMarker { get; set; }

Property Value

Type	Description
string

LogEndMarker

Optionally specifies the line written as the last line of log files when the operation succeeded.

Declaration

public string LogEndMarker { get; set; }

Property Value

Type	Description
string

LogFailedMarker

Optionally specifies the line written as the last line of log files when the operation failed.

Declaration

public string LogFailedMarker { get; set; }

Property Value

Type	Description
string

MaxDisplayedSteps

Specifies the maximum number of setup steps to be displayed. This defaults to 5. You can set 0 to allow an unlimited number of steps may be displayed.

Declaration

public int MaxDisplayedSteps { get; set; }

Property Value

Type	Description
int

MaxParallel

The maximum number of nodes that will execute setup steps in parallel. This defaults to effectively unconstrained.

Declaration

public int MaxParallel { get; set; }

Property Value

Type	Description
int

NodeMetadataType

Returns the SetupController<NodeMetadata>'s node metadata type.

Declaration

public Type NodeMetadataType { get; }

Property Value

Type	Description
Type

OperationTitle

Specifies the operation title.

Declaration

public string OperationTitle { get; }

Property Value

Type	Description
string

ShowNodeStatus

Specifies whether that node status will be displayed. This defaults to true.

Declaration

public bool ShowNodeStatus { get; set; }

Property Value

Type	Description
bool

ShowRuntime

Optionally displays the elapsed time for each step as well as the overall operation when setup completes (or fails).

Declaration

public bool ShowRuntime { get; set; }

Property Value

Type	Description
bool

ShowStatus

Specifies whether the class should print setup status to the console. This defaults to false.

Declaration

public bool ShowStatus { get; set; }

Property Value

Type	Description
bool

StepCount

Returns the number of setup steps.

Declaration

public int StepCount { get; }

Property Value

Type	Description
int

Methods

AddCheckForIpConflcits(string)

Adds a global step that scans for existing machines that conflict with any of the IP addressess assigned to the cluster. This is used by some hosting managers to ensure that we're not conficting with and exising cluster or other assets deployed on the LAN.

Declaration

public object AddCheckForIpConflcits(string stepLabel = "scan for IP address conflicts")

Parameters

Type	Name	Description
string	stepLabel	Optionally specifies the step label.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

AddControllerStep<ServerMetadata>(SetupController<ServerMetadata>)

Adds the steps from a subcontroller to the current controller.

Declaration

public void AddControllerStep<ServerMetadata>(SetupController<ServerMetadata> subController) where ServerMetadata : class

Parameters

Type	Name	Description
SetupController<ServerMetadata>	subController	The subcontroller.

Type Parameters

Name	Description
ServerMetadata	Specifies the type of the subcontroller's node metadata.

Remarks

This is useful for situations where an operation requires interactions with machines that are not cluster nodes. Currently, we're using this for connecting to XenServers to provision cluster nodes there before moving on to preparing the cluster nodes and configuring the cluster.

note

This method copies the state from this controller (the parent) to the subcontroller before executing the first subcontroller step.

note

Subcontroller steps may only be added to the parent level. You may not nest these any deeper than that.

AddDelayStep(string, TimeSpan, string, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>, bool, int)

Adds a synchronous global step that waits for a specified period of time.

Declaration

public object AddDelayStep(string stepLabel, TimeSpan delay, string status = null, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool> nodePredicate = null, bool quiet = false, int position = -1)

Parameters

Type	Name	Description
string	stepLabel	Specifies the step label.
TimeSpan	delay	The amount of time to wait.
string	status	The optional node status.
Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>	nodePredicate	Optional predicate used to select the nodes that participate in the step or null to select all nodes.
bool	quiet	Optionally specifies that the step is not to be reported in the progress.
int	position	The optional zero-based index of the position where the step is to be inserted into the step list.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

AddDisposable(IDisposable)

Adds an IDisposable instance to the controller so that they can be properly disposed when RunAsync(int) exits.

Declaration

public void AddDisposable(IDisposable disposable)

Parameters

Type	Name	Description
IDisposable	disposable	The disposable instance.

AddGlobalStep(string, Action<ISetupController>, bool, ISetupController, int)

Adds a synchronous global configuration step.

Declaration

public object AddGlobalStep(string stepLabel, Action<ISetupController> action, bool quiet = false, ISetupController subController = null, int position = -1)

Parameters

Type	Name	Description
string	stepLabel	Specifies the step label.
Action<ISetupController>	action	The synchronous global action to be performed.
bool	quiet	Optionally specifies that the step is not to be reported in the progress.
ISetupController	subController	Optionally specifies the related subcontroller.
int	position	The optional zero-based index of the position where the step is to be inserted into the step list.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

AddGlobalStep(string, Func<ISetupController, Task>, bool, ISetupController, int)

Adds an asynchronous global configuration step.

Declaration

public object AddGlobalStep(string stepLabel, Func<ISetupController, Task> action, bool quiet = false, ISetupController subController = null, int position = -1)

Parameters

Type	Name	Description
string	stepLabel	Specifies the step label.
Func<ISetupController, Task>	action	The asynchronous global action to be performed.
bool	quiet	Optionally specifies that the step is not to be reported in the progress.
ISetupController	subController	Optionally specifies the related subcontroller.
int	position	The optional zero-based index of the position where the step is to be inserted into the step list.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

AddNodeStep(string, Action<ISetupController, NodeSshProxy<NodeMetadata>>, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>, bool, bool, int, int)

Appends a synchronous node configuration step.

Declaration

public object AddNodeStep(string stepLabel, Action<ISetupController, NodeSshProxy<NodeMetadata>> nodeAction, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool> nodePredicate = null, bool quiet = false, bool noParallelLimit = false, int position = -1, int parallelLimit = 0)

Parameters

Type	Name	Description
string	stepLabel	Specifies the step label.
Action<ISetupController, NodeSshProxy<NodeMetadata>>	nodeAction	The action to be performed on each node. Two parameters will be passed to this action: the node's NodeSshProxy<TMetadata> and a TimeSpan indicating the amount of time the action should wait before performing the operation, if the operation hasn't already been performed.
Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>	nodePredicate	Optional predicate used to select the nodes that participate in the step or null to select all nodes.
bool	quiet	Optionally specifies that the step is not to be reported in the progress.
bool	noParallelLimit	Optionally ignores the global MaxParallel limit for the new step when greater.
int	position	Optionally specifies the zero-based index of the position where the step is to be inserted into the step list.
int	parallelLimit	Optionally specifies the maximum number of operations to be performed in parallel for this step, overriding the controller default.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

Exceptions

Type	Condition
InvalidOperationException	Thrown when RunAsync(int) has been called to start execution.

AddNodeStep(string, Func<ISetupController, NodeSshProxy<NodeMetadata>, Task>, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>, bool, bool, int, int)

Appends an asynchronous node configuration step.

Declaration

public object AddNodeStep(string stepLabel, Func<ISetupController, NodeSshProxy<NodeMetadata>, Task> nodeAction, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool> nodePredicate = null, bool quiet = false, bool noParallelLimit = false, int position = -1, int parallelLimit = 0)

Parameters

Type	Name	Description
string	stepLabel	Specifies the step label.
Func<ISetupController, NodeSshProxy<NodeMetadata>, Task>	nodeAction	The action to be performed on each node. Two parameters will be passed to this action: the node's NodeSshProxy<TMetadata> and a TimeSpan indicating the amount of time the action should wait before performing the operation, if the operation hasn't already been performed.
Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>	nodePredicate	Optional predicate used to select the nodes that participate in the step or null to select all nodes.
bool	quiet	Optionally specifies that the step is not to be reported in the progress.
bool	noParallelLimit	Optionally ignores the global MaxParallel limit for the new step when greater.
int	position	Optionally specifies the zero-based index of the position where the step is to be inserted into the step list.
int	parallelLimit	Optionally specifies the maximum number of operations to be performed in parallel for this step, overriding the controller default.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

AddPendingTaskAsync(string, Task, string, string, INodeSshProxy)

Adds a pending task to a group of related tasks, creating the group when necessary. This is used as an aid to parallelizing setup operations to improve cluster setup times.

note

If DisablePendingTasks is true, then this method will await the task immediately, creating any empty group if necessary. This is useful for debugging because executing a bunch of tasks in parallel is likely to mess with the node and global logs since those are not really structured to handle parallel operations at this time.

Declaration

public Task AddPendingTaskAsync(string groupName, Task task, string verb, string message, INodeSshProxy node = null)

Parameters

Type	Name	Description
string	groupName	The task group name.
Task	task	The pending task.
string	verb	The progress verb.
string	message	The progress message.
INodeSshProxy	node	Optionally specifies the node where the operation is happening. The operation will be considered to be cluster global when this is null.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
InvalidOperationException	Thrown if WaitForPendingTasksAsync(string) has already been called for this group.

AddWaitUntilOnlineStep(string, string, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>, bool, TimeSpan?, int)

Adds a synchronous global step that waits for all nodes to be online.

Declaration

public object AddWaitUntilOnlineStep(string stepLabel = "connect", string status = null, Func<ISetupController, NodeSshProxy<NodeMetadata>, bool> nodePredicate = null, bool quiet = false, TimeSpan? timeout = null, int position = -1)

Parameters

Type	Name	Description
string	stepLabel	Optionally specifies the step label.
string	status	The optional node status.
Func<ISetupController, NodeSshProxy<NodeMetadata>, bool>	nodePredicate	Optional predicate used to select the nodes that participate in the step or null to select all nodes.
bool	quiet	Optionally specifies that the step is not to be reported in the progress.
TimeSpan?	timeout	Optionally specifies the maximum time to wait (defaults to 10 minutes).
int	position	The optional zero-based index of the position where the step is to be inserted into the step list.

Returns

Type	Description
object	INTERNAL USE ONLY: The new internal step as an object.

Cancel()

Attempts to cancel the setup operation. This will cause IsCancelPending to return true and calls to ThrowIfCancelled() to throw a OperationCanceledException.

Declaration

public void Cancel()

ClearStatus()

Clears any global status and the status for all cluster nodes. This should generally be called after completing a setup operation so that outdated status strings won't linger for setup steps that do a lot of work.

Declaration

public void ClearStatus()

GetHostLogs()

Returns setup related log information for any host proxies.

Declaration

public IEnumerable<NodeLog> GetHostLogs()

Returns

Type	Description
IEnumerable<NodeLog>	An the NodeLog values.

GetHostStatus()

Returns the status for any VM host machines being managed by executing subcontroller steps.

Declaration

public IEnumerable<SetupNodeStatus> GetHostStatus()

Returns

Type	Description
IEnumerable<SetupNodeStatus>	The status information for any host nodes.

GetNodeLogs()

Returns setup related log information for each of the nodes.

Declaration

public IEnumerable<NodeLog> GetNodeLogs()

Returns

Type	Description
IEnumerable<NodeLog>	An the NodeLog values.

GetNodeStatus()

Returns the status for any nodes being managed by the controller.

Declaration

public IEnumerable<SetupNodeStatus> GetNodeStatus()

Returns

Type	Description
IEnumerable<SetupNodeStatus>	The status information for any nodes.

GetPendingGroups()

Returns the names of any pending task groups that have not been awaited via WaitForPendingTasksAsync(string). This can be used by setup implementations to verify that all pending tasks have completed.

Declaration

public List<string> GetPendingGroups()

Returns

Type	Description
List<string>	The list of pending task group names.

GetStepNodeNames(object)

Returns a HashSet<T> with the names of the cluster nodes participating in the internal node step passed. This step is available as InternalStep.

Declaration

public HashSet<string> GetStepNodeNames(object internalStep)

Parameters

Type	Name	Description
object	internalStep	The internal node step.

Returns

Type	Description
HashSet<string>	The set of names affected by the setup sstep.

GetStepStatus()

Returns the status for all of the setup steps in order of execution.

Declaration

public IEnumerable<SetupStepStatus> GetStepStatus()

Returns

Type	Description
IEnumerable<SetupStepStatus>	The step status items.

LogGlobal(string)

Writes a line to the global cluster log file. This is used to log information that pertains to a global operation rather than a specific node.

note

This does not raise the ProgressEvent.

Declaration

public void LogGlobal(string message = null)

Parameters

Type	Name	Description
string	message	Optionally specifies the message to be logged.

LogGlobalError(string)

Writes an error line to the global cluster log file. This is used to log errors that pertain to a global operation rather than a specific node.

note

This does not raise the ProgressEvent.

Declaration

public void LogGlobalError(string message = null)

Parameters

Type	Name	Description
string	message	Optionally specifies the message to be logged.

LogGlobalException(Exception)

Writes information about an exception to the global cluster log file.

note

This does not raise the ProgressEvent.

Declaration

public void LogGlobalException(Exception e)

Parameters

Type	Name	Description
Exception	e	The exception.

LogProgress(ILinuxSshProxy, string)

Logs a progress message for a specific node. This sets the status text for the node.

Declaration

public void LogProgress(ILinuxSshProxy node, string message)

Parameters

Type	Name	Description
ILinuxSshProxy	node	Identifies the node
string	message	The message.

LogProgress(ILinuxSshProxy, string, string)

Logs a progress for a specific node with a verb and message.
This will be formatted like VERB MESSAGE.

Declaration

public void LogProgress(ILinuxSshProxy node, string verb, string message)

Parameters

Type	Name	Description
ILinuxSshProxy	node	Identifies the node
string	verb	The message verb.
string	message	The message.

LogProgress(string)

Logs a progress message.

Declaration

public void LogProgress(string message)

Parameters

Type	Name	Description
string	message	The message.

LogProgress(string, string)

Logs a progress message with a verb. This will be formatted like VERB: MESSAGE.

Declaration

public void LogProgress(string verb, string message)

Parameters

Type	Name	Description
string	verb	The message verb.
string	message	The message.

LogProgressError(ILinuxSshProxy, string)

Logs an error message for a specific node.

note

Setup will terminate after any step that reports an error via this method.

Declaration

public void LogProgressError(ILinuxSshProxy node, string message)

Parameters

Type	Name	Description
ILinuxSshProxy	node	Identifies the node
string	message	The message.

LogProgressError(string)

Logs an error message.

note

Setup will terminate after any step that reports an error via this method.

Declaration

public void LogProgressError(string message)

Parameters

Type	Name	Description
string	message	The message.

RunAsync(int)

Performs the setup operation steps in the in the order they were added to the controller.

Declaration

public Task<SetupDisposition> RunAsync(int maxStackSize = 256000)

Parameters

Type	Name	Description
int	maxStackSize	Optionally specifies the maximum stack size, in bytes, to be used by the threads created by this method, or 0 to use the default maximum stack size specified in the header for the executable. Important for partially trusted code, maxStackSize is ignored if it is greater than the default stack size. No exception is thrown in this case. This defaults to 250 KiB to reduce the memory footprint when deploying large clusters.

Returns

Type	Description
Task<SetupDisposition>	The final disposition of the setup run.

SetDefaultRunOptions(RunOptions)

Sets the DefaultRunOptions property for all nodes managed by the controller.

Declaration

public void SetDefaultRunOptions(RunOptions options)

Parameters

Type	Name	Description
RunOptions	options	The options to be set.

SetGlobalStepStatus(string)

Sets the operation status text.

Declaration

public void SetGlobalStepStatus(string status = null)

Parameters

Type	Name	Description
string	status	The optional operation status text.

SetHosts(IEnumerable<INodeSshProxy>)

Optionally called by hosting managers to associate any virtual machine host proxies that are participating in the setup operation with the controller. These are used to write fault details to the global cluster log after the operation completes.

note

This must be called before the controller starts.

Declaration

public void SetHosts(IEnumerable<INodeSshProxy> hosts)

Parameters

Type	Name	Description
IEnumerable<INodeSshProxy>	hosts	The hosts being assoicated.

ThrowIfCancelled()

Throws a OperationCanceledException when Cancel() has been called.

Declaration

public void ThrowIfCancelled()

ThrowOnError()

Throws an exception if any of the operation steps did not complete successfully.

Declaration

public void ThrowOnError()

WaitForPendingTasksAsync(string)

Waits for the pending tasks in a group to complete.

Declaration

public Task WaitForPendingTasksAsync(string groupName)

Parameters

Type	Name	Description
string	groupName	The task group name.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
InvalidOperationException	Thrown if WaitForPendingTasksAsync(string) has already been called for this group.
KeyNotFoundException	Thrown when there's no group named groupName.

Events

Finished

Optional event which is raised when the setup operation completes. The sender argument will be passed as the ISetupController instance and the Exception argument will be null when the setup operation completed successfully or an exception detailing the failure.

This presents a good opportunity for setup controller users to capture additional information about failed operations, etc. in common code.

note

Setup controller implementions are not required to set this.

Declaration

public event EventHandler<Exception> Finished

Event Type

Type	Description
EventHandler<Exception>

ProgressEvent

Raised when individual progress/error messages are logged during base image setup where where only limited status needs to be displayed or logged.

note

This event is not raised during normal cluster prepare or setup because the node image will have already gone through the base preparation. This will be raised though when setting up using debug mode.

note

This event will be raised on the same thread that logged the progress, typically the thread executing the step and that you MUST NOT modify any event parameters.

Declaration

public event SetupProgressDelegate ProgressEvent

Event Type

Type	Description
SetupProgressDelegate

StatusChangedEvent

Raised periodically when the overall status changes during cluster setup.

note

This event will be raised on a background thread and that you MUST NOT modify any event parameters.

Declaration

public event SetupStatusChangedDelegate StatusChangedEvent

Event Type

Type	Description
SetupStatusChangedDelegate

StepStarted

Raised when the next setup step is started.

Declaration

public event EventHandler<SetupStepDetails> StepStarted

Event Type

Type	Description
EventHandler<SetupStepDetails>

Implements

ISetupController

IObjectDictionary