Установка kubectl на Linux: полное руководство для начинающих

Введение / Зачем это нужно

kubectl — это командная строка (CLI) для управления кластерами Kubernetes. С её помощью вы разворачиваете приложения, inspectируете состояние ресурсов, управляете конфигурацией и отлаживаете работу в кластере. Без kubectl взаимодействие с Kubernetes сводится к прямым вызовам API, что крайне неудобно.

После выполнения этого гайда у вас будет установлен и готовый к работе клиент kubectl. Вы сможете подключаться к любому кластеру Kubernetes (управляемому сервисом вроде GKE/EKS/AKS или собственным) и выполнять основные операции.

Требования / Подготовка

Перед началом убедитесь, что:

1. У вас есть доступ к терминалу Linux (Ubuntu, CentOS, Debian, Fedora и т.д.) с правами sudo.
2. На машине установлен curl (обычно есть по умолчанию) или wget.
3. Вы знаете URL и имеют учетные данные для доступа к целевому кластеру Kubernetes (это нужно для шага настройки kubeconfig).

Шаг 1: Добавление официального репозитория Kubernetes

Рекомендуемый способ установки — через официальный репозиторий pkgs.k8s.io. Это гарантирует получение актуальных и проверенных версий.

Для дистрибутивов на базе Debian/Ubuntu (apt):

# 1. Скачайте и добавьте GPG-ключ репозитория
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# 2. Добавьте сам репозиторий в sources.list.d
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# 3. Обновите кэш пакетов
sudo apt-get update

💡 Совет: Замените v1.28 в URL на нужную вам минорную версию Kubernetes (например, v1.29). Актуальную версию можно уточнить на странице релизов.

Для дистрибутивов на базе RHEL/CentOS/Fedora (yum/dnf):

# 1. Создайте файл репозитория
sudo tee /etc/yum.repos.d/kubernetes.repo <<EOF
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.28/rpm/repodata/repomd.xml.key
EOF

# 2. Обновите кэш репозитория (для CentOS/RHEL 7 может потребоваться включить модуль)
sudo yum makecache

⚠️ Важно: Для CentOS/RHEL 7 может потребоваться явное включение модуля: sudo yum module enable -n containerd или sudo yum install -y containerd.

Шаг 2: Установка пакета kubectl

Теперь, когда репозиторий добавлен, установите сам пакет.

Для apt (Ubuntu/Debian):

sudo apt-get install -y kubectl

Для yum/dnf (CentOS/RHEL/Fedora):

# На CentOS/RHEL 7 используйте yum
sudo yum install -y kubectl

# На Fedora и более новых RHEL/CentOS используйте dnf
sudo dnf install -y kubectl

Команда установит бинарный файл kubectl в системный каталог (обычно /usr/local/bin или /usr/bin).

Шаг 3: Проверка установки и настройка автодополнения

Убедитесь, что установка прошла успешно:

kubectl version --client

Вывод должен показать версию клиента, например:

Client Version: v1.28.4

Если команда не найдена (command not found), проверьте, находится ли каталог установки в вашей PATH:

echo $PATH | grep -q '/usr/local/bin' || echo "Добавьте /usr/local/bin в PATH"

Настройка автодополнения по Tab (существенно ускоряет работу):

# Для bash
source <(kubectl completion bash)
echo "source <(kubectl completion bash)" >> ~/.bashrc

# Для zsh
source <(kubectl completion zsh)
echo "source <(kubectl completion zsh)" >> ~/.zshrc

Шаг 4: Настройка подключения к кластеру (kubeconfig)

kubectl ищет конфигурацию кластера в файле ~/.kube/config. Получить его можно несколькими способами:

1. От администратора кластера: Вам передадут файл config или команду для его получения.
2. Сервисы облачных провайдеров:
   • GKE (Google): gcloud container clusters get-credentials CLUSTER_NAME --zone ZONE --project PROJECT_ID
   • EKS (AWS): aws eks update-kubeconfig --name CLUSTER_NAME --region REGION
   • AKS (Azure): az aks get-credentials --resource-group RG_NAME --name CLUSTER_NAME
3. Локальный кластер (Minikube): minikube start автоматически настроит конфиг.

После настройки проверьте доступ:

kubectl cluster-info

Если вы видите URL API-сервера — подключение установлено.

Шаг 5: Базовые команды для проверки работоспособности

Выполните несколько простых команд, чтобы убедиться, что всё работает:

# Показать информацию о кластере
kubectl get nodes

# Показать пространства имен (namespaces)
kubectl get namespaces

# Получить справку по любой команде
kubectl get --help

Если kubectl get nodes выводит список нод вашего кластера (или для Minikube — одну ноду minikube), установка и настройка завершены успешно.

Проверка результата

Готовность подтверждается:

1. Команда kubectl version --client возвращает версию без ошибок.
2. Команда kubectl cluster-info показывает данные о подключенном кластере (или ошибку аутентификации, если конфиг неверный, но сам клиент работает).
3. Автодополнение по Tab предлагает ресурсы и имена.

Возможные проблемы

Ошибка: The connection to the server localhost:8080 was refused

Причина: Файл ~/.kube/config отсутствует или не содержит корректных данных о кластере. Решение: Настройте kubeconfig согласно шагу 4. Убедитесь, что вы выполнили команду от облачного провайдера или получили файл конфигурации.

Ошибка: error: You must be logged in to the server (Unauthorized)

Причина: В конфиге указаны неверные учетные данные (сертификат, токен, логин/пароль). Решение: Пересоздайте конфигурацию, получив новые учетные данные от администратора кластера или через CLI облачного провайдера (gcloud, aws, az).

Ошибка: kubectl: command not found после установки

Причина: Каталог, куда установлен бинарный файл (например, /usr/local/bin), не входит в переменную PATH текущей сессии. Решение: Добавьте путь в PATH в ~/.bashrc или ~/.zshrc и перезапустите терминал. Либо создайте симлинк: sudo ln -s /usr/local/bin/kubectl /usr/bin/kubectl.

Ошибка при установке пакета: Unable to read /etc/apt/sources.list.d/...

Причина: Неправильно создан файл репозитория или отсутствует GPG-ключ. Решение: Проверьте шаг 1. Убедитесь, что вы использовали sudo для записи в системные каталоги. Пересоздайте файл репозитория и ключ.

Версия kubectl несовместима с кластером

Причина: Разница версий больше одной минорной. Решение: Установите другую версию kubectl, указав нужный тег репозитория (например, v1.27 вместо v1.28). Либо обновите/понизьте версию самого кластера.

# Пример установки конкретной версии на Ubuntu
sudo apt-get install kubectl=1.27.5-00

# Пример на CentOS/RHEL
sudo yum install kubectl-1.27.5