Installation Guide

This guide covers how to install and set up kubectl-multi on your system.

Prerequisites

  • Go 1.21 or later
  • kubectl installed and configured
  • Access to KubeStellar managed clusters

Installation Methods

# Clone the repository
git clone <repository-url>
cd kubectl-multi
 
# Build and install as kubectl plugin
make install
 
# Or install system-wide
make install-system

Method 2: Manual Installation

# Build binary
make build
 
# Copy to PATH
cp bin/kubectl-multi ~/.local/bin/
chmod +x ~/.local/bin/kubectl-multi
 
# Verify installation
kubectl plugin list | grep multi

Method 3: Go Install (if available)

# Install directly with Go
go install <repository-url>@latest
 
# Make sure your GOPATH/bin is in your PATH
export PATH=$PATH:$(go env GOPATH)/bin

Verification

After installation, verify that the plugin is working correctly:

# Check if kubectl recognizes the plugin
kubectl plugin list | grep multi
 
# Test basic functionality
kubectl multi get nodes
 
# Check version (if implemented)
kubectl multi version

Configuration

Kubeconfig Setup

kubectl-multi uses your existing kubectl configuration. Make sure you have:

  1. Valid kubeconfig file (usually ~/.kube/config)
  2. Access to your KubeStellar ITS cluster
  3. Proper RBAC permissions for managed clusters

Required Permissions

The plugin needs the following permissions on your ITS cluster:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubectl-multi-reader
rules:
- apiGroups: ["cluster.open-cluster-management.io"]
  resources: ["managedclusters"]
  verbs: ["get", "list"]

And on managed clusters:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubectl-multi-reader
rules:
- apiGroups: [""]
  resources: ["*"]
  verbs: ["get", "list"]
- apiGroups: ["apps"]
  resources: ["*"]
  verbs: ["get", "list"]
# Add other API groups as needed

Troubleshooting Installation

Common Issues

Plugin Not Found

Error: unknown command "multi" for "kubectl"

Solution:

  • Ensure the binary is named kubectl-multi and is in your PATH
  • Run kubectl plugin list to verify the plugin is detected

Permission Denied

permission denied: kubectl-multi

Solution:

chmod +x /path/to/kubectl-multi

Go Build Issues

go: module not found

Solution:

# Ensure Go modules are initialized
go mod tidy
go mod download

Connection Issues

Error: failed to connect to ITS cluster

Solution:

  • Verify your kubeconfig is correct
  • Check if you can connect with regular kubectl: kubectl get nodes
  • Verify the ITS cluster context exists

Build Dependencies

If you’re building from source, you may need additional tools:

# Install make (if not available)
# On macOS
brew install make
 
# On Ubuntu/Debian
apt-get install build-essential
 
# On CentOS/RHEL
yum groupinstall "Development Tools"

Updating

To update kubectl-multi to the latest version:

# Pull latest changes
git pull origin main
 
# Rebuild and install
make install

Uninstallation

To remove kubectl-multi:

# Find the plugin location
which kubectl-multi
 
# Remove the binary
rm /path/to/kubectl-multi
 
# Or if installed via make
make uninstall

Next Steps

After successful installation:

  1. Read the Usage Guide for detailed examples
  2. Check the Architecture Guide to understand how it works
  3. See Development Guide if you want to contribute