Настройте контекст Kubernetes для kubectl: пошаговое руководство за 5 минут

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

Контексты Kubernetes позволяют управлять несколькими кластерами, узлами аутентификации и namespace из единой конфигурации kubeconfig. Без них kubectl будет использовать первый определённый кластер, что быстро приводит к ошибкам «нет доступа» или «несоответствие сервера». После выполнения этого гайда у вас будет рабочий набор команд для создания, переключения, проверки и удаления контекстов — всё за несколько минут.

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

• Операционная система: Linux (Ubuntu 22.04, Debian 12 и т.д.)
• Инструменты: kubectl версии 1.28+ и клиент kubeconfig (входит в состав Kubernetes‑client)
• Доступ: Права на чтение/запись в ~/.kube/config (обычно требуется root или sudo для безопасного редактирования)
• Необязательно: Сертификат CA кластера, токен или PEM‑файл для аутентификации

💡 Совет: Храните sensitive данные (токены, приватные ключи) в ~/.kube/secrets и ссылаться на них через env-file или mount, если используете контейнеризованный CI.

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

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

Сначала определите кластер (адрес сервера и CA), затем пользователя (метод аутентификации) и, наконец, контекст (связка кластера и пользователя).

# Определите кластер
kubectl config set-cluster production \
  --server=https://k8s.example.com \
  --certificate-authority=~/.kube/ca.pem \
  --embed-certs=true

# Определите пользователя (токен для простоты)
kubectl config set-user production-user \
  --token=ABC123DEF456

# Создайте контекст, связывающий кластер и пользователя
kubectl config set-context production \
  --cluster=production \
  --user=production-user

Команды выше добавляют записи в ~/.kube/config. Если файл не существует, kubectl создаст его автоматически.

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

После создания контекста активируйте его, чтобы последующие команды применялись к кластеру production.

kubectl config use-context production

Шаг 3: Проверьте текущий контекст

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

kubectl config current-context
# Выведет: production

Для просмотра всех определённых контекстов:

kubectl config get-contexts

Шаг 4: Измените параметры существующего контекста

Если вам нужно изменить базовый кластер или пользователя, используйте set-context. Изменения вступают в силу сразу после следующего use-context.

kubectl config set-context production --cluster=staging --user=staging-user

Шаг 5: Удалите ненужные контексты

Для очистки конфигурации удалите неиспользуемые определения:

kubectl config unset contexts.production

Если кластер production больше не используется ни одним контекстом, он также будет удалён автоматически.

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

1. Выполните безопасную команду: kubectl get nodes --server=https://k8s.example.com. Она должна вернуть список узлов в кластере production.
2. Убедитесь в namespace по умолчанию: kubectl get ns вернёт namespace, настроенный в контексте (или default, если не указан).
3. Проверьте файл конфигурации: откройте ~/.kube/config и убедитесь, что блок [contexts], [clusters] и [users] содержит созданные записи.

Если любая команда завершается с ошибкой, вернитесь к шагам создания контекста и проверьте права доступа и токены.

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

• Контекст не найден: Проверьте список с помощью kubectl config get-contexts. Имена чувствительны к регистру.
• Ошибка аутентификации: Убедитесь, что токен или сертификат действителен и соответствует определённому пользователю.
• Конфликт кластеров: Если вы пытаетесь определить кластер с тем же именем, что уже существует, сначала удалите старое определение: kubectl config unset clusters.old.
• Нет доступа к файлу: Если ~/.kube/config защищён, используйте sudoedit ~/.kube/config или выполните команду с sudo.

Эти советы помогут избежать типичных ошибок и сохранят вашу конфигурацию чистой.