Access Using kubeconfig

The recommended way to access a KubeRaya cluster is by using a kubeconfig file.

A kubeconfig file contains the authentication and endpoint information required to securely connect to the Kubernetes API (control plane).

This guide walks you through downloading, configuring, and verifying access to your KubeRaya cluster using kubectl.

What Is kubeconfig?

A kubeconfig file is a YAML configuration file used by Kubernetes clients.

It defines:

• Cluster API endpoint
• Certificate authority
• Authentication credentials
• Context and user mapping

CloudRaya automatically generates a ready-to-use kubeconfig for each Kubernetes cluster.

No manual certificate or credential setup is required.

Prerequisites

Before you begin, make sure:

• You have an active KubeRaya cluster
• You have access to the CloudRaya dashboard
• kubectl is installed on your local machine

📄 kubectl installation:
https://kubernetes.io/docs/tasks/tools/

Step 1: Download the kubeconfig File

You can download the kubeconfig file from the CloudRaya dashboard.

Option A: From the Cluster List

1. Open Dashboard → Compute → KubeRaya
2. Locate your cluster
3. Click the action menu
4. Select Download Config File

Option B: From Cluster Detail Page

1. Open Dashboard → Compute → KubeRaya
2. Click View Detail on the cluster
3. Click Download Config

The file will be downloaded to your local machine (usually named something like config or kubernetes.conf).

Step 2: Place the kubeconfig File

kubectl looks for kubeconfig files in a default location.

Default Location (Recommended)

Move the downloaded file to:

~/.kube/config

If the directory does not exist, create it:

mkdir -p ~/.kube

Then move the file:

mv ~/Downloads/config ~/.kube/config

If you already have an existing kubeconfig, see Using Multiple kubeconfig Files below.

Step 3: Verify Cluster Access

Once the kubeconfig file is in place, verify access using kubectl.

Check Cluster Connectivity

kubectl cluster-info

Expected result:

• Kubernetes control plane endpoint is reachable
• No authentication errors

List Nodes

kubectl get nodes

You should see:

• One or more master nodes (control plane)
• One or more worker nodes

This confirms that your local machine is successfully connected to the KubeRaya cluster.

Step 4: Verify Current Context

A kubeconfig file can contain multiple clusters and contexts.

Check the active context:

kubectl config current-context

List available contexts:

kubectl config get-contexts

If needed, switch context:

kubectl config use-context <context-name>

Using Multiple kubeconfig Files (Advanced)

If you manage multiple clusters, you can keep separate kubeconfig files.

Option 1: Use KUBECONFIG Environment Variable

export KUBECONFIG=~/kubeconfigs/cluster1.yaml

Option 2: Merge kubeconfig Files

export KUBECONFIG=~/.kube/config:~/kubeconfigs/cluster2.yaml
kubectl config view --merge --flatten > ~/.kube/config

This approach is commonly used by teams managing multiple environments.

Security Best Practices

kubeconfig files grant administrative access to your cluster.

Follow these best practices:

• Store kubeconfig files securely
• Do not upload kubeconfig files to public repositories
• Do not share kubeconfig files over chat or email
• Regenerate kubeconfig if credentials are exposed
• Restrict access at the operating system level

📄 See: Kubernetes Security Basics

Common Issues & Troubleshooting

Connection Refused or Timeout

• Ensure the cluster status is Running
• Verify network connectivity
• Check firewall or VPN configuration if applicable

Authentication Errors

• Re-download the kubeconfig file
• Ensure the correct context is active
• Confirm the file has not been modified

Wrong Cluster Accessed

• Check current context
• Switch context explicitly

When to Use kubeconfig Access

Use kubeconfig access for:

• Application deployment
• Cluster administration
• CI/CD pipelines
• Debugging workloads
• Production operations

This is the standard and most reliable access method.

Related Guides

📄 Access a KubeRaya Cluster

📄 Create a KubeRaya Cluster

📄 Access Using Kubernetes Dashboard

📄 Access Using Lens

📄 Kubernetes Security Basics