Skip to main content

Cluster Definition

This documentation section describes the cluster definition format in detail. Here's the top-level structure of a cluster definition:

annotations: [map]
container: {}
datacenter: null
deployment: {}
description: null
features: {}
hosting: {}
isDesktop: false
jobs: {}
kubelet: {}
latitude: null
longitude: null
monitor: {}
name: [required]
network: {}
nodeOptions: {}
nodes: [map]
packageProxy: null
purpose: "unspecified"
resourceTags: []
security: {}
storage: {}
timeSources: [""]

map: Optionally specifies cluster annotations. Label names and values must follow the Kubernetes conventions and the prefix is reserved by NeonKUBE.


object: Customizes the cluster's container registry configuration.


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

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


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


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


object: Specifies optional features to be installed in the cluster.


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


bool: Indicates that the definition describes a NeonDESKTOP cluster. This is set to true by NeonDESKTOP when it deploys a desktop cluster and isn't typically set by cluster operators.


object: Specifies the schedules for cluster jobs.


object: Specifies Kubernetes cluster options.


decimal: 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.


decimal: 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.


object: Specifies options for the cluster integrated monitoring stack.


string: Specifies the cluster name.

NOTE: Names 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.


object: Describes the cluster's network configuration.


object: Specifies host node options, including Linux package manager settings.


map: Describes the cluster nodes.


string: 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 generally 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.

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.

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


string: Describes how the cluster is being used. Supported values are: unspecified, development, production, stage, and test


array: 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 and Azure.


object: Specifies cluster security options.


integer: cluster nodes are configured with a cryptographically random root account password. This defaults to 20 characters. The minumum length is 8.


object: Specifies cluster storage related options for Minio and OPenEBS.

volumesPerNode: 4
volumeSize: "2 GiB"
engine: "default"
nfsSize: "10 GiB"

Specifies the number of volumes per server. This defaults to 4.


The size of each volume to be mounted to each server. This defaults to 2 GiB.


string: Specifies which OpenEBS engine will be deployed within the cluster. Supported values are default, hostpath, cstor, jiva, or mayastor.

This defaults to default where NeonKUBE will try to choose a reasonable storage engine for your cluster. Currently, this selects hostpath for single-node clusters or jiva for multi-node clusters.


string: Specifies the size of the NFS file system to be created for the cluster. This defaults to 10 GiB and cannot be any smaller.


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

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.