Interface ISetupController

Describes some common methods exposed by all SetupController<NodeMetadata> implementations.

Inherited Members

IObjectDictionary.Get<TValue>(string)

IObjectDictionary.Get<TValue>(string, TValue)

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

Namespace: Neon.Kube.Setup

Assembly: Neon.Kube.dll

Syntax

public interface ISetupController : IObjectDictionary

Properties

CancellationToken

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

Declaration

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

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

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

bool DisablePendingTasks { get; set; }

Property Value

Type	Description
bool

GlobalStatus

Returns any status for the overall setup operation.

Declaration

string GlobalStatus { get; }

Property Value

Type	Description
string

HasNodeSteps

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

Declaration

bool HasNodeSteps { get; }

Property Value

Type	Description
bool

IsCancelPending

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

Declaration

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

bool IsFaulted { get; }

Property Value

Type	Description
bool

LastProgressError

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

Declaration

string LastProgressError { get; }

Property Value

Type	Description
string

LogBeginMarker

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

Declaration

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

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

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

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

int MaxParallel { get; set; }

Property Value

Type	Description
int

NodeMetadataType

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

Declaration

Type NodeMetadataType { get; }

Property Value

Type	Description
Type

OperationTitle

Specifies the operation title.

Declaration

string OperationTitle { get; }

Property Value

Type	Description
string

ShowNodeStatus

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

Declaration

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

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

bool ShowStatus { get; set; }

Property Value

Type	Description
bool

StepCount

Returns the number of setup steps.

Declaration

int StepCount { get; }

Property Value

Type	Description
int

Methods

AddDisposable(IDisposable)

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

Declaration

void AddDisposable(IDisposable disposable)

Parameters

Type	Name	Description
IDisposable	disposable	The disposable instance.

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

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.

Cancel()

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

Declaration

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

void ClearStatus()

GetHostLogs()

Returns setup related log information for any host proxies.

Declaration

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

SetGlobalStepStatus(string)

Sets the operation status text.

Declaration

void SetGlobalStepStatus(string status = null)

Parameters

Type	Name	Description
string	status	The optional operation status text.

ThrowIfCancelled()

Throws a OperationCanceledException when Cancel() has been called.

Declaration

void ThrowIfCancelled()

WaitForPendingTasksAsync(string)

Waits for the pending tasks in a group to complete.

Declaration

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

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

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

event SetupStatusChangedDelegate StatusChangedEvent

Event Type

Type	Description
SetupStatusChangedDelegate

StepStarted

Raised when the next setup step is started.

Declaration

event EventHandler<SetupStepDetails> StepStarted

Event Type

Type	Description
EventHandler<SetupStepDetails>