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

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

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

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

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

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

Синтаксис

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

kubectl [command] [TYPE] [NAME] [flags]

де command, TYPE, NAME та flags визначаються так:

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

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

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

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

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

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

    • Щоб групувати ресурси, якщо всі вони одного типу: TYPE1 name1 name2 name<#>.
      Приклад: kubectl get pod example-pod1 example-pod2.

    • Щоб вказати кілька типів ресурсів окремо: TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>.
      Приклад: kubectl get pod/example-pod1 replicationcontroller/example-rc1.

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

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

• flags: Вказує необовʼязкові прапорці. Наприклад, ви можете використовувати прапорці -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 знаходить простір імен цього ServiceAccount (це такий самий простір імен, що й у 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 [command] [TYPE] [NAME] -o <output_format>

Залежно від операції 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

Файл шаблону:

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 [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

Приклад

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

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

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

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

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

# Створити Service, використовуючи визначення у файлі 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>

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

# Показати всі DaemonSet у форматі звичайного тексту.
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ʼи та Service із міткою '<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
  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/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
  • довідник аргументів командного рядка
• Дізнайтеся про домовленості використання kubectl
• Ознайомтеся з підтримкою JSONPath у kubectl
• Дізнайтеся, як розширювати kubectl за допомогою втулків
  • Для отримання додаткової інформації про втулки, подивіться приклад CLI-втулка.