Інструмент командного рядка (kubectl)

Kubernetes надає інструмент командного рядка для взаємодії із кластером Kubernetes, панеллю управління, використовуючи API Kubernetes.

Цей інструмент має назву kubectl.

Для отримання налаштувань kubectl шукає файл config в теці $HOME/.kube. Ви можете вказати інший файл kubeconfig у змінній оточення KUBECONFIG або у значенні ключа --kubeconfig.

Тут ми розглянемо синтаксис команд kubectl, опис операторів та розберемо їх на прикладах. Докладніше про кожну команду, включаючи всі підтримувані прапорці та підкоманди, див. довідкову документацію kubectl.

Інструкції з встановлення знаходяться у статті Встановлення kubectl; короткий посібник є у шпаргалці. Якщо ви звикли користуватись інструмент командного рядка docker, kubectl для користувачів Docker пояснює деякі еквівалентні команди для Kubernetes.

Синтаксис

Використовуйте наступний синтаксис для виконання команд kubectl у вашому терміналі:

kubectl [команда] [ТИП] [ІМʼЯ] [прапорці]

де команда, ТИП, ІМʼЯ та прапорці визначаються наступним чином:

• команда: Вказує операцію, яку ви хочете виконати з одним чи кількома ресурсами, наприклад create, get, describe, delete.

• ТИП: Вказує тип ресурсу. Типи ресурсів нечутливі до регістру, і можна вказувати форми однини, множини чи абревіатури. Наприклад, наступні команди виводять той самий результат:

  kubectl get pod pod1
  kubectl get pods pod1
  kubectl get po pod1
  

• ІМʼЯ: Вказує імʼя ресурсу. Імена чутливі до регістру. Якщо імʼя відсутнє, виводяться деталі для всіх ресурсів, наприклад kubectl get pods.

  При виконанні операції над кількома ресурсами можна вказати кожен ресурс за типом та іменем або вказати один чи кілька файлів:

  • Щоб вказати ресурси за типом та іменем:

    • Щоб групувати ресурси, якщо вони всі є тим самим типом: ТИП1 імʼя1 імʼя2 імʼя<#>.
      Приклад: kubectl get pod example-pod1 example-pod2.

    • Щоб вказати кілька типів ресурсів окремо: ТИП1/імʼя1 ТИП1/імʼя2 ТИП2/імʼя3 ТИП<#>/імʼя<#>.
      Приклад: kubectl get pod/example-pod1 replicationcontroller/example-rc1.

  • Щоб вказати ресурси за допомогою одного чи кількох файлів: -f файл1 -f файл2 -f файл<#>.

    • Використовуйте YAML замість JSON, оскільки YAML зазвичай є зручнішим для користувача, особливо для файлів конфігурації.
      Приклад: kubectl get -f ./pod.yaml

• прапорці: Є необовʼязковими. Наприклад, ви можете використовувати прапорці -s або --server, щоб вказати адресу та порт сервера API Kubernetes.

Якщо вам потрібна допомога, виконайте команду kubectl help у вікні термінала.

Автентифікація та перевизначення простору імен в кластері

Типово kubectl спочатку визначатиме, чи він виконується в середині Podʼа, і отже, в кластері. Програма починає з перевірки наявності змінних середовища KUBERNETES_SERVICE_HOST та KUBERNETES_SERVICE_PORT, а також наявності файлу токена облікового запису служби за шляхом /var/run/secrets/kubernetes.io/serviceaccount/token. Якщо всі три умови виконуються, вважається, що використовується автентифікація в кластері.

Для забезпечення зворотної сумісності, якщо під час автентифікації в кластері встановлено змінну середовища POD_NAMESPACE, вона перевизначить типовий простір імен скориставшись токеном облікового запису служби. Це буде впливати на будь-які маніфести або інструменти, які покладаються на типовий простір імен.

Змінна середовища POD_NAMESPACE

Якщо змінна середовища POD_NAMESPACE встановлена, операції CLI для ресурсів з обмеженим простором імен будуть отримувати типове значення від цієї змінної. Наприклад, якщо змінна встановлена в seattle, kubectl get pods поверне Podʼи з простору імен seattle. Це тому, що Podʼи є ресурсом з обмеженим простором імен, і ми не вказали команді простір імен в командному рядку. Ознайомтесь з виводом kubectl api-resources, щоб визначити, чи ресурс має обмежений простір імен чи ні.

Явне використання --namespace <value> перевизначає цю поведінку.

Як kubectl обробляє токени ServiceAccount

Якщо:

• маємо файл токена облікового запису служби Kubernetes, змонтований за шляхом /var/run/secrets/kubernetes.io/serviceaccount/token, і
• встановлено змінну середовища KUBERNETES_SERVICE_HOST, і
• встановлено змінну середовища KUBERNETES_SERVICE_PORT, і
• ви не вказуєте простір імен явно в командному рядку kubectl

тоді kubectl вважатиме, що він працює в вашому кластері. Інструмент kubectl знаходить простір імен цього облікового запису служби (це такий самий простір імен, що й у Podʼа) та діє відповідно до цього простору імен. Це відрізняється від того, що відбувається поза кластером; коли kubectl працює за межами кластера і ви не вказуєте простір імен, команда kubectl діє в просторі імен, встановленому для поточного контексту у вашій конфігурації клієнта. Щоб змінити типовий простір імен для kubectl, ви можете використовувати наступну команду:

kubectl config set-context --current --namespace=<namespace-name>

Операції

Наступна таблиця містить короткі описи та загальний синтаксис для всіх операцій kubectl:

Щоб дізнатися більше про операції, що виконують команди, див. довідку kubectl.

Типи ресурсів

У наступній таблиці наведено список всіх підтримуваних типів ресурсів та їх скорочених аліасів.

(Цей вивід можна отримати за допомогою kubectl api-resources і був актуальним на момент Kubernetes 1.25.0)

Параметри виводу

Використовуйте наступні розділи для отримання інформації про те, як ви можете форматувати або сортувати вивід деяких команд. Докладні відомості щодо команд, які підтримують різні параметри виводу, див. в документації по kubectl.

Форматування виводу

Стандартний формат виводу для всіх команд kubectl – це читабельний текстовий формат. Щоб вивести деталі у вашому терміналі у певному форматі, ви можете додати параметр -o або --output до підтримуваної команди kubectl.

Синтаксис

kubectl [команда] [ТИП] [ІМʼЯ] -o <формат_виводу>

Залежно від операції kubectl, підтримуються наступні формати виводу:

Приклад

Тут наступна команда виводить інформацію про Pod у форматі YAML:

kubectl get pod web-pod-13je7 -o yaml

Нагадування: Дивіться довідку kubectl для отримання деталей щодо підтримуваних форматів виводу для кожної команди.

Власні стовпці

Щоб визначити власні стовпці та виводити лише ті деталі, які вам потрібні у вигляді таблиці, ви можете використовувати опцію custom-columns. Ви можете вибрати визначення спеціальних стовпців під час складення параметрів команди або використовувати файл шаблону: -o custom-columns=<spec> або -o custom-columns-file=<filename>.

Приклади

З використанням параметрів в командному рядку:

kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

З використанням файлу шаблону template.txt:

kubectl get pods <pod-name> -o custom-columns-file=template.txt

де template.txt містить:

NAME          RSRC
metadata.name metadata.resourceVersion

Результати виводу будуть виглядати як для використання шаблону, так і для параметрів командного рядка, як:

NAME           RSRC
submit-queue   610995

Стовпці на стороні сервера

kubectl підтримує отримання конкретної інформації в стовпці щодо обʼєктів від сервера. Це означає, що для будь-якого заданого ресурсу сервер поверне стовпці та рядки, що стосуються цього ресурсу, для показу його клієнту. Це дозволяє отримати послідовний, зручний для читання вивід для різних клієнтів, які використовуються для одного і того ж кластера, оскільки сервер ізолює деталі виведення.

Ця функція стандартно увімкнена. Щоб вимкнути її, додайте прапорець --server-print=false до команди kubectl get.

Приклади

Щоб вивести інформацію про стан Podʼа, використовуйте команду на зразок наступної:

kubectl get pods <pod-name> --server-print=false

Вивід буде подібний до:

NAME       AGE
pod-name   1m

Сортування списку обʼєктів

Щоб вивести обʼєкти в відсортованому списку у вашому вікні термінала, ви можете додати прапорець --sort-by до команди kubectl. Впорядкуйте ваші обʼєкти, вказавши будь-яке числове чи рядкове поле з прапорцем --sort-by. Для вказання поля використовуйте вираз jsonpath.

Синтаксис

kubectl [команда] [ТИП] [ІМ'Я] --sort-by=<вираз_jsonpath>

Приклад

Щоб вивести список Podʼів, відсортованих за назвами, зробіть наступне:

kubectl get pods --sort-by=.metadata.name

Приклади: Загальні операції

Використовуйте цей набір прикладів, щоб ознайомитися з тим, як використовувати найпоширеніші операції kubectl:

kubectl apply — Застосувати або оновити ресурс із файлу чи stdin.

# Створити службу, використовуючи визначення у файлі example-service.yaml.
kubectl apply -f example-service.yaml

# Створити контролер реплікації, використовуючи визначення у файлі example-controller.yaml.
kubectl apply -f example-controller.yaml

# Створити обʼєкти, які визначені у файлах з розширеннями .yaml, .yml, або .json у теці <directory>.
kubectl apply -f <directory>

kubectl get — Показати відомості про один чи кілька ресурсів.

# Показати всі Podʼі у форматі звичайного тексту.
kubectl get pods

# Показати всі Podʼі у форматі звичайного тексту та додаткову інформацію (наприклад, імʼя вузла).
kubectl get pods -o wide

# Показати контролер реплікації із вказаним імʼям у форматі звичайного тексту. Порада: Ви можете скоротити та замінити тип ресурсу 'replicationcontroller' на скорочену назву 'rc'.
kubectl get replicationcontroller <rc-name>

# Показати всі контролери реплікації та служби разом у форматі звичайного тексту.
kubectl get rc,services

# Показати всі daemonsets у форматі звичайного тексту.
kubectl get ds

# Показати всі Podʼи, які працюють на вузлі server01
kubectl get pods --field-selector=spec.nodeName=server01

kubectl describe — Показати детальний стан одного чи кількох ресурсів, включаючи ті, які ще не ініціалізовані.

# Показати деталі вузла із ім'ям <node-name>.
kubectl describe nodes <node-name>

# Показати деталі Podʼу із ім'ям <pod-name>.
kubectl describe pods/<pod-name>

# Показати деталі всіх Podʼів, які керуються контролером реплікації із вказаним ім'ям <rc-name>.
# Памʼятайте: Будь-які Podʼи, які створює контролер реплікації, отримують префікс із імʼям контролера реплікації.
kubectl describe pods <rc-name>

# Показати всі Podʼи
kubectl describe pods

kubectl delete — Видалити ресурси або з використанням файлу, або з stdin, або вказавши селектори міток, імена, селектори ресурсів чи самі ресурси.

# Видалити Pod, використовуючи тип та імʼя, вказане у файлі pod.yaml.
kubectl delete -f pod.yaml

# Видалити всі Podʼи та служби із міткою '<label-key>=<label-value>'.
kubectl delete pods,services -l <label-key>=<label-value>

# Видалити всі Podʼи, включаючи неініціалізовані.
kubectl delete pods --all

kubectl exec — Виконати команду у контейнері Podʼу.

# Отримати вивід виконання команди 'date' у Podʼі <pod-name>. Типово вивід виконується з першого контейнера.
kubectl exec <pod-name> -- date

# Отримати вивід виконання команди 'date' у контейнері <container-name> Podʼу <pod-name>.
kubectl exec <pod-name> -c <container-name> -- date

# Отримати інтерактивний TTY та виконати /bin/bash у Podʼі <pod-name>. Типово вивід виконується з першого контейнера.
kubectl exec -ti <pod-name> -- /bin/bash

kubectl logs — Вивести логи для контейнера у Podʼі.

# Отримати логи із Podʼу <pod-name>.
kubectl logs <pod-name>

# Почати виведення логів у режимі стрічки із Podʼу <pod-name>. Це схоже на команду 'tail -f' у Linux.
kubectl logs -f <pod-name>

kubectl diff — Переглянути відмінності запропонованих оновлень кластера.

# Відмінності ресурсів, включених у "pod.json".
kubectl diff -f pod.json

# Відмінності, отримані з stdin.
cat service.yaml | kubectl diff -f -

Приклади: Створення та використання втулків

Використовуйте цей набір прикладів, щоб ознайомитися із написанням та використанням втулків kubectl:

# створіть простий втулок будь-якою мовою та зробить файл виконуваним
# так, щоб він починався префіксом "kubectl-"
cat ./kubectl-hello

#!/bin/sh

# цей втулок виводить слова "hello world"
echo "hello world"

Дайте втулку права на виконання:

chmod a+x ./kubectl-hello

# та перемістіть його в місце, яке є у вашому шляху (PATH)
sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin

# Ви зараз створили та "встановили" втулок kubectl.
# Ви можете почати використовувати цей втулок, викликаючи його з kubectl, 
# ніби це звичайна команда
kubectl hello

hello world

# Ви можете "вилучити" втулок, видаливши його з теки у вашому
# $PATH, де ви його розмістили
sudo rm /usr/local/bin/kubectl-hello

Щоб переглянути всі втулки, доступні для kubectl, використовуйте команду kubectl plugin list:

kubectl plugin list

Вивід буде схожий на:

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar

kubectl plugin list також попереджає вас про втулки, які не мають прав на виконання, або які перекриваються з іншими втулками; наприклад:

sudo chmod -x /usr/local/bin/kubectl-foo # вилучити права виконання
kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
  - попередження: /usr/local/bin/kubectl-foo визначено як втулок, але він не є виконавчим
/usr/local/bin/kubectl-bar

error: one plugin warning was found

Ви можете думати про втулки як про можливість будувати більш складні функції на основі наявних команд kubectl:

cat ./kubectl-whoami

Наступні кілька прикладів передбачають, що ви вже зробили так, що kubectl-whoami має наступний вміст:

#!/bin/bash

# цей втулок використовує команду `kubectl config` для виведення
# інформації про поточного користувача, на основі вибраного контексту
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'

Запуск вищезазначеної команди дає вам вивід із зазначенням користувача для поточного контексту у вашому файлі KUBECONFIG:

# зробіть файл виконавчим
sudo chmod +x ./kubectl-whoami

# та перемістіть його у ваш шлях (PATH)
sudo mv ./kubectl-whoami /usr/local/bin

kubectl whoami
Current user: plugins-user

Що далі

• Ознайомтеся з документацією kubectl:
  • довідник команд
  • специфікації аргументів командного рядка в довіднику
• Дізнайтеся про домовленості використання kubectl
• Ознайомтеся з підтримкою JSONPath у kubectl
• Дізнайтеся, як розширювати kubectl за допомогою втулків
  • Для отримання додаткової інформації про втулки, подивіться приклад CLI-втулка.