Class HostingManager

Base class for environment specific hosting managers.

Inheritance

object

HostingManager

AwsHostingManager

AzureHostingManager

BareMetalHostingManager

GoogleHostingManager

HyperVHostingManager

XenServerHostingManager

Implements

IHostingManager

Namespace: Neon.Kube.Hosting

Assembly: Neon.Kube.dll

Syntax

public abstract class HostingManager : IHostingManager

Fields

DefaultStatusTimeout

The default timeout for GetClusterHealthAsync(TimeSpan) implementations.

Declaration

protected readonly TimeSpan DefaultStatusTimeout

Field Value

Type	Description
TimeSpan

MaxAsyncParallelHostingOperations

Maximum number of async operations that hosting managers should perform in parallel.

Declaration

protected const int MaxAsyncParallelHostingOperations = 25

Field Value

Type	Description
int

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

public virtual bool CanManageRouter { get; }

Property Value

Type	Description
bool

Capabilities

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

Declaration

public abstract HostingCapabilities Capabilities { get; }

Property Value

Type	Description
HostingCapabilities

HostingEnvironment

Returns the hosting environment implemented by the manager.

Declaration

public abstract 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

public virtual 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

public virtual 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

public virtual 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

public 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

public virtual 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

public virtual void AddPostSetupSteps(SetupController<NodeDefinition> controllerd)

Parameters

Type	Name	Description
SetupController<NodeDefinition>	controllerd

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

public abstract 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

public virtual void AddSetupSteps(SetupController<NodeDefinition> controller)

Parameters

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

AssignNodeAddresses(ClusterDefinition)

Used by cloud and potentially other hosting manager implementations to verify the node address assignments and/or to automatically assign these addresses.

Declaration

protected void AssignNodeAddresses(ClusterDefinition clusterDefinition)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition	The cluster definition.

Remarks

note

This method verifies that node addresses for on-premise environments are located within the premise subnet. The method will not attempt to assign node addresses for on-premise node and requires all nodes have explicit addresses.

CheckDeploymentReadinessAsync(ClusterDefinition)

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

Declaration

public abstract 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

public virtual 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.

CheckForIPConflictsAsync(ClusterDefinition)

Used by on-premise hosting managers to detect IP address related conflicts.

Declaration

protected Task<string> CheckForIPConflictsAsync(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

public virtual 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

public virtual Task DisableInternetSshAsync()

Returns

Type	Description
Task

Dispose()

Releases any important resources associated with the instance.

Declaration

public void Dispose()

Dispose(bool)

Releases any important resources associated with the instance.

Declaration

public abstract void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Pass true if the instance is being disposed as opposed to being finalized.

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

public virtual Task EnableInternetSshAsync()

Returns

Type	Description
Task

~HostingManager()

Finalizer.

Declaration

protected ~HostingManager()

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

public abstract 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

public abstract 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

public abstract 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

public virtual 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

public abstract Task<HostingResourceAvailability> GetResourceAvailabilityAsync(long reserveMemory = 0, long reserveDisk = 0)

Parameters

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

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

public abstract (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.

Load(Action)

HACK: Used by derived HostingManager implementations to defeat C# code optimization to prevent trimming.

Declaration

protected static void Load(Action action)

Parameters

Type	Name	Description
Action	action	Specifies an action that ensures that trimming doesn't happen.

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

public virtual 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

public virtual 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

public virtual 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

public virtual 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.

SupportsFsTrim(HostingEnvironment)

Determines whether the hosting environment supports fstrim.

Declaration

public static bool SupportsFsTrim(HostingEnvironment environment)

Parameters

Type	Name	Description
HostingEnvironment	environment	Specifies the hosting environment.

Returns

Type	Description
bool	true if fstrim is supported.

SupportsFsZero(HostingEnvironment)

Determines whether the hosting environment supports zeroing block devices.

Declaration

public static bool SupportsFsZero(HostingEnvironment environment)

Parameters

Type	Name	Description
HostingEnvironment	environment	Specifies the hosting environment.

Returns

Type	Description
bool	true if fstrim is supported.

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

public virtual Task UpdateInternetRoutingAsync()

Returns

Type	Description
Task

Validate(ClusterDefinition)

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

Declaration

public abstract void Validate(ClusterDefinition clusterDefinition)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if any problems were detected.

ValidateCluster(ClusterDefinition, List<HostedNodeInfo>, HostingReadiness)

Performs final cluster definition validation including ensuring that the vCPUs and memory assigned to each node is supported, adding any details to the HostingReadiness instance passed.

Declaration

protected void ValidateCluster(ClusterDefinition clusterDefinition, List<HostedNodeInfo> hostedNodes, HostingReadiness readiness)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition	Specifies the cluster definition.
List<HostedNodeInfo>	hostedNodes	Specifies information about each cluster node including the number of vCPUs and memory (derived from the instance type/size for cloud environments).
HostingReadiness	readiness	Used to return discovered readiness problems.

Remarks

NEONKUBE clusters supports control-plane nodes with 2+ cores and at least 8GB RAM. All worker nodes must have at least 4 cores and at least 8GiB RAM. Clusters that have control-plane nodes with only 2 cores are required to have at least 1 worker node.

note

For cloud environments, we don't charge an extra hourly fee for 2-core VMs hosting control-plane nodes to be more competitive with cloud integrated Kubernetes offerings like AKS/EKS where the control-plane is entirely free. We need to ensure users can't workaround our fees by deploying 2-core worker nodes.

Implements

IHostingManager