Interface IHostingManager

Interface describing NEONKUBE hosting manager implementions for different environments..

Namespace: Neon.Kube.Hosting

Assembly: Neon.Kube.dll

Syntax

public interface IHostingManager

Remarks

IHostingManager implementations are used to provision the infrastructure required to deploy a NEONKUBE cluster to various environments including on-premise via XenServer or Hyper-V hypervisors or to public clouds like AWS, Azure, and Google. This infrastructure includes creating or initializing the servers as well as configuring networking in cloud environments.

This interface also defines the mechanism for deprovisioning a cluster.

Properties

CanManageRouter

Returns true if the hosting manage is capable of updating the upstream network router or load balancer. Cloud based managers will return true whereas on-premise managers will return false because we don't have the ability to manage physical routers yet.

Declaration

bool CanManageRouter { get; }

Property Value

Type	Description
bool

Capabilities

Returns flags describing any optional capabilities supported by the hosting manager.

Declaration

HostingCapabilities Capabilities { get; }

Property Value

Type	Description
HostingCapabilities

HostingEnvironment

Returns the hosting environment implemented by the manager.

Declaration

HostingEnvironment HostingEnvironment { get; }

Property Value

Type	Description
HostingEnvironment

MaxParallel

The maximum number of nodes that will execute provisioning steps in parallel. This defaults to 25 for on-premise hosting managers and 100 for the cloud. This may also be customized by specific IHostingManager implementations.

Declaration

int MaxParallel { get; set; }

Property Value

Type	Description
int

NodeMtu

Returns the MTU (Maximum Transmission Unit) to be configured for network interfaces on node machines created by the hosting manager. This may return 0 which indicates that the default MTU (typically DefaultMTU bytes) should be set or a custom value between [512-9000].

Declaration

int NodeMtu { get; }

Property Value

Type	Description
int

RequiresNodeAddressCheck

Returns true if the hosting manager requires that the LAN be scanned for devices assigned IP addresses that may conflict with node addresses. This is typically required only for clusters deployed on-premise because cloud clusters are typically provisioned to their own isolated network.

Declaration

bool RequiresNodeAddressCheck { get; }

Property Value

Type	Description
bool

WaitSeconds

Number of seconds to delay after specific operations (e.g. to allow services to stabilize). This defaults to 0.0.

Declaration

double WaitSeconds { get; set; }

Property Value

Type	Description
double

Methods

AddPostProvisioningSteps(SetupController<NodeDefinition>)

Adds any steps to be performed after the node has been otherwise prepared.

Declaration

void AddPostProvisioningSteps(SetupController<NodeDefinition> controller)

Parameters

Type	Name	Description
SetupController<NodeDefinition>	controller	The target setup controller.

AddPostSetupSteps(SetupController<NodeDefinition>)

Adds any stps to be performed after cluster setup.

Declaration

void AddPostSetupSteps(SetupController<NodeDefinition> controller)

Parameters

Type	Name	Description
SetupController<NodeDefinition>	controller	The target setup controller.

AddProvisioningSteps(SetupController<NodeDefinition>)

Adds the steps required to the setup controller passed that creates and initializes the cluster resources such as the virtual machines, networks, load balancers, network security groups, public IP addresses.

Declaration

void AddProvisioningSteps(SetupController<NodeDefinition> controller)

Parameters

Type	Name	Description
SetupController<NodeDefinition>	controller	The setup controller.

AddSetupSteps(SetupController<NodeDefinition>)

Adds any steps to be performed before starting cluster setup.

Declaration

void AddSetupSteps(SetupController<NodeDefinition> controller)

Parameters

Type	Name	Description
SetupController<NodeDefinition>	controller	The target setup controller.

CheckDeploymentReadinessAsync(ClusterDefinition)

Performs any final hosting environmet readiness check before deploying a cluster.

Declaration

Task CheckDeploymentReadinessAsync(ClusterDefinition clusterDefinition)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition	Specifies the cluster definition.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
HostingReadinessException	Thrown if any problems were detected.

CheckForConflictsAsync(ClusterDefinition)

Checks for any conflicts that might arise when provisoning a cluster. Currently, this checks for existing machines using IP addresses that will conflict with one or more of the cluster nodes.

Declaration

Task<string> CheckForConflictsAsync(ClusterDefinition clusterDefinition)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition	Specifies the cluster definition.

Returns

Type	Description
Task<string>	null when there are no conflicts, otherise a string detailing the conflicts.

DeleteClusterAsync(ClusterDefinition)

Deletes an existing cluster by terminating any nodes and then removing node VMs and any related resources as well as the related local cluster login by default. The cluster does not need to be running.

note

This operation may not be supported for all environments.

Declaration

Task DeleteClusterAsync(ClusterDefinition clusterDefinition = null)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition	Optionally specifies a cluster definition. This is used in situations where you need to remove a cluster without having its kubeconfig context. Use this with extreme care because in the mode, the cluster cannot be queried to determine whether it's locked or not and locked clusters will be deleted too.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
NotSupportedException	Thrown if the hosting environment doesn't support this operation.

DisableInternetSshAsync()

Disables public SSH access for every node in the cluster, honoring source address limitations specified by ManagementAddressRules in the cluster definition.

note

This currently supported only by cloud hosting managers like: Azure, AWS, and Google. This will do nothing for the on-premise hosting managers because we don't have the ability to manage physical routers yet.

Declaration

Task DisableInternetSshAsync()

Returns

Type	Description
Task

EnableInternetSshAsync()

Enables public SSH access for every node in the cluster, honoring source address limitations specified by ManagementAddressRules in the cluster definition.

Each node will be assigned a public port that has a NAT rule directing SSH traffic to that specific node. These ports will be in the range of FirstExternalSshPort to LastExternalSshPort. GetSshEndpoint(string) will return the external endpoint for nodes when external SSH is enabled.

note

This currently supported only by cloud hosting managers like: Azure, AWS, and Google. This will do nothing for the on-premise hosting managers because we don't have the ability to manage physical routers yet.

Declaration

Task EnableInternetSshAsync()

Returns

Type	Description
Task

GetClusterAddresses()

Returns the IP address to be used to access the cluster. For clusters deployed the the cloud, this will be the ingress IP address assigned to the load balancer. For on-premise clusters, this returns the private IP addresses for the control-plane nodes.

Declaration

IEnumerable<string> GetClusterAddresses()

Returns

Type	Description
IEnumerable<string>	The list of cluster IP addresses.

GetClusterHealthAsync(TimeSpan)

Retrieves the health status of the current cluster from the hosting manager's perspective This includes information about the infrastructure provisioned for the cluster.

Declaration

Task<ClusterHealth> GetClusterHealthAsync(TimeSpan timeout = default)

Parameters

Type	Name	Description
TimeSpan	timeout	Optionally specifies the maximum time to wait for the result. This defaults to 15 seconds.

Returns

Type	Description
Task<ClusterHealth>	The ClusterHealth information for the current cluster. note When there is no current cluster, the health information will return indicating that no cluster was found.

GetDataDisk(LinuxSshProxy)

Identifies the data disk device for a node. This returns the data disk's device name when an uninitialized data disk exists or "PRIMARY" when the OS disk will be used for data.

Declaration

string GetDataDisk(LinuxSshProxy node)

Parameters

Type	Name	Description
LinuxSshProxy	node

Returns

Type	Description
string	The disk device name or "PRIMARY".

Remarks

note

This will not work after the node's data disk has been initialized.

GetDatacenterCoordinatesAsync()

Returns the lat/long coordinates of the region or datacenter hosting the cluster when possible. The coordinates will be returned as null when this is unknown.

Declaration

Task<(double? Latitude, double? Longitude)> GetDatacenterCoordinatesAsync()

Returns

Type	Description
Task<(double? Latitude, double? Longitude)>	The datacenter coordinates or null values.

GetResourceAvailabilityAsync(long, long)

Returns the availability of resources required to deploy a cluster.

Declaration

Task<HostingResourceAvailability> GetResourceAvailabilityAsync(long reserveMemory = 0, long reservedDisk = 0)

Parameters

Type	Name	Description
long	reserveMemory	Optionally specifies the amount of host memory (in bytes) to be reserved for host operations.
long	reservedDisk	Optionally specifies the amount of host disk disk (in bytes) to be reserved for host operations.

Returns

Type	Description
Task<HostingResourceAvailability>	Details about whether cluster deployment can proceed.

Remarks

The optional reserveMemory and reservedDisk parameters can be used to specify memory and disk that are to be reserved for the host environment. Hosting manager implementations are free to ignore this when they don't really makse sense.

This is currently used for Hyper-V based clusters running on a user workstation or laptop to ensure that deployed clusters don't adverserly impact the host machine too badly.

These parameters don't really make sense for cloud or dedicated hypervisor hosting environments because those environemnts will still work well when all available resources are consumed.

GetSshEndpoint(string)

Returns the FQDN or IP address (as a string) and the port to use to establish a SSH connection to a specific node.

Declaration

(string Address, int Port) GetSshEndpoint(string nodeName)

Parameters

Type	Name	Description
string	nodeName	The target node's name.

Returns

Type	Description
(string Address, int Port)	A (string Address, int Port) tuple.

Remarks

This will return the direct private node endpoint by default. If EnableInternetSshAsync() has been called and is supported by the hosting manager, then this returns the public address of the cluster along with the public NAT port.

PauseClusterAsync()

Pauses a cluster if it's running, by putting all cluster nodes to sleep.

note

This operation may not be supported for all environments.

Declaration

Task PauseClusterAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
NotSupportedException	Thrown if the hosting environment doesn't support this operation.

ResumeClusterAsync()

Resumes a paused cluster, by waking all cluster nodes.

note

This operation may not be supported for all environments.

Declaration

Task ResumeClusterAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
NotSupportedException	Thrown if the hosting environment doesn't support this operation.

StartClusterAsync()

Starts a cluster if it's not already running.

note

This operation may not be supported for all environments.

Declaration

Task StartClusterAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
NotSupportedException	Thrown if the hosting environment doesn't support this operation.

StopClusterAsync(StopMode)

Shuts down a cluster if it's running.

note

This operation may not be supported for all environments.

Declaration

Task StopClusterAsync(StopMode stopMode = StopMode.Graceful)

Parameters

Type	Name	Description
StopMode	stopMode	Optionally specifies how the cluster nodes are stopped. This defaults to Graceful.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
NotSupportedException	Thrown if the hosting environment doesn't support this operation.

UpdateInternetRoutingAsync()

Updates the cluster's load balancer or router to use the current set of ingress rules defined by IngressRules and the egress rules defined by EgressAddressRules.

note

This currently supported only by cloud hosting managers like for Azure, AWS, and Google. This will do nothing for the on-premise hosting managers because we don't have the ability to manage physical routers yet.

Declaration

Task UpdateInternetRoutingAsync()

Returns

Type	Description
Task

Validate(ClusterDefinition)

Verifies that a cluster is valid for the hosting manager, customizing properties as required.

Declaration

void Validate(ClusterDefinition clusterDefinition)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if any problems were detected.