Last modified February 21, 2019
Cluster Definition YAML Reference
gsctl create cluster command can consume YAML files conforming to this specification to create new clusters.
The YAML format corresponds directly with the Giant Swarm API v4 request body spec for creating clusters.
The following example defines a cluster with three worker nodes:
name: Example Cluster owner: myorg scaling: min: 3 max: 3 workers: - memory: size_gb: 16 cpu: cores: 8 storage: size_gb: 100
As you can possibly see, the definition is quite sparse. Not all worker nodes need to have specifications for storage, CPU, and memory. Where details aren’t specified, Giant Swarm will make use of defaults when creating the cluster.
Note: To learn about our current default values, available Kubernetes version, and valid ranges for the specifications for clusters, please contact us at email@example.com. We plan to offer simpler ways to inform you about current default values in the future.
In contrast to the example above, for AWS EC2 based clusters, worker nodes have to be specified by selecting an instance type. The following example shows how to select instance types for worker nodes instead. The keys
storage are not applicable here.
name: Example AWS Cluster owner: myorg scaling: min: 3 max: 3 workers: - aws: instance_type: m3.large
Note: As of now, in AWS based clusters all worker nodes must be of the same instance type. Based on your installation, only certain instance types may be available. Please contact the support team to learn which instance types are supported on your installation.
Root level keys
owner: Name of the owner organization.
name: Friendly name of the cluster. If not specified, a name will be generated.
workers: Array of node definition objects describing each worker node. See below for possible keys. If not specified, the default number of worker nodes with default settings will be created.
release: Allows to select a specific release version. The value must be the semver version number of an active relaese. To get information on all available releases, use the
gsctl list releasescommand.
Node definition keys
memory: The sub-key
size_gballows to specify the amount of RAM to provide in a node using an integer or float value. Only usable on KVM (on-premises/bare metal) installations.
cpu: The sub-key
coresallows to require a number of CPU cores as integer. Only usable on KVM (on-premises/bare metal) installations.
storage: The sub-key
size_gbis used to specify the amount of local node storage in GB as an integer or decimal number. Only usable on KVM (on-premises/bare metal) installations.
aws: Settings specific to AWS based clusters
aws.instance_type: The AWS EC2 instance type to use for worker nodes, e. g.
azure: Settings specific to Azure based clusters
azure.vm_size: The Azure VM size to use for worker nodes
General notes on YAML
Chances are that you already work with YAML in various places. If not, here are some hints:
In YAML, whitespace is important. Indentation must be made using blanks (space), not tabs.
If in doubt, check your YAML in a linter. There are plenty online, e. g. yamllint.com.
JSON is valid YAML. If you prefer JSON’s notation, just use valid JSON.
You can add comments to YAML files by starting a line with the character