Kubernetes Kubectl Deploy/Usage Guide

Prerequisites

Go: Version 1.21 or later (required for compatibility with Kubernetes 1.29+)
Git: For cloning and version control
Kubernetes Cluster: Access to a cluster (v1.26+) for integration testing
Kubeconfig: Valid ~/.kube/config file or KUBECONFIG environment variable pointing to cluster credentials
Make: Optional, for build automation (if building full kubectl from kubernetes/kubernetes)

Installation

Important: This repository (kubernetes/kubectl) is a read-only mirror and staged repository. Pull requests must be made to the main kubernetes/kubernetes repository.

As a Go Library

Add specific packages to your project:

go get k8s.io/kubectl/pkg/cmd/util
go get k8s.io/kubectl/pkg/cmd/get
go get k8s.io/kubectl/pkg/cmd/apply
go get k8s.io/kubectl/pkg/cmd/debug

For Source Inspection/Development

git clone https://github.com/kubernetes/kubectl.git
cd kubectl
go mod download

Note: If you intend to contribute, clone the main Kubernetes repository instead:

git clone https://github.com/kubernetes/kubernetes.git

Configuration

Environment Variables

KUBECONFIG: Path to kubeconfig file (default: ~/.kube/config)
GOPROXY: Go module proxy (default: https://proxy.golang.org)
GO111MODULE: Set to on for module-aware mode (required)

Go Module Setup

Ensure your go.mod includes the correct import path:

module your-project

go 1.21

require (
    k8s.io/kubectl v0.29.0
    k8s.io/client-go v0.29.0
    k8s.io/apimachinery v0.29.0
)

Critical Constraint: Packages in this repository must not depend on k8s.io/kubernetes. Only depend on:

k8s.io/client-go
k8s.io/apimachinery
k8s.io/cli-runtime
Other external repositories

Build & Run

Running Tests

Full unit-test coverage is required for contributions:

# Run all unit tests
go test ./...

# Run tests for specific package (e.g., apply command)
go test ./pkg/cmd/apply/...

# Run with verbose output and race detection
go test -v -race ./pkg/cmd/util/...

Building Packages

Since this is a library repository, build specific packages:

# Verify packages compile
go build ./pkg/cmd/get
go build ./pkg/cmd/apply
go build ./pkg/cmd/debug
go build ./pkg/cmd/util/...

Using as a Library

Import packages in your Go application:

package main

import (
    "k8s.io/cli-runtime/pkg/genericclioptions"
    "k8s.io/kubectl/pkg/cmd/get"
    "k8s.io/kubectl/pkg/cmd/util"
)

func main() {
    streams := genericclioptions.IOStreams{In: os.Stdin, Out: os.Stdout, ErrOut: os.Stderr}
    cmd := get.NewCmdGet("kubectl", streams)
    // Execute or extend command
}

Building Full Kubectl Binary

The kubectl CLI source currently resides in kubernetes/kubernetes. To build the binary:

git clone https://github.com/kubernetes/kubernetes.git
cd kubernetes
make kubectl
# Binary output: ./_output/bin/kubectl

Deployment

As a Dependency in Go Projects

Import specific packages to minimize dependency tree:

import (
    cmdutil "k8s.io/kubectl/pkg/cmd/util"
    "k8s.io/kubectl/pkg/scheme"
)

Vendor dependencies (optional):
```
go mod vendor
```
Version alignment: Ensure k8s.io/kubectl, k8s.io/client-go, and k8s.io/apimachinery versions match your target Kubernetes cluster version.

Integration Patterns

CLI Extensions: Use pkg/cmd/util for helper functions and pkg/polymorphichelpers for resource-specific operations
Custom Controllers: Import pkg/scheme for Kubernetes type serialization
Debug Tools: Leverage pkg/cmd/debug packages for ephemeral container automation

Troubleshooting

Common Issues

Module Resolution Errors

go: k8s.io/kubectl@v0.29.0 requires k8s.io/client-go@v0.29.0

Solution: Ensure all Kubernetes-related modules use the same version tag:

go get k8s.io/kubectl@v0.29.0 k8s.io/client-go@v0.29.0 k8s.io/apimachinery@v0.29.0

Forbidden Dependency on k8s.io/kubernetes

import "k8s.io/kubernetes/pkg/..." is not allowed

Solution: This repository must remain independent of the main Kubernetes repository. Use k8s.io/client-go or k8s.io/apimachinery instead.

Test Failures Requiring Cluster

--- FAIL: TestApply (0.00s)
    apply_test.go:XX: unable to connect to server

Solution: Unit tests should not require a live cluster. Ensure you're running unit tests only:

go test -short ./...

OpenAPI/Schema Validation Errors If using pkg/validation or pkg/util/openapi, ensure your client matches the server version:

// Check server version compatibility
discoveryClient, _ := cmdutil.NewDiscoveryClient(kubeConfigFlags)

Solution: Pin to specific Kubernetes version tags in go.mod that match your target cluster.

Code Review Requirements

Before submitting changes (to kubernetes/kubernetes):

Ensure go vet ./... passes without warnings
Run gofmt -s -w on all modified files
Verify go mod tidy produces no changes
Check imports follow code review comments guidelines

Getting Help

Issues: File kubectl-specific issues at kubernetes/kubectl
Contributions: Submit PRs to kubernetes/kubernetes (sig-cli)
Community: Join SIG-CLI discussions via Kubernetes Community

How to Deploy & Use kubernetes/kubectl