Class ClusterDefinition

Describes a Kubernetes cluster.

Inheritance

object

ClusterDefinition

Namespace: Neon.Kube.ClusterDef

Assembly: Neon.Kube.dll

Syntax

public class ClusterDefinition

Constructors

ClusterDefinition()

Default constructor.

Declaration

public ClusterDefinition()

Fields

MaxClusterNameLength

Maximum number of characters allowed in a cluster name.

Declaration

public const int MaxClusterNameLength = 24

Field Value

Type	Description
int

ReservedNodePrefix

The prefix reserved for NEONKUBE specific node annotations and labels.

Declaration

public const string ReservedNodePrefix = "node.neonkube.io/"

Field Value

Type	Description
string

ReservedPrefix

The prefix reserved for NEONKUBE specific annotations and labels.

Declaration

public const string ReservedPrefix = "neonkube.io/"

Field Value

Type	Description
string

Properties

Annotations

Optionally specifies cluster annotations. Label names and values must follow the Kubernetes conventions and the neonkube.io/ prefix is reserved by NEONKUBE.

Declaration

[JsonProperty(PropertyName = "Annotations", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "annotations", ApplyNamingConventions = false)]
public Dictionary<string, string> Annotations { get; set; }

Property Value

Type	Description
Dictionary<string, string>

ClusterVersion

Optionally specifies the semantic version of the NEONKUBE cluster being created. This defaults to null which indicates that the latest supported cluster version will be created.

Declaration

[JsonProperty(PropertyName = "ClusterVersion", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "clusterVersion", ApplyNamingConventions = false)]
public string ClusterVersion { get; set; }

Property Value

Type	Description
string

Container

Customizes the cluster's container configuration.

Declaration

[JsonProperty(PropertyName = "Container", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "container", ApplyNamingConventions = false)]
public ContainerOptions Container { get; set; }

Property Value

Type	Description
ContainerOptions

ControlNodes

Enumerates the cluster control-plane node definitions.

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> ControlNodes { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

Datacenter

Identifies the datacenter. This defaults to empty string for on-premise clusters or the region for clusters deployed to the cloud.

Declaration

[JsonProperty(PropertyName = "Datacenter", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "datacenter", ApplyNamingConventions = false)]
public string Datacenter { get; set; }

Property Value

Type	Description
string

Remarks

note

The name may include only letters, numbers, periods, dashes, and underscores.

Deployment

Optionally specifies options used by ClusterFixture and possibly custom tools for customizing cluster and node names to avoid conflicts.

Declaration

[JsonProperty(PropertyName = "Deployment", Required = Required.Always)]
[YamlMember(Alias = "deployment", ApplyNamingConventions = false)]
public DeploymentOptions Deployment { get; set; }

Property Value

Type	Description
DeploymentOptions

Description

Optionally describes the cluster for humans. This may be a string up to 256 characters long.

Declaration

[JsonProperty(PropertyName = "Description", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "description", ApplyNamingConventions = false)]
public string Description { get; set; }

Property Value

Type	Description
string

DnsNameRegex

Regex for verifying cluster names for hosts, routes, groups, etc. This also can be used to (lightly) validate DNS host names.

Declaration

public static Regex DnsNameRegex { get; }

Property Value

Type	Description
Regex

Features

Specifies optional features to be installed in the cluster.

Declaration

[JsonProperty(PropertyName = "Features", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "features", ApplyNamingConventions = false)]
public FeatureOptions Features { get; set; }

Property Value

Type	Description
FeatureOptions

Hosting

Specifies hosting related settings (e.g. the cloud provider). This defaults to null which indicates that the cluster will be hosted on private servers.

Declaration

[JsonProperty(PropertyName = "Hosting", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "hosting", ApplyNamingConventions = false)]
public HostingOptions Hosting { get; set; }

Property Value

Type	Description
HostingOptions

IsDesktop

Indicates whether the definition describes a NEONDESKTOP clusters.

Declaration

[JsonProperty(PropertyName = "IsDesktop", Required = Required.Always)]
[YamlMember(Alias = "isDesktop", ApplyNamingConventions = false)]
public bool IsDesktop { get; set; }

Property Value

Type	Description
bool

IsLocked

Indicates whether the cluster should be locked after being deployed successfully. neon-desktop, neon-cli, and ClusterFixture will block distructive operations such as cluster pause, reset, remove, and stop on locked clusters as to help avoid impacting production clusters by accident.

Declaration

[JsonProperty(PropertyName = "IsLocked", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "isLocked", ApplyNamingConventions = false)]
public bool IsLocked { get; set; }

Property Value

Type	Description
bool

Jobs

Specifies the schedules for cluster jobs.

Declaration

[JsonProperty(PropertyName = "Jobs", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "jobs", ApplyNamingConventions = false)]
public JobOptions Jobs { get; set; }

Property Value

Type	Description
JobOptions

Kubernetes

Returns the Kubernetes cluster options.,

Declaration

[JsonProperty(PropertyName = "Kubernetes", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "kubernetes", ApplyNamingConventions = false)]
public KubernetesOptions Kubernetes { get; set; }

Property Value

Type	Description
KubernetesOptions

Latitude

Optionally specifies the latitude of the cluster location. This is a value between -90 and +90 degrees.

note

Latitude and Longitude must both be specified together or not at all.

Declaration

public double? Latitude { get; set; }

Property Value

Type	Description
double?

Longitude

Optionally specifies the longitude of the cluster location. This is a value between -180 and +180 degrees.

note

Latitude and Longitude must both be specified together or not at all.

Declaration

public double? Longitude { get; set; }

Property Value

Type	Description
double?

Monitor

Returns the options to be used for configuring the cluster integrated Elasticsearch/Fluentd/Kibana (Mon) logging stack.

Declaration

[JsonProperty(PropertyName = "Monitor", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "monitor", ApplyNamingConventions = false)]
public MonitorOptions Monitor { get; set; }

Property Value

Type	Description
MonitorOptions

Name

The cluster name.

note

The name may include only letters, numbers, periods, dashes, and underscores and may be up to 24 characters long. Some hosting environments enforce length limits on resource names that we derive from the cluster name, so please limit your cluster name to 24 characters.

Declaration

[JsonProperty(PropertyName = "Name", Required = Required.Always)]
[YamlMember(Alias = "name", ApplyNamingConventions = false)]
public string Name { get; set; }

Property Value

Type	Description
string

NameRegex

Regex for verifying non-DNS like names that start and end with a letter or digit and may also include dashes and underscores.

Declaration

public static Regex NameRegex { get; }

Property Value

Type	Description
Regex

Network

Describes the cluster's network configuration.

Declaration

[JsonProperty(PropertyName = "Network", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "network", ApplyNamingConventions = false)]
public NetworkOptions Network { get; set; }

Property Value

Type	Description
NetworkOptions

NodeDefinitions

Describes the cluster nodes.

Declaration

[JsonProperty(PropertyName = "Nodes", Required = Required.Always)]
[YamlMember(Alias = "nodes", ApplyNamingConventions = false)]
public Dictionary<string, NodeDefinition> NodeDefinitions { get; set; }

Property Value

Type	Description
Dictionary<string, NodeDefinition>

NodeOptions

Specifies host node options.

Declaration

[JsonProperty(PropertyName = "NodeOptions", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "nodeOptions", ApplyNamingConventions = false)]
public NodeOptions NodeOptions { get; set; }

Property Value

Type	Description
NodeOptions

Nodes

Enumerates all cluster node definitions.

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> Nodes { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

PackageProxy

Optionally specifies one or more APT proxy/cache servers the cluster will use to install and update Linux packages. These are endpoints like HOSTNAME:PORT or ADDRESS.PORT of a apt-cacher-ng or other package proxy server. The port is generall set to 3142 Multiple proxies may be specified by separating them with spaces. This defaults to referencing the apt-cacher-ng instances running on the control-plane nodes.

Declaration

[JsonProperty(PropertyName = "PackageProxy", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "packageProxy", ApplyNamingConventions = false)]
public string PackageProxy { get; set; }

Property Value

Type	Description
string

Remarks

A package cache will greatly reduce the Internet network traffic required to deploy a cluster, especially for large clusters.

note

The cluster nodes are configured to failover to different proxies or to hit the default Linux distribution package mirror directly if any or all of the caches specified are unavailable.

note

The package caches will be tried in the order they are listed. This essentially makes the first cache primary, with the others as backups.

Purpose

Indicates how the cluster is being used.

Declaration

[JsonProperty(PropertyName = "Purpose", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "purpose", ApplyNamingConventions = false)]
[JsonConverter(typeof(StringEnumConverter))]
public ClusterPurpose Purpose { get; set; }

Property Value

Type	Description
ClusterPurpose

ResourceTags

Optionally specifies custom tags that will be attached to cluster resources in cloud hosting environments. These tags are intended to help you manage your cloud resources as well as help organize your cost reporting.

note

Currently, this is only supported for clusters deployed to AWS, Azure or Google Cloud.

Declaration

public List<ResourceTag> ResourceTags { get; set; }

Property Value

Type	Description
List<ResourceTag>

RootPassword

Optionally specifies the cluster root single sign-on (SSO) password. A random password with of PasswordLength will be created by default when no password is specified here.

Declaration

[JsonProperty(PropertyName = "RootPassword", Required = Required.Default)]
[YamlMember(Alias = "rootPassword", ApplyNamingConventions = false)]
public string RootPassword { get; set; }

Property Value

Type	Description
string

Security

Specifies cluster security options.

Declaration

[JsonProperty(PropertyName = "Security", Required = Required.Always)]
[YamlMember(Alias = "security", ApplyNamingConventions = false)]
public SecurityOptions Security { get; set; }

Property Value

Type	Description
SecurityOptions

SortedControlNodes

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

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> SortedControlNodes { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

SortedControlThenWorkerNodes

Enumerates the cluster control-plane nodes sorted by name followed by the worker nodes, also sorted by name. This is convienent for situations like assigning IP addresses or ports such that the control-plane nodes are grouped together first.

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> SortedControlThenWorkerNodes { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

SortedNodes

Enumerates all cluster node definitions sorted in ascending order by name.

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> SortedNodes { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

SortedWorkerNodes

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

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> SortedWorkerNodes { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

Storage

Specifies the cluster storage related options.

Declaration

[JsonProperty(PropertyName = "Storage", Required = Required.Always)]
[YamlMember(Alias = "storage", ApplyNamingConventions = false)]
public StorageOptions Storage { get; set; }

Property Value

Type	Description
StorageOptions

TimeSources

Specifies the NTP time sources to be configured for the cluster. These are the FQDNs or IP addresses of the sources. This defaults to pool.ntp.org.

Declaration

[JsonProperty(PropertyName = "TimeSources", Required = Required.Default, DefaultValueHandling = DefaultValueHandling.IgnoreAndPopulate)]
[YamlMember(Alias = "timeSources", ApplyNamingConventions = false)]
public string[] TimeSources { get; set; }

Property Value

Type	Description
string[]

Remarks

The cluster control-plane nodes will be configured to synchronize their time with these time sources and the worker nodes will be configured to synchronize their time with the control-plane nodes.

Workers

Enumerates the cluster worker node definitions.

Declaration

[JsonIgnore]
[YamlIgnore]
public IEnumerable<NodeDefinition> Workers { get; }

Property Value

Type	Description
IEnumerable<NodeDefinition>

Methods

AddNode(NodeDefinition)

Adds a node to the cluster.

Declaration

public void AddNode(NodeDefinition node)

Parameters

Type	Name	Description
NodeDefinition	node	The new node.

AreSimilar(ClusterDefinition, ClusterDefinition)

INTERNAL USE ONLY: Compares two ClusterDefinition instances to determine whether they can be considered the same by ClusterFixture when it's deciding whether to reuse an existing cluster or deploy a new one.

note

This method works by comparing the definitions serialized to JSON after removing a handful of unimportant properties that may conflict.

Declaration

public static bool AreSimilar(ClusterDefinition definition1, ClusterDefinition definition2)

Parameters

Type	Name	Description
ClusterDefinition	definition1	The first cluster definition.
ClusterDefinition	definition2	The second cluster definition.

Returns

Type	Description
bool	true when the definitions are close enough for ClusterFixture.

FromFile(string, bool)

Parses a YAML cluster definition from a file.

Declaration

public static ClusterDefinition FromFile(string path, bool strict = false)

Parameters

Type	Name	Description
string	path	The file path.
bool	strict	Optionally require that all input properties map to ClusterDefinition properties.

Returns

Type	Description
ClusterDefinition	The parsed ClusterDefinition.

Remarks

note

The source is first preprocessed using PreprocessReader and then is parsed as JSON.

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if the definition is not valid.
IOException	Thrown if the file could not be read.

FromYaml(string, bool, bool)

Parses a cluster definition from YAML text.

Declaration

public static ClusterDefinition FromYaml(string yaml, bool strict = false, bool validate = false)

Parameters

Type	Name	Description
string	yaml	The JSON text.
bool	strict	Optionally require that all input properties map to ClusterDefinition properties.
bool	validate	Optionally validate the cluster definition. note You must have already called HostingLoader.Initialize() for validation to work.

Returns

Type	Description
ClusterDefinition	The parsed ClusterDefinition.

Remarks

note

The source is first preprocessed using PreprocessReader and then is parsed as YAML.

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if the definition is not valid.

IsValidName(string)

Verifies that a string is a valid cluster name.

Declaration

public static bool IsValidName(string name)

Parameters

Type	Name	Description
string	name	The name being tested.

Returns

Type	Description
bool	true if the name is valid.

Redact()

Clones the current cluster definition and then removes any hosting related secrets, as well as temporary state used by the hosting managers.

Declaration

public ClusterDefinition Redact()

Returns

Type	Description
ClusterDefinition	The redacted cluster definition.

Validate()

Validates the cluster definition and also ensures that all null properties are initialized to their default values.

Declaration

public void Validate()

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if the definition is not valid.

ValidateFile(string, bool)

Parses and validates a YAML cluster definition file.

Declaration

public static void ValidateFile(string path, bool strict = false)

Parameters

Type	Name	Description
string	path	The file path.
bool	strict	Optionally require that all input properties map to ClusterDefinition properties.

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if the definition is not valid.
IOException	Thrown if the file could not be read.

ValidatePrivateNodeAddresses()

Validates that node private IP addresses are set, are within the nodes subnet, and are unique. This method is intended to be called from hosting options classes like BareMetalHostingOptions which require specified node IP addresses.

Declaration

public void ValidatePrivateNodeAddresses()

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if the definition is not valid.

ValidateSize(string, Type, string, string)

Ensures that a VM memory or disk size specification is valid and also converts the value to the corresponding long byte count.

Declaration

public static long ValidateSize(string sizeValue, Type optionsType, string propertyName, string minimum = null)

Parameters

Type	Name	Description
string	sizeValue	The size value string.
Type	optionsType	Type of the property holding the size property (used for error reporting).
string	propertyName	The size property name (used for error reporting).
string	minimum	Optionally specifies the m inimum size as ByteUnits.

Returns

Type	Description
long	The size converted into a long.

Exceptions

Type	Condition
ClusterDefinitionException	Thrown if the size is not valid.