How to create a cluster in Rancher v2.x using the Rancher CLI or v3 API

This document (000020121) is provided subject to the disclaimer at the end of this document.

Situation

Task

The process for creating Kubernetes clusters via the Rancher v2.x UI is documented in "Setting up Kubernetes Clusters in Rancher".

This article details the process for creating Kubernetes clusters in Rancher v2.x via the Rancher CLI or v3 API interfaces.

Pre-requisites

A Rancher v2.x instance
The Rancher CLI installed for CLI cluster creation (this can be downloaded from the Rancher UI, via the Download CLI link in the lower-right corner)
curl installed to make Rancher v3 API requests for API cluster creation
A Rancher API Key for a user with cluster creation permissions
A Rancher Kubernetes Engine (RKE) cluster config file in YAML or JSON format (optional)

Steps

The cluster creation process is detailed below for both the Rancher CLI and v3 API.

Cluster creation via the Rancher CLI

rancher login <server_url> --token <token>

Create the cluster:

To create a cluster with the default cluster configuration:
```
rancher cluster create <new_cluster_name>
```
If you are passing in an RKE cluster config file, do so as follows:
```
rancher cluster create --rke-config <rke_config_file> <new_cluster_name>
```

Cluster creation via the Rancher v3 API

Create a Rancher API Key, and save the access key and secret key as environment variables (export CATTLE_ACCESS_KEY=<access_key> && export CATTLE_SECRET_KEY=<secret_key>). Alternatively you can pass these directly into the curl request in place of the ${CATTLE_ACCESS_KEY} and ${CATTLE_SECRET_KEY} variables in the examples below.

Send a POST request to the /v3/clusters API endpoint of your Rancher server:

To create a cluster with the default cluster configuration:

curl -u "${CATTLE_ACCESS_KEY}:${CATTLE_SECRET_KEY}" \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"name":"test-cluster"}' \
'https://<rancher_server>/v3/clusters'

If you are passing in an RKE cluster config file, do so as follows:

curl -u "${CATTLE_ACCESS_KEY}:${CATTLE_SECRET_KEY}" \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @<rke_config_file> \
'https://<rancher_server>/v3/clusters'

Additional Reading

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.