Rancher Quickstart¶

Create a single-node or highly available Kubernetes cluster with Rancher. You will create the cluster, test its ingress endpoint, and connect to it with kubectl.

Prerequisites¶

Complete the onboarding flow and activate your DevOpsCentral account before you begin.

Single Node Cluster¶

Step 1: Copy Your Application Credential Secret Name¶

● Open Voyager Quick Start.
⤷ Under Your Application Credentials, copy the value shown as Secret Name.

The name follows this pattern:

os-app-cred-xxxxxxxxxx

Copy Secret Name. This is the only application credential value you need to enter in Rancher.

Step 2: Open Rancher¶

● On Voyager Quick Start, find the Rancher launcher.
⤷ Select Launch Now.

Alternative

You can also open Rancher by selecting the Rancher icon in the upper-right service launcher.

Step 3: Create Your Cluster¶

● Select Create.
⤷ On Cluster: Create, select rke2-cluster-templates (look for the DevOpsCentral logo).
⤷ Open Edit Options.
⤷ Select the General tab and leave the defaults unchanged.
⤷ Paste the Secret Name into applicationCredentialSecretName.
⤷ Select Install.

Step 4: Wait for Provisioning¶

Rancher opens the Clusters page and begins provisioning the cluster. Provisioning usually takes several minutes, but timing varies. Continue when Rancher reports that the cluster is ready.

Step 5: Test the Ingress Endpoint¶

● Open Skyline.
⤷ Select Compute.
⤷ Select Instances.
⤷ Locate the instance created for your cluster and copy its Floating IP.

Run this command from your Linux terminal, replacing <floating_ip> with the Floating IP:

curl --connect-timeout 10 --head "http://<floating_ip>"

Expected result

HTTP/1.1 404 Not Found

A 404 Not Found response is expected from the default ingress endpoint because no application route has been created yet.

Using Horizon

If you use Horizon, the Floating IP is also available under Compute -> Instances.

Step 6: Install kubectl on Linux¶

Install kubectl to manage the cluster from your Linux terminal. These commands install the current stable Linux amd64 client and verify its checksum before installation.

KUBECTL_VERSION="$(curl -fsSL https://dl.k8s.io/release/stable.txt)"
curl -fsSLO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
curl -fsSLO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl kubectl.sha256
kubectl version --client

Expected result

kubectl: OK
Client Version: v1.x.y

These commands are for Linux amd64. If you use another architecture, follow the official kubectl installation guide.

Step 7: Download and Use KubeConfig¶

● In Rancher, select your cluster from the left sidebar.
⤷ The Cluster Dashboard opens.
⤷ In the upper-right corner, select Download KubeConfig and save the file locally.

Keep your KubeConfig private

The downloaded KubeConfig contains credentials for your cluster. Do not commit it to source control or share it.

Rancher names the downloaded file <cluster_name>.yaml. This tutorial creates a cluster named test, so the downloaded file is test.yaml.

Replacing an existing KubeConfig

These commands replace existing ~/.kube/config.

Run the following commands one at a time:

# Create the Kubernetes configuration directory.
mkdir -p "$HOME/.kube"

# Install the downloaded KubeConfig as the default configuration with owner-only permissions.
install -m 600 "$HOME/Downloads/test.yaml" "$HOME/.kube/config"

# Verify access to the cluster and display its nodes.
kubectl get nodes

Expected result

NAME                STATUS   ROLES              AGE   VERSION
your-cluster-node   Ready    control-plane,...   ...   v1.x.y+rke2r1

Confirm that one node has status Ready.

HA Cluster¶

If you want an HA cluster, complete Step 1 and Step 2 above, then use the HA-specific Steps 3 to 5 below. You do not need to create a single-node cluster first.

Step 3: Create Your HA Cluster¶

● Select Create.
⤷ On Cluster: Create, select rke2-cluster-templates (look for the DevOpsCentral logo).
⤷ Open Edit Options.
⤷ Select the General tab.
⤷ Change nodePoolTemplate to MultiPool.
⤷ Paste the Secret Name into applicationCredentialSecretName.
⤷ Open the Master Nodepool tab.
⤷ Set Node count to 3.

Worker node count

This configuration starts the cluster with one worker node by default. You can adjust the number of worker nodes later from the Rancher interface. To start with more than one worker node, open Worker Nodepool and set Node count to the required value.

● Leave the remaining settings unchanged and select Install.

Step 4: Wait for Provisioning¶

Rancher opens the Clusters page and begins provisioning the cluster. Provisioning usually takes several minutes, but timing varies. Continue when Rancher reports that the cluster is ready.

Step 5: Test the Ingress Endpoint¶

● Open Skyline.
⤷ Select Load Balancers.
⤷ Locate the load balancer created for your cluster and copy its Floating IP.

Run this command from your Linux terminal, replacing <floating_ip> with the Floating IP:

curl --connect-timeout 10 --head "http://<floating_ip>"

Expected result

HTTP/1.1 404 Not Found

A 404 Not Found response is expected from the default ingress endpoint because no application route has been created yet.

Using Horizon

If you use Horizon, open Load Balancers and copy the load balancer Floating IP there.

HA clusters use a load balancer Floating IP for public ingress. Kubernetes nodes do not receive direct Floating IPs.

To install kubectl and connect to the HA cluster, follow Single Node Cluster Steps 6 and 7 above.

Troubleshooting¶

Catalog installation errors may not be visible

Rancher may not display a clear error when a catalog installation fails. If the cluster does not appear or provisioning does not start after you select Install, check the following:

Application credential Secret Name: Confirm that applicationCredentialSecretName was not left empty and exactly matches the Secret Name copied from Voyager.
Project quota: Confirm that your OpenStack project has sufficient quota for the selected topology and node counts. HA clusters and additional worker nodes require more resources than the default single-node configuration.