Last modified May 12, 2022
'gsctl create cluster' command reference
gsctl and the REST API are being phased out. We don't have an end-of-life date yet. However, we recommend to familiarize yourself with our Management API and the kubectl gs plugin as a future-proof replacement. We provide a migration page to help you with the transition.
The command gsctl create cluster
allows to create new Kubernetes clusters.
You can use the command with very simple syntax to create a cluster using default values. Note that several cluster specification details cannot be changed after creation.
In order to configure all details of the cluster according to your requirements, you’ll create a cluster definition first and pass it to the command.
Command line examples
The first and rather trivial example shows how to create a cluster for organization myorg
and specifying the cluster name, while leaving all other settings to defaults:
gsctl create cluster --owner myorg --name "Test cluster"
The second example shows how to create a cluster where most or even all configurable details are specified, using a definition file:
gsctl create cluster --file prod_cluster_definition.yaml
Note that command line flags take precedence over values in the definition. This way you can, for example, define a default cluster name in the definition, but set a specific one via the --name
flag when applying the same definition several times.
Full argument reference
--file
,-f
: Definition file path. See cluster definition reference for details. The value-
means that the definition will be read from standard input.--owner
,-o
: Name of the owner organization. Overwrites a name given per definition file.--name
: Name of the cluster. Overwrites name given in definition file.--release
,-r
: Specific the workload cluster release version to use. Defaults to the latest active version. See list releases for details on listing available workload cluster releases.--create-default-nodepool
: Where node pools are supported (AWS since workload cluster release v10.0.0 and Azure since workload cluster release v13.0.0 ), setting this tofalse
allows to suppress the creation of a default node pool. A default node pools would otherwise be created automatically if no cluster definition is given specifying any node pools details, to get you started quickly.--master-ha
: Where supported, this istrue
by default, which means that the cluster will have three control plane nodes. Available on AWS since workload cluster release v11.4.0 . Set this tofalse
to have only one control plane node in the cluster (recommended only for test clusters).--output
: By specifying this flag with valuejson
, the output can be printed in JSON format. This is convenient for use in automation. See JSON output for examples.
Passing the cluster definition via standard input
The --file
(short -f
) flag accepts the special value -
to read a definition from standard input. Depending on your shell you can make use of that in various ways.
For example, you can use a pipe like this:
cat my-cluster.yaml | gsctl create cluster -f -
At least in bash, this syntax allows to include the entire definition in the command:
gsctl create cluster --file - <<EOF
owner: acme
name: Dev cluster
release: 7.1.1
EOF
JSON output
Passing flag --output
with value json
to gsctl create cluster
changes the printed output to be formatted as a JSON object.
Example success output:
{
"result": "created",
"id": "f01r4"
}
When requesting cluster creation with workload cluster release v10.0.0
on AWS, or 13.0.0
on Azure, it is possible to recieve created-with-errors
as value for the result
key. This indicates some problem with either node pool creation or label attachment.
Example error output:
{
"result": "error",
"error": {
"kind": "unknown",
"annotation": "Unauthorized",
"stack": [
{
"file": "/go/src/giantswarm/gsctl/commands/create/cluster/v5.go",
"line": 140
},
{
"file": "/go/src/giantswarm/gsctl/commands/create/cluster/command.go",
"line": 632
}
]
}
}
Related
- Cluster definition reference
gsctl list releases
- List all available workload cluster releasesgsctl create kubeconfig
- Getting a key pair and enablingkubectl
to access a clustergsctl delete cluster
- Deleting a cluster- Basics: Cluster Size and Autoscaling
- API: Create cluster (v4)
- API: Create cluster (v5)
Need help, got feedback?
We listen to your Slack support channel. You can also reach us at support@giantswarm.io. And of course, we welcome your pull requests!