kubectl-shturval-plugin

О модуле

В платформе “Штурвал” есть модуль kubectl-shturval-plugin, который позволяет получать доступ к кластерам из интерфейса командной строки.

kubectl-shturval-plugin:

  • проходит аутентификацию в платформе;
  • загружает kubeconfig одного кластера или всех кластеров, доступных пользователю;
  • позволяет сохранить параметры подключения в kubectl-shturval-plugin.yaml, чтобы не вводить их заново при каждом входе.

Когда kubeconfig загружен, вы можете использовать kubectl для работы с кластером.

Какие сценарии поддерживаются

Сценарий Что используется Когда подходит
С config из GUI kubectl-shturval-plugin.yaml, скачанный из GUI GUI доступен и не хочется вводить параметры вручную
С config из CLI kubectl-shturval-plugin.yaml, сформированный командой kubectl shturval login genconfig GUI недоступен, но параметры подключения известны
Без config Команда kubectl shturval login с параметрами Нужен разовый вход без сохранения YAML-файла

Что такое kubectl-shturval-plugin.yaml

kubectl-shturval-plugin.yaml - это конфигурационный файл с параметрами подключения к платформе. Его можно получить двумя способами:

  1. Сформировать в CLI командой kubectl shturval login genconfig;
  2. Скачать из графического интерфейса платформы.

Если значения уже сохранены в этом файле, команда kubectl shturval login может использовать их повторно. При этом параметры, переданные в самой команде kubectl shturval login, имеют приоритет над значениями в YAML-файле (kubectl-shturval-plugin.yaml) и не перезаписывают его.

Что скачать

Если платформа развернута в закрытом окружении, вместо публичной ссылки используйте адрес вашего зеркала для kubectl-shturval.

Установка и команды

Перед началом работы установите kubectl-shturval-plugin рядом с kubectl. После установки плагин становится доступен как подкоманда kubectl shturval ....

Шаг 1. Найдите, где расположен kubectl

    Найдите исполняемый файл kubectl:

    which kubectl

    Найдите kubectl.exe:

    Get-ChildItem -Path C:\\ \"kubectl.exe\" -Recurse -Force -ErrorAction SilentlyContinue

    Шаг 2. Положите плагин в ту же директорию, что и kubectl

    Если загруженный файл называется иначе, переименуйте его в kubectl-shturval (для Linux) или kubectl-shturval.exe (для Windows) при перемещении.

      Скопируйте файл в директорию рядом с kubectl и выдайте права на выполнение:

      sudo cp ВВЕДИТЕ-ПУТЬ-ДО-ЗАГРУЖЕННОГО-kubectl-shturval-version ВВЕДИТЕ-ДИРЕКТОРИЮ-ГДЕ-РАСПОЛАГАЕТСЯ-kubectl-shturval && sudo chmod +x ВВЕДИТЕ-ДИРЕКТОРИЮ-ГДЕ-РАСПОЛАГАЕТСЯ-kubectl-shturval

      Скопируйте kubectl-shturval.exe в директорию, где расположен kubectl.exe:

      cp ВВЕДИТЕ-ПУТЬ-ДО-ЗАГРУЖЕННОГО-kubectl-shturval.exe ВВЕДИТЕ-ДИРЕКТОРИЮ-ГДЕ-РАСПОЛАГАЕТСЯ-kubectl.exe

      Шаг 3. Проверьте, что файл лежит рядом с kubectl

        Проверьте, что в директории есть kubectl-shturval:

        ls ВВЕДИТЕ-ДИРЕКТОРИЮ-ГДЕ-РАСПОЛАГАЕТСЯ-kubectl | grep kubectl-shturval

        Проверьте, что в директории есть kubectl-shturval.exe:

        Test-Path -PathType Leaf -Path 'ВВЕДИТЕ-ДИРЕКТОРИЮ-ГДЕ-РАСПОЛАГАЕТСЯ-kubectl.exe\\kubectl-shturval.exe'

        Основные команды

        Команда Что делает Когда использовать
        kubectl shturval login Проходит аутентификацию в платформе и загружает kubeconfig одного или нескольких доступных пользователю кластеров Когда нужно сразу получить доступ к кластерам
        kubectl shturval login genconfig Формирует kubectl-shturval-plugin.yaml с параметрами подключения Когда нужно сохранить параметры подключения и использовать их повторно

        Справка по команде

        Чтобы посмотреть встроенную справку, выполните:

        kubectl shturval login -h

          Сценарий использования с config из GUI

          Этот сценарий подходит, если у вас есть доступ к графическому интерфейсу платформы и вы хотите использовать kubectl-shturval-plugin, не вводя параметры подключения вручную в консоли.

          Какой файл можно скачать из GUI

          Сценарий Где скачать Что получится после выполнения команды kubectl shturval login с использованием данных из конфигурационного файла
          Один кластер В интерфейсе конкретного кластера clustername.conf в директории, где выполняются команды, с kubeconfig одного кластера
          Все доступные кластеры На главной странице платформы all-clusters.conf в директории, где выполняются команды, с kubeconfigs доступных кластеров

          Общий порядок работы

          1. Скачайте kubectl-shturval-plugin.yaml из GUI.
          2. Поместите файл в домашний каталог пользователя. В примерах для Linux используется домашний каталог /root.
          3. Выполните kubectl shturval login.
          4. Используйте полученный kubeconfig напрямую или переместите его в ~/.kube/config.

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

          Доступ к одному кластеру

          1. В графическом интерфейсе кластера нажмите стрелку справа от имени пользователя.
          2. Выберите Скачать config для kubectl-shturval-plugin.
          3. Дождитесь загрузки файла (см. скриншот ниже).
          Скачивание config для kubectl-shturval-plugin из GUI кластера

          Меню скачивания config рядом с именем пользователя в GUI кластера Диалог сохранения файла kubectl-shturval-plugin.yaml

          Пример конфигурационного файла 

          auth-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link
client-id: backend
client-secret: qz86fkqkb
cacert: |
  -----BEGIN CERTIFICATE-----
  MIIC+TCCAoCgAwIBAgINAKaLeSkAAAAAUNCR+TAKBggqhkjOPQQDAzCBvzELMAkG
  A1UEBhMCVVMxFjAUBgNpFQUWw==
  -----END CERTIFICATE-----  
username: username
cluster-name: clustername
kubeConfig: clustername.conf
server-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link

          В этом варианте плагин загружает kubeconfig кластера в директорию, где выполняются команды и сохраняет его с именем, соответствующим кластеру.

          Дальнейшие шаги

          1. Перейдите в интерфейс командной строки и поместите полученный конфигурационный файл в директорию домашнего каталога пользователя (например, для Linux - /root).
          2. Выполните команду для загрузки kubeconfig кластера. Пароль вашей учетной записи будет запрошен в интерактивном режиме. После выполнения команды kubeconfig будет загружен в директорию, где выполнялись команды, и сохранен с именем, соответствующим названию кластера.
          3. Переместите kubeconfig кластера в папку ~/.kube и переименуйте файл в config.
          mv ВВЕДИТЕ-ПУТЬ-ДО-ЗАГРУЖЕННОГО-kubectl-shturval-plugin.yaml ПАПКА-ДОМАШНЕГО-КАТАЛОГА-ПОЛЬЗОВАТЕЛЯ/kubectl-shturval-plugin.yaml
kubectl shturval login
mv ВВЕДИТЕ-ПУТЬ-ДО-clustername.conf ~/.kube/config

          После этого вы можете использовать kubectl для работы с кластером.

          Доступ ко всем доступным пользователю кластерам

          1. На главной странице платформы нажмите стрелку справа от имени пользователя.
          2. Выберите Скачать config kubectl-shturval-plugin для всех кластеров.
          3. Дождитесь загрузки файла kubectl-shturval-plugin.yaml (см. скриншот ниже).
          Скачивание config kubectl-shturval-plugin для всех кластеров с главной страницы платформы

          Меню скачивания config для всех кластеров на главной странице платформы Диалог сохранения kubectl-shturval-plugin.yaml для всех кластеров

          Пример конфигурационного файла 

          auth-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link
client-id: backend
client-secret: qz86fkqkb
cacert: |
  -----BEGIN CERTIFICATE-----
  MIIC+TCCAoCgAwIBAgINAKaLeSkAAAAAUNCR+TAKBggqhkjOPQQDAzCBvzELMAkG
  A1UEBhMCVVMxFjAUBgNpFQUWw==
  -----END CERTIFICATE-----  
username: username
kubeConfig: all-clusters.conf
server-url: shturval.clustername.ip-XX-XX-XX-XX.shturval.link

          Kubeconfigs доступных кластеров будут загружены в файл all-clusters.conf в директории, где выполняются команды.

          Дальнейшие шаги

          1. Перейдите в интерфейс командной строки и поместите полученный конфигурационный файл в директорию домашнего каталога пользователя (например, для Linux - /root).
          2. Выполните команду для загрузки kubeconfigs кластеров. Пароль вашей учетной записи будет запрошен в интерактивном режиме.
          3. Переместите kubeconfigs кластеров в папку ~/.kube и переименуйте файл в config.
          mv ВВЕДИТЕ-ПУТЬ-ДО-ЗАГРУЖЕННОГО-kubectl-shturval-plugin.yaml ПАПКА-ДОМАШНЕГО-КАТАЛОГА-ПОЛЬЗОВАТЕЛЯ/kubectl-shturval-plugin.yaml
kubectl shturval login
mv ВВЕДИТЕ-ПУТЬ-ДО-all-clusters.conf ~/.kube/config

          Типовые ошибки доступа - если не удается получить доступ к кластеру или кластерам.

          Сценарий использования с config из CLI

          Этот сценарий подходит, если графический интерфейс недоступен, но параметры подключения уже известны и вы хотите сохранить их в kubectl-shturval-plugin.yaml для повторного использования.

          Что понадобится

          Параметр Когда нужен Что означает
          -s, --server-url Обычно нужен URL shturval-backend сервера
          -u, --username Обычно нужен Имя пользователя для подключения к серверу shturval-backend
          -p, --password Опционально Пароль для подключения к серверу shturval-backend. Если пароль содержит специальные символы ($,<, >, *, &, ?, /,\ ), необходимо их экранировать с помощью одинарных кавычек. Например, --password='my$Password?'
          --client-secret Нужен для аутентификации Secret клиента для внешнего сервиса аутентификации
          --client-id Опционально Идентификатор клиента для внешнего сервиса аутентификации. По умолчанию: backend
          --auth-url Опционально URL-адрес сервера аутентификации
          --cacert Опционально Содержимое корневого доверенного сертификата
          --cacert-file Опционально Путь до корневого доверенного сертификата
          -n, --cluster-name Опционально Имя кластера для получения kubeconfig одного кластера. Не указывается, если необходимо получить kubeconfigs всех доступных кластеров
          --config-path Опционально Путь до расположения конфигурационного файла kubectl-shturval-plugin.yaml. По умолчанию для Linux: /root
          -i, --insecure Опционально Признак проверки безопасности TLS соединения
          -k, --kubeconfig Опционально Путь расположения загруженных kubeconfigs. По умолчанию для Linux: /root/.kube/config
          --ttl Опционально Время жизни токена. По умолчанию 24h

          client-secret получите из ключа backend секрета backend-* в неймспейсе shturval-backend кластера управления. Если у вас нет доступа к этому секрету, запросите значение ключа backend у администратора платформы.

          Общая схема работы

          1. Сгенерируйте kubectl-shturval-plugin.yaml командой kubectl shturval login genconfig.
          2. Проверьте содержимое файла.
          3. Выполните kubectl shturval login, чтобы получить kubeconfig.
          4. Используйте загруженный kubeconfig для работы с кластером через kubectl.

          Шаг 1. Сгенерируйте конфигурационный файл

          Минимальный пример 

          kubectl shturval login genconfig --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --insecure=true --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ

          Файл kubectl-shturval-plugin.yaml создается в домашнем каталоге пользователя. В примерах для Linux используется каталог /root.

          Если нужно сохранить файл в другой директории и выполнить аутентификацию без проверки TLS соединения 

          kubectl shturval login genconfig --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ' --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --insecure=true --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ --config-path=ВВЕДИТЕ-ПУТЬ-ДО-РАСПОЛОЖЕНИЯ-КОНФИГУРАЦИОННОГО-ФАЙЛА

          Шаг 2. Проверьте, что файл создан 

          cat ВВЕДИТЕ-ПУТЬ-ДО-kubectl-shturval-plugin.yaml

          Шаг 3. Выполните вход и загрузите kubeconfig

          Когда конфигурационный файл готов, запустите:

          kubectl shturval login

          Если нужно переопределить параметры на один запуск

          Параметры, переданные в kubectl shturval login, имеют приоритет перед такими же значениями в kubectl-shturval-plugin.yaml. При этом сам конфигурационный файл не перезаписывается.

          Например, можно выполнить вход от другой учетной записи:

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ'

          Что получится на выходе

          • если в конфигурации задан один кластер, будет загружен kubeconfig этого кластера;
          • если cluster-name не указан, будут загружены kubeconfigs всех доступных кластеров;
          • путь к итоговому kubeconfig можно задать через --kubeconfig.

          Типовые ошибки доступа - если не удается получить доступ к кластеру или кластерам.

          Сценарий использования без config

          Этот сценарий подходит, если вам нужен прямой вход через kubectl shturval login без сохранения kubectl-shturval-plugin.yaml.

          Что понадобится заранее

          • server-url сервера shturval-backend;
          • имя пользователя и пароль;
          • client-secret для сервиса аутентификации;
          • при необходимости cluster-name, параметры сервиса аутентификации и TLS.

          В --client-secret указывается значение ключа backend секрета backend-*. Он находится в неймспейсе shturval-backend кластера управления. Если у вас нет доступа к секрету, запросите данные у администратора платформы.

          Параметры команды kubectl shturval login

          Параметр Обязательность Назначение
          --auth-url [string] Нет URL сервера аутентификации
          --cacert [string] Нет Содержимое корневого доверенного сертификата
          --cacert-file [string] Нет Путь к корневому доверенному сертификату
          --client-id [string] Нет Идентификатор клиента для сервиса аутентификации. По умолчанию backend
          --client-secret [string] Да Secret клиента для сервиса аутентификации
          -n, --cluster-name [string] Нет Имя одного кластера. Если параметр не указан, загружаются kubeconfigs всех доступных кластеров
          --config-path [string] Нет Путь к kubectl-shturval-plugin.yaml, если он все же используется
          -i, --insecure Нет Признак проверки безопасности TLS-соединения
          -k, --kubeconfig [string] Нет Путь, куда будет загружен kubeconfig. По умолчанию для Linux /root/.kube/config
          -p, --password [string] Нет Пароль пользователя. Если пароль содержит специальные символы ($,<, >, *, &, ?, /,\ ), используйте одинарные кавычки. Например, --password='my$Password?'
          -s, --server-url [string] Да URL сервера shturval-backend
          --ttl [string] Нет Время жизни токена. По умолчанию 24 часа
          -u, --username [string] Да Имя пользователя для подключения к shturval-backend
          -v, --version Нет Версия команды login

          Если параметр --password не передан, пароль будет запрошен в интерактивном режиме.

          Интерактивный запрос пароля при выполнении kubectl shturval login

          Окно ввода пароля при входе через kubectl shturval login

          Минимальный сценарий

          Если нужен доступ ко всем доступным кластерам без проверки TLS, можно начать с такой команды:

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --insecure=true --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ

          Примеры

          Все доступные кластеры с включенной проверкой безопасности TLS соединения (задан корневой сертификат) 

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ' --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ --cacert=-----BEGIN CERTIFICATE-----Содержимое в Base64-----END CERTIFICATE-----

          Все доступные кластеры с включенной проверкой безопасности TLS соединения (задан корневой сертификат из файла) 

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ' --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ --cacert-file=ВВЕДИТЕ-ПУТЬ-ДО-КОРНЕВОГО-ДОВЕРЕННОГО-СЕРТИФИКАТА

          Все доступные кластеры с указанием пути загрузки для kubeconfig 

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ' --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --insecure=true --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ --kubeconfig=ВВЕДИТЕ-ПУТЬ-ДЛЯ-ЗАГРУЗКИ-kubeconfig

          Один кластер с обязательными параметрами аутентификации без проверки TLS 

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ' --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ --cluster-name=myclustername --insecure=true

          Один кластер с обязательными параметрами аутентификации и проверкой TLS 

          kubectl shturval login --username=ВВЕДИТЕ-ИМЯ-ПОЛЬЗОВАТЕЛЯ-ДЛЯ-ПОДКЛЮЧЕНИЯ --password='ВВЕДИТЕ-ПАРОЛЬ-ПОЛЬЗОВАТЕЛЯ' --server-url=ВВЕДИТЕ-URL-shturval-backend-СЕРВЕРА --client-secret=ВВЕДИТЕ-Secret-КЛИЕНТА-СЕРВИСА-АУТЕНТИФИКАЦИИ --cluster-name=ВВЕДИТЕ-ИМЯ-КЛАСТЕРА --cacert-file=ВВЕДИТЕ-ПУТЬ-ДО-КОРНЕВОГО-ДОВЕРЕННОГО-СЕРТИФИКАТА

          Типовые ошибки доступа - если не удается получить доступ к кластеру или кластерам.

          ← Получение kubeconfig кластера
          Типовые ошибки доступа →