Class ClusterProxy

Used to manage a NEONKUBE cluster.

Inheritance

object

ClusterProxy

Namespace: Neon.Kube.Proxy

Assembly: Neon.Kube.dll

Syntax

public class ClusterProxy

Properties

Capabilities

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

Declaration

public HostingCapabilities Capabilities { get; }

Property Value

Type	Description
HostingCapabilities

ControlNodes

Enumerates the cluster control-plane node proxies sorted in ascending order by name.

Declaration

public IEnumerable<NodeSshProxy<NodeDefinition>> ControlNodes { get; }

Property Value

Type	Description
IEnumerable<NodeSshProxy<NodeDefinition>>

DeploymentControlNode

Returns the first cluster control-plane node as sorted by name.

note

This property works only for cluster proxies constructed for cluster setup from a KubeSetupState. Use GetReachableControlNode(ReachableHostMode) for other scenarios.

Declaration

public NodeSshProxy<NodeDefinition> DeploymentControlNode { get; }

Property Value

Type	Description
NodeSshProxy<NodeDefinition>

Exceptions

Type	Condition
InvalidOperationException	Thrown when the cluster proxy is not configured to deplpy a cluster.

Domain

Returns the cluster domain.

Declaration

public string Domain { get; }

Property Value

Type	Description
string

Hosting

Returns the cluster hosting options.

Declaration

public HostingOptions Hosting { get; }

Property Value

Type	Description
HostingOptions

HostingManager

Returns associated IHostingManager.

Declaration

public IHostingManager HostingManager { get; set; }

Property Value

Type	Description
IHostingManager

Hosts

Returns the list of node host proxies for hosting managers that need to manipulate host machines.

Declaration

public List<LinuxSshProxy> Hosts { get; }

Property Value

Type	Description
List<LinuxSshProxy>

Remarks

This is initialized by hosting managers such as XenServer and probably Hyper-V in the future so that status changes for host machines will be included in SetupController<NodeMetadata> UX status updates properly.

Hosting managers should add any hosts to this list when the manager is constructed and then leave this list alone during provisioning.

Id

Returns the cluster ID.

Declaration

public string Id { get; }

Property Value

Type	Description
string

K8s

Returns the IKubernetes client for the cluster.

Declaration

public IKubernetes K8s { get; }

Property Value

Type	Description
IKubernetes

KubeConfig

Returns the Kubernetes config holding the current cluster.

Declaration

public KubeConfig KubeConfig { get; set; }

Property Value

Type	Description
KubeConfig

Name

Returns the cluster name.

Declaration

public string Name { get; }

Property Value

Type	Description
string

Nodes

Returns a read-only list of cluster node proxies. This property is available only when the ClusterProxy is being used to deploy a cluster.

Declaration

public IReadOnlyList<NodeSshProxy<NodeDefinition>> Nodes { get; }

Property Value

Type	Description
IReadOnlyList<NodeSshProxy<NodeDefinition>>

Exceptions

Type	Condition
InvalidOperationException	Thrown when the cluster proxy is not configured to deplpy a cluster.

SecureRunOptions

Specifies the RunOptions to use when executing commands that include secrets. This defaults to Redact for best security but may be changed to just None when debugging cluster setup.

Declaration

public RunOptions SecureRunOptions { get; set; }

Property Value

Type	Description
RunOptions

SetupState

Set to the setup state while the cluster is being provisioned, null otherwise.

Declaration

public KubeSetupState SetupState { get; set; }

Property Value

Type	Description
KubeSetupState

Workers

Enumerates the cluster worker node proxies sorted in ascending order by name.

Declaration

public IEnumerable<NodeSshProxy<NodeDefinition>> Workers { get; }

Property Value

Type	Description
IEnumerable<NodeSshProxy<NodeDefinition>>

Methods

AddContainerRegistryResourcesAsync(ClusterDefinition)

Adds custom V1NeonContainerRegistry resources defined in the cluster definition to the cluster. neon-node-agent will pick these up and regenerate the CRI-O configuration.

Declaration

public Task AddContainerRegistryResourcesAsync(ClusterDefinition clusterDefinition = null)

Parameters

Type	Name	Description
ClusterDefinition	clusterDefinition	Optionally specifies a cluster definitinn for situations where the cluster is already deployed and the definition is not otherwise avalable. This is typically used by ClusterFixture based unit tests.

Returns

Type	Description
Task	The tracking Task.

ClearNodeStatus()

Clears the status for the all of the cluster nodes.

Declaration

public void ClearNodeStatus()

Create(KubeConfig, KubeConfigContext, IHostingManagerFactory, Operation, NodeProxyCreator, RunOptions)

Creates a cluster proxy for the the specified context in a KubeConfig.

Declaration

public static ClusterProxy Create(KubeConfig kubeConfig, KubeConfigContext context, IHostingManagerFactory hostingManagerFactory, ClusterProxy.Operation operation = Operation.LifeCycle, NodeProxyCreator nodeProxyCreator = null, RunOptions defaultRunOptions = RunOptions.None)

Parameters

Type	Name	Description
KubeConfig	kubeConfig	The Kubernetes config with the current context set to the target cluster.
KubeConfigContext	context	Specifies the context for the cluster.
IHostingManagerFactory	hostingManagerFactory	The hosting manager factory,
ClusterProxy.Operation	operation	Optionally identifies the operations that will be performed using the proxy. This defaults to LifeCycle.
NodeProxyCreator	nodeProxyCreator	The application supplied function that creates a management proxy given the node name, public address or FQDN, private address, and the node definition.
RunOptions	defaultRunOptions	Optionally specifies the RunOptions to be assigned to the DefaultRunOptions property for the nodes managed by the cluster proxy. This defaults to None.

Returns

Type	Description
ClusterProxy	The ClusterProxy.

Create(KubeConfig, IHostingManagerFactory, Operation, NodeProxyCreator, RunOptions, bool)

Creates a cluster proxy for the current context in a KubeConfig.

Declaration

public static ClusterProxy Create(KubeConfig kubeConfig, IHostingManagerFactory hostingManagerFactory, ClusterProxy.Operation operation = Operation.LifeCycle, NodeProxyCreator nodeProxyCreator = null, RunOptions defaultRunOptions = RunOptions.None, bool needsCurrentContext = true)

Parameters

Type	Name	Description
KubeConfig	kubeConfig	The Kubernetes config with the current context set to the target cluster.
IHostingManagerFactory	hostingManagerFactory	The hosting manager factory,
ClusterProxy.Operation	operation	Optionally identifies the operations that will be performed using the proxy. This defaults to LifeCycle.
NodeProxyCreator	nodeProxyCreator	The application supplied function that creates a management proxy given the node name, public address or FQDN, private address, and the node definition.
RunOptions	defaultRunOptions	Optionally specifies the RunOptions to be assigned to the DefaultRunOptions property for the nodes managed by the cluster proxy. This defaults to None.
bool	needsCurrentContext	Optionally used to disable checks for a current cluster context. This defaults to true and can be passed as false for situations where co current context is required, like having the hosting manager check for resource availability.

Returns

Type	Description
ClusterProxy	The ClusterProxy.

Create(KubeSetupState, IHostingManagerFactory, bool, Operation, string, string, NodeProxyCreator, RunOptions)

Constructs a cluster proxy that will typically be used for deploying a new cluster.

Declaration

public static ClusterProxy Create(KubeSetupState setupState, IHostingManagerFactory hostingManagerFactory, bool cloudMarketplace, ClusterProxy.Operation operation = Operation.LifeCycle, string nodeImageUri = null, string nodeImagePath = null, NodeProxyCreator nodeProxyCreator = null, RunOptions defaultRunOptions = RunOptions.None)

Parameters

Type	Name	Description
KubeSetupState	setupState	Specifies cluster setup state.
IHostingManagerFactory	hostingManagerFactory	The hosting manager factory,
bool	cloudMarketplace	For cloud environments, this specifies whether the cluster should be provisioned using a VM image from the public cloud marketplace when true or from the private NEONFORGE image gallery for testing when false. This is ignored for on-premise environments. note Only NEONFORGE maintainers will have permission to use the private image.
ClusterProxy.Operation	operation	Optionally identifies the operations that will be performed using the proxy. This defaults to LifeCycle.
string	nodeImageUri	Optionally passed as the URI to the (GZIP compressed) node image.
string	nodeImagePath	Optionally passed as the local path to the (GZIP compressed) node image file.
NodeProxyCreator	nodeProxyCreator	The application supplied function that creates a management proxy given the node name, public address or FQDN, private address, and the node definition.
RunOptions	defaultRunOptions	Optionally specifies the RunOptions to be assigned to the DefaultRunOptions property for the nodes managed by the cluster proxy. This defaults to None.

Returns

Type	Description
ClusterProxy	The ClusterProxy.

Remarks

At least one of nodeImageUri or nodeImagePath must be passed for GetHostingManager(IHostingManagerFactory, bool, Operation, string) to work.

set The nodeProxyCreator function will be called for each node in the cluster definition giving the application the chance to create the node proxy using the node's SSH credentials and also to specify logging. A default creator that doesn't initialize SSH credentials and logging is used if null is passed.

CreateClusterInfoAsync()

Creates a ClusterInfo instance from information held by the cluster proxy.

Declaration

public Task<ClusterInfo> CreateClusterInfoAsync()

Returns

Type	Description
Task<ClusterInfo>

DeleteClusterAsync()

Removes 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 Task DeleteClusterAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

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

Dispose()

Releases all resources associated with the instance.

Declaration

public void Dispose()

Dispose(bool)

Releases all associated resources.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Pass true if we're disposing, false if we're finalizing.

EnsureSetupMode()

Ensures that the proxy is configured for provisioning the cluster.

Declaration

public void EnsureSetupMode()

Exceptions

Type	Condition
AssertException	Thrown when the proxy is not configured to provision the cluster.

ExecMinioCommandAsync(string, bool, IRetryPolicy, CancellationToken)

Executes a command on a Minio node using the mc Minio Client.

Declaration

public Task<ExecuteResponse> ExecMinioCommandAsync(string mcCommand, bool noSuccessCheck = false, IRetryPolicy retryPolicy = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	mcCommand	The Minio Client command.
bool	noSuccessCheck	Optionally disables the EnsureSuccess(bool) check.
IRetryPolicy	retryPolicy	Optionally specifies a IRetryPolicy.
CancellationToken	cancellationToken	Optionally specifies a cancellation token.

Returns

Type	Description
Task<ExecuteResponse>	The ExecuteResponse.

ExecSystemDbCommandAsync(string, string, bool, IRetryPolicy, CancellationToken)

Executes a PSQL command on one of the system database pods using the pgsql and returns the response. The database command is executed in the context of the NeonSystemDbAdminUser.

Declaration

public Task<ExecuteResponse> ExecSystemDbCommandAsync(string database, string psqlCommand, bool noSuccessCheck = false, IRetryPolicy retryPolicy = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	database	Identifies the target database.
string	psqlCommand	The PSQL command text.
bool	noSuccessCheck	Optionally disables the EnsureSuccess(bool) check.
IRetryPolicy	retryPolicy	Optionally specifies a IRetryPolicy.
CancellationToken	cancellationToken	Optionally specifies a cancellation token.

Returns

Type	Description
Task<ExecuteResponse>	The ExecuteResponse.

FindNode(string)

Looks for the NodeSshProxy<TMetadata> instance for a named node.

Declaration

public NodeSshProxy<NodeDefinition> FindNode(string nodeName)

Parameters

Type	Name	Description
string	nodeName	The node name.

Returns

Type	Description
NodeSshProxy<NodeDefinition>	The node proxy instance or null if the named node does not exist.

GetClusterHealthAsync(TimeSpan)

Returns the health status of a cluster.

Declaration

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

GetClusterInfoAsync()

Returns information about a cluster.

Declaration

public Task<ClusterInfo> GetClusterInfoAsync()

Returns

Type	Description
Task<ClusterInfo>	The ClusterHealth.

GetDeploymentAsync()

Fetches the cluster deployment details for the proxied cluster.

Declaration

public Task<ClusterDeployment> GetDeploymentAsync()

Returns

Type	Description
Task<ClusterDeployment>	The ClusterDeployment details.

GetNode(string)

Returns the NodeSshProxy<TMetadata> instance for a named node.

Declaration

public NodeSshProxy<NodeDefinition> GetNode(string nodeName)

Parameters

Type	Name	Description
string	nodeName	The node name.

Returns

Type	Description
NodeSshProxy<NodeDefinition>	The node definition.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the name node is not present in the cluster.

GetReachableControlNode(ReachableHostMode)

Returns a control-plane node that appears to be reachable because it answers a ping.

Declaration

public NodeSshProxy<NodeDefinition> GetReachableControlNode(ReachableHostMode failureMode = ReachableHostMode.ReturnFirst)

Parameters

Type	Name	Description
ReachableHostMode	failureMode	Specifies what should happen when there are no reachable control-plane nodes.

Returns

Type	Description
NodeSshProxy<NodeDefinition>	The reachable control-plane node or null.

Exceptions

Type	Condition
NeonKubeException	Thrown if no control-plane nodes are reachable and failureMode is passed as Throw.

GetReachableNode(Func<NodeSshProxy<NodeDefinition>, bool>, ReachableHostMode)

Selects a cluster node from the set of nodes that match a predicate that is reachable via the network because it answers a ping.

Declaration

public NodeSshProxy<NodeDefinition> GetReachableNode(Func<NodeSshProxy<NodeDefinition>, bool> predicate, ReachableHostMode failureMode = ReachableHostMode.ReturnFirst)

Parameters

Type	Name	Description
Func<NodeSshProxy<NodeDefinition>, bool>	predicate	Predicate used to select the candidate nodes.
ReachableHostMode	failureMode	Specifies what should happen when there are no reachable nodes.

Returns

Type	Description
NodeSshProxy<NodeDefinition>	The reachable node or null.

Exceptions

Type	Condition
NeonKubeException	Thrown if no nodes matching the predicate are reachable and failureMode is passed as Throw.

GetResourceAvailabilityAsync(long, long)

Returns the availability of resources required to deploy a cluster.

Declaration

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

IsClusterReadyAsync()

Queries the cluster to determine whether it's online.

Declaration

public Task<bool> IsClusterReadyAsync()

Returns

Type	Description
Task<bool>	true when the cluster reports that it's ready.

IsLockedAsync(CancellationToken)

Determines whether the cluster is considered to be locked to prevent potentially distructive operations such as Pause, Remove, Reset, Resume, or Stop. This is used to help prevent impacting production clusters by accident.

Declaration

public Task<bool?> IsLockedAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optionally specifies the cancellation token.

Returns

Type	Description
Task<bool?>	true when the cluster is locked, false when it's unlocked or null when the lock status cannot be determined.

Exceptions

Type	Condition
InvalidOperationException	Thrown then the proxy was created with the wrong constructor.

ListClusterDashboardsAsync()

Returns a dictionary mapping case-insensitive dashboard names to the dashboard information.

Declaration

public Task<Dictionary<string, V1NeonDashboard>> ListClusterDashboardsAsync()

Returns

Type	Description
Task<Dictionary<string, V1NeonDashboard>>	The dashboard dictionary.

LockAsync(CancellationToken)

Locks the cluster by modifying the ClusterLock configmap in the NeonStatus namespace. Potentially distructive operations like Pause, Remove, Reset, Resume, or Stop are not allowed on locked clusters.

Declaration

public Task LockAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optionally specifies the cancellation token.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
InvalidOperationException	Thrown then the proxy was created with the wrong constructor.

LogLine(string)

Writes a message to the logs associated with all cluster nodes.

Declaration

public void LogLine(string message = null)

Parameters

Type	Name	Description
string	message	Optionally specifies the log message.

ResetAsync(ClusterResetOptions, ClusterDefinition, Action<string>)

Resets the cluster to factory defaults by removing all non neon-* namespaces including default (which will be recreated to be empty) as well as restoring custom resources as required.

Declaration

public Task ResetAsync(ClusterResetOptions options = null, ClusterDefinition clusterDefinition = null, Action<string> progress = null)

Parameters

Type	Name	Description
ClusterResetOptions	options	Optionally specifies details about components to be reset. This defaults to resetting everything that makes sense.
ClusterDefinition	clusterDefinition	Optionally specifies a cluster definitinn for situations where the cluster is already deployed and the definition is not otherwise avalable. This is typically used by ClusterFixture based unit tests.
Action<string>	progress	Optionally specified a callback to be called with human readable progress messages.

Returns

Type	Description
Task	The tracking Task.

SaveSetupState()

Persists the setup state for the cluster.

Declaration

public void SaveSetupState()

SetClusterInfo(ClusterInfo)

Set information about a cluster.

Declaration

public Task SetClusterInfo(ClusterInfo clusterInfo)

Parameters

Type	Name	Description
ClusterInfo	clusterInfo	The information being set.

Returns

Type	Description
Task	The tracking Task.

StartAsync()

Starts a cluster if it's not already running.

note

This operation may not be supported for all environments.

Declaration

public Task StartAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

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

StopAsync(StopMode)

Stops a cluster if it's running.

note

This operation may not be supported for all environments.

Declaration

public Task StopAsync(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.

UnlockAsync(CancellationToken)

Unlocks the cluster by modifying the ClusterLock configmap in the NeonStatus namespace. Potentially distructive operations like Pause, Remove, Reset, Resume, or Stop are not allowed on locked clusters.

Declaration

public Task UnlockAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Optionally specifies the cancellation token.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
InvalidOperationException	Thrown then the proxy was created with the wrong constructor.