Настройка контекста kubectl в Linux: полное руководство

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

Работая с Kubernetes, особенно в продакшн-среде или при наличии нескольких кластеров (dev, staging, prod), вам постоянно нужно переключаться между ними. Контекст kubectl — это именно тот механизм, который хранит комбинацию «кластер + пользователь + namespace» и позволяет мгновенно переключаться между разными окружениями одной командой.

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

• Просматривать все доступные контексты.
• Создавать и настраивать новые контексты.
• Быстро переключаться между кластерами.
• Управлять пространствами имён по умолчанию для каждого контекста.

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

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

1. Установлен и работоспособен kubectl (версия 1.20 или выше).
2. У вас уже есть доступ как минимум к одному Kubernetes-кластеру (т.е. в ~/.kube/config уже есть хотя бы один рабочий контекст).
3. Вы обладаете необходимыми правами для доступа к кластерам (обычно через kubeconfig-файл или aws eks и т.п.).
4. Вы работаете в Linux-окружении (Ubuntu, CentOS, Fedora и др.) сbash-совместимой оболочкой.

Пошаговая инструкция

Шаг 1: Проверьте текущую конфигурацию

Сначала узнайте, что уже есть в вашей конфигурации.

# Показать все контексты из текущего kubeconfig
kubectl config get-contexts

Вывод будет похож на таблицу:

CURRENT   NAME                      CLUSTER                   AUTHINFO                  NAMESPACE
*         my-prod-cluster           prod-cluster.example.com  prod-user                 default
          my-dev-cluster            dev-cluster.example.com   dev-user                  staging

Звёздочка (*) в колонке CURRENT указывает на активный в данный момент контекст.

Также полезно посмотреть полный файл конфигурации:

kubectl config view

Этот вывод в формате YAML покажет все кластеры, пользователей (credentials) и контексты.

Шаг 2: Создайте новый контекст

Предположим, у вас уже есть:

• Кластер с именем staging-cluster (уже добавлен в config).
• Пользователь (auth info) с именем admin-staging (уже добавлен).

Теперь создадим контекст staging-admin, который по умолчанию будет использовать пространство имён monitoring:

kubectl config set-context staging-admin \
  --cluster=staging-cluster \
  --user=admin-staging \
  --namespace=monitoring

Что делает эта команда:

• set-context — операция создания/обновления контекста.
• staging-admin — имя нового контекста.
• --cluster, --user — ссылаются на уже существующие записи в kubeconfig.
• --namespace — устанавливает пространство имён по умолчанию для этого контекста (необязательный параметр).

💡 Совет: Если вы хотите, чтобы контекст не имел пространства имён по умолчанию, просто не используйте флаг --namespace. Тогда будет использоваться default.

Шаг 3: Переключитесь на новый контекст

Теперь сделайте только что созданный контекст активным:

kubectl config use-context staging-admin

После этого все последующие команды kubectl (например, kubectl get pods) будут выполняться против кластера staging-cluster с пользователем admin-staging и в namespace monitoring.

Шаг 4: Проверьте результат

1. Убедитесь, что контекст изменился:

kubectl config current-context

Вывод должен быть: staging-admin

2. Сделайте тестовый запрос к API кластера:

kubectl get nodes

Если вы видите список нод вашего staging-cluster — контекст работает корректно.

3. Проверьте, что пространство имён по умолчанию установлено:

kubectl get pods

Команда покажет поды только из namespace monitoring (если они там есть).

Шаг 5: (Опционально) Удалите ненужный контекст

Если контекст больше не нужен, удалите его из конфигурации:

kubectl config delete-context staging-admin

⚠️ Важно: Эта команда удаляет только запись о контексте, но не удаляет сами записи о кластере (clusters.staging-cluster) и пользователе (users.admin-staging) из файла kubeconfig. Они останутся и могут использоваться в других контекстах.

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

Критерии успешной настройки:

1. kubectl config current-context возвращает имя вашего нового контекста.
2. Команды kubectl get ... взаимодействуют с правильным кластером.
3. (Если задан namespace) kubectl get pods показывает ресурсы только в указанном пространстве имён.
4. Файл ~/.kube/config содержит новую секцию contexts: с вашими параметрами.

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

Ошибка: error: no context exists with name ...

Причина: Контекст с таким именем не найден в конфигурации. Решение: Проверьте имя через kubectl config get-contexts и используйте точное написание.

Ошибка: Unable to connect to the server: dial tcp ...: i/o timeout

Причина: Контекст указывает на неверный кластер или кластер недоступен. Решение: Проверьте, что в --cluster указано правильное имя кластера из kubectl config get-clusters. Убедитесь, что у вас есть сетевой доступ к API-серверу кластера.

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

Причина: Контекст использует пользователя (auth info), у которого нет прав или отсутствуют корректные credentials. Решение: Проверьте, что пользователь (--user) существует в конфиге и что для него заданы правильные токены/certificates. Возможно, нужно обновить kubeconfig через aws eks update-kubeconfig или аналогичный инструмент.

Контекст переключился, но команды всё равно идут на старый кластер

Причина: В команде явно указан флаг --context или переменная окружения KUBECONTEXT. Решение: Убедитесь, что вы не переопределяете контекст в самой команде или в алиасах/скриптах.

Пространство имён по умолчанию не применяется

Причина: Контекст был создан без флага --namespace, или в команде явно указан --namespace. Решение: Пересоздайте контекст с нужным namespace или явно указывайте namespace в каждой команде: kubectl get pods -n monitoring.

Дополнительные возможности

Использование нескольких файлов kubeconfig

Вы можете объединять конфигурации из разных файлов:

export KUBECONFIG=~/.kube/config:~/.kube/eks-config
kubectl config view --flatten > merged-config

Это удобно, если у вас отдельные конфиги для EKS, GKE и on-premise кластеров.

Установка контекста для конкретного namespace без создания нового контекста

Если вам нужно разово выполнить команду в другом namespace, не меняя контекст, используйте:

kubectl get pods -n <namespace>

Но для частого переключения между разными проектами в одном кластере всё же удобнее создать отдельные контексты с разными --namespace.