Настройка kubeconfig на Linux: полное руководство по подключению

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

Kubeconfig — это основной файл конфигурации для kubectl, CLI-инструмента управления Kubernetes. Он хранит информацию о кластерах, пользователях, контекстах и методах аутентификации. Без корректно настроенного kubeconfig вы не сможете выполнять команды kubectl get pods, kubectl apply и другие.

После выполнения этого гайда вы сможете:

Подключить kubectl к одному или нескольким Kubernetes-кластерам
Переключаться между кластерами и пространствами имен
Управлять ресурсами кластера через командную строку

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

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

Установлен kubectl версии 1.20 или выше. Проверить: kubectl version --client.
Есть доступ к Kubernetes-кластеру — вы получили от администратора или облачного провайдера (GKE, EKS, AKS и др.) конфигурационные данные:
- URL API-сервера
- Сертификат CA или путь к его файлу
- Токен сервис-аккаунта или данные для аутентификации (например, client-certificate и client-key)
Права на запись в домашнюю директорию — у вашего пользователя должны быть права на создание ~/.kube и запись в ~/.kube/config.
Сетевой доступ к API-серверу — порт 6443 (по умолчанию) должен быть открыт.

Шаг 1: Получение конфигурации кластера

Конфигурация кластера может быть предоставлена в нескольких форматах:

Готовый kubeconfig-файл (чаще всего от облачных провайдеров). Пример содержимого:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBD...
    server: https://<API-сервер>:6443
  name: my-cluster
contexts:
- context:
    cluster: my-cluster
    user: admin
  name: my-cluster-admin
current-context: my-cluster-admin
kind: Config
users:
- name: admin
  user:
    token: eyJhbGciOiJSUzI1NiIs...

Отдельные параметры (URL, токен, сертификаты), которые нужно вручную добавить в kubeconfig с помощью kubectl config set-....

Если вы работаете с kubeadm-кластером, конфигурацию можно скопировать с мастер-ноды:

scp user@master-node:/etc/kubernetes/admin.conf ~/.kube/config

Если вы используете облачный провайдер, конфигурацию обычно можно скачать через веб-консоль или CLI (например, gcloud container clusters get-credentials для GKE).

Шаг 2: Размещение и объединение конфигураций

Стандартный путь для kubeconfig — ~/.kube/config. Если директории ~/.kube нет, создайте её:

mkdir -p ~/.kube

Вариант A: У вас есть один файл конфигурации

Просто скопируйте его в ~/.kube/config:

cp /путь/к/полученному/config ~/.kube/config

Вариант B: У вас несколько конфигураций (несколько кластеров)

Если у вас уже есть kubeconfig с другими кластерами, объедините конфигурации, чтобы не потерять существующие:

# Экспортируем существующий kubeconfig в переменную
export KUBECONFIG=~/.kube/config:/путь/к/новому/config

# Объединяем в один файл
kubectl config view --flatten > ~/.kube/config.tmp && mv ~/.kube/config.tmp ~/.kube/config

# Очищаем переменную
unset KUBECONFIG

Что делает команда kubectl config view --flatten?
Она объединяет все конфигурации из указанных файлов в один YAML, разрешая пересечения имён (clusters, users, contexts).

Шаг 3: Настройка прав доступа

Файл ~/.kube/config содержит чувствительные данные (сертификаты, токены). Ограничьте доступ только вашему пользователю:

chmod 600 ~/.kube/config

Если вы используете системные учетные записи (например, root для автоматизации), убедитесь, что файл доступен и для них, но не оставляйте его доступным для группы или всех (chmod 644 опасно!).

Шаг 4: Проверка подключения и контекстов

Проверьте, что kubectl видит кластер:

kubectl cluster-info

Пример успешного вывода:

Kubernetes control plane is running at https://<API-сервер>:6443
CoreDNS is running at https://<API-сервер>:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

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

kubectl config current-context

Вывод должен соответствовать имени контекста из kubeconfig (например, my-cluster-admin).

Посмотрите все доступные контексты:

kubectl config get-contexts

Переключитесь на нужный контекст (если их несколько):

kubectl config use-context <имя_контекста>

Проверьте доступ к ресурсам кластера:

kubectl get nodes

Если команда возвращает список нод (или пустой список, если у вас нет прав на их просмотр), подключение работает.

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

kubectl cluster-info должен показывать URL API-сервера без ошибок.
kubectl get namespaces должен возвращать список пространств имён (например, default, kube-system).
kubectl config view должен отображать валидный YAML без синтаксических ошибок.

Если все эти команды выполняются успешно, kubeconfig настроен корректно.

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

Проблема: `kubectl` выводит `The connection to the server <server> was refused` или `Unable to connect to the server`

Причины:

Неверный URL API-сервера в kubeconfig.
API-сервер не запущен или недоступен из вашей сети.
Брандмауэр блокирует порт 6443.

Решение:

Проверьте URL: kubectl config view | grep server.
Убедитесь, что вы можете пропинговать API-сервер (или использовать telnet <server> 6443).
Если кластер в облаке, проверьте настройки фаервола и VPC.

Проблема: `error: You must be logged in to the server (Unauthorized)`

Причины:

Истёк срок действия токена.
Неправильный токен или сертификаты в kubeconfig.
Учетная запись не имеет прав на кластер.

Решение:

Обновите токен (если используется временный) или проверьте корректность client-certificate и client-key.
Для облачных провайдеров выполните команду повторного получения учетных данных (например, aws eks update-kubeconfig).
Проверьте, что в kubeconfig указан правильный user и он существует в кластере (kubectl get users требует RBAC-прав).

Проблема: `error: no context exists with name <context>`

Причина: В kubeconfig нет контекста с таким именем (возможно, вы ошиблись в названии или конфигурация не была загружена).

Решение:

Посмотрите список контекстов: kubectl config get-contexts.
Если контекста нет, добавьте его через kubectl config set-context или исправьте current-context:
```
kubectl config set-current-context <существующий_контекст>
```

Проблема: `error: couldn't read client-certificate-file` или `client-key-file`

Причина: Указанные в kubeconfig пути к сертификатам недоступны или имеют неверные права.

Решение:

Проверьте пути в kubeconfig (kubectl config view).
Убедитесь, что файлы существуют и доступны для чтения вашему пользователю:
```
ls -l /путь/к/сертификату.crt
```
Если сертификаты встроены в kubeconfig (как certificate-authority-data), эта ошибка не должна возникать.

Проблема: Kubeconfig работает, но `kubectl get pods` возвращает `Forbidden`

Причина: Учетная запись, указанная в kubeconfig, не имеет прав на просмотр ресурсов в текущем пространстве имён.

Решение:

Проверьте, в каком контексте вы работаете: kubectl config current-context.
Посмотрите, какие права есть у пользователя: kubectl auth can-i get pods --namespace=<namespace>.
Попросите администратора кластера назначить нужные Role или ClusterRoleBinding.

Проблема: Kubeconfig содержит несколько кластеров, но `kubectl` по умолчанию подключается не к тому

Решение: Явно укажите контекст при выполнении команды:

kubectl --context <имя_контекста> get pods

Или измените текущий контекст глобально, как показано выше.

Часто задаваемые вопросы

Что такое kubeconfig и зачем он нужен?

Как проверить текущий kubeconfig?

Что делать, если kubectl выводит 'Unable to connect to the server'?

Как переключиться между несколькими кластерами?

Полезное

Получите конфигурацию кластера

Разместите файл в стандартной директории

Настройте права доступа

Проверьте подключение и контексты