Use vCluster CLI as a kubectl plugin

This guide demonstrates how to set up the vCluster CLI as a kubectl plugin and allows you to manage virtual clusters directly through kubectl commands.

Prerequisites

• Install the vCluster CLI
• Ensure kubectl is installed and properly configured

Set up the plugin

Mac/Linux

1. Locate the installed vCluster binary:

   which vcluster

   The output typically displays /usr/local/bin/vcluster.

2. Create a symlink with the name kubectl-vcluster:

   sudo ln -s /usr/local/bin/vcluster /usr/local/bin/kubectl-vcluster

Windows

1. Locate the vcluster.exe binary using File Explorer. It should be in C:\Users\<current user>\AppData\Roaming

2. Copy the vCluster binary to the same location and rename it to kubectl-vcluster.exe

Test the plugin

Verify the installation by runningthe following command:

kubectl vcluster --version

The output displays the installed vCluster version:

vcluster version 0.21.2

Use the plugin

After installation, you can run vCluster commands through kubectl:

# List vClusters
kubectl vcluster list

# Create a vCluster
kubectl vcluster create my-vcluster

# Connect to a vCluster
kubectl vcluster connect my-vcluster

Troubleshoot kubectl plugin issues

Plugin not found

If kubectl cannot find the plugin:

• Verify the renamed binary is in a directory included in your system's PATH
• Check the paths with echo $PATH (macOS/Linux) or echo %PATH% (Windows)
• Ensure the binary name begins with kubectl- and has no file extension on macOS/Linux

Permission denied

If you get permission errors:

• For macOS/Linux: Ensure the binary has executable permissions with chmod +x /usr/local/bin/kubectl-vcluster.
• For Windows: Verify the file permissions and PATH configuration.