1 - Декларативне керування обʼєктами Kubernetes за допомогою файлів конфігурації

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

Перш ніж ви розпочнете

Встановіть kubectl.

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Для перевірки версії введіть kubectl version.

Компроміси

Інструмент kubectl підтримує три види керування обʼєктами:

  • Імперативні команди
  • Імперативне конфігурування обʼєктів
  • Декларативна конфігурація обʼєктів

Переваги й недоліки кожного виду керування обʼєктами розглянуто в розділі Управління обʼєктами Kubernetes.

Огляд

Декларативна конфігурація обʼєктів потребує чіткого розуміння визначень і конфігурації обʼєктів Kubernetes. Прочитайте й виконайте наведені нижче документи, якщо ви ще цього не зробили:

Нижче подано визначення термінів, використаних у цьому документі:

  • файл конфігурації обʼєкта / файл конфігурації: файл, який визначає конфігурацію обʼєкта Kubernetes. У цій темі показано, як передавати файли конфігурації до kubectl apply. Файли конфігурації зазвичай зберігаються в системі контролю версій, як-от Git.
  • жива конфігурація обʼєкта / жива конфігурація: живі значення конфігурації обʼєкта, які спостерігає кластер Kubernetes. Вони зберігаються у сховищі кластера Kubernetes, зазвичай etcd.
  • декларативний записувач конфігурації / декларативний записувач: особа або програмний компонент, що вносить оновлення до живого обʼєкта. Живі записувачі, про яких ідеться в цій темі, змінюють файли конфігурації обʼєктів і запускають kubectl apply, щоб записати зміни.

Як створити обʼєкти

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

kubectl apply -f <directory>

Це встановлює анотацію kubectl.kubernetes.io/last-applied-configuration: '{...}' для кожного обʼєкта. Анотація містить вміст файлу конфігурації обʼєкта, який був використаний для створення обʼєкта.

Примітка:

Додайте прапорець -R, щоб рекурсивно обробляти теки.

Ось приклад файлу конфігурації обʼєкта:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Виконайте kubectl diff, щоб вивести обʼєкт, який буде створено:

kubectl diff -f https://k8s.io/examples/application/simple_deployment.yaml

Примітка:

diff використовує запуск без внесення змін на сервері (dry-run), таку можливість потрібно ввімкнути на kube-apiserver.

Оскільки diff виконує запит застосування на стороні сервера в режимі dry-run, для нього потрібно надати дозволи PATCH, CREATE і UPDATE. Докладніше дивіться в розділі Авторизація запуску dry-run.

Створіть обʼєкт за допомогою kubectl apply:

kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml

Виведіть живу конфігурацію за допомогою kubectl get:

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

Вивід показує, що анотація kubectl.kubernetes.io/last-applied-configuration була записана до живої конфігурації та відповідає файлу конфігурації:

kind: Deployment
metadata:
  annotations:
    # ...
    # Це json-представлення simple_deployment.yaml
    # Його записав kubectl apply під час створення обʼєкта
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}
  # ...
spec:
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

Як оновити обʼєкти

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

  1. Встановлює в живій конфігурації поля, що є у файлі конфігурації.
  2. Очищає в живій конфігурації поля, вилучені з файлу конфігурації.
kubectl diff -f <directory>
kubectl apply -f <directory>

Примітка:

Додайте прапорець -R, щоб рекурсивно обробляти теки.

Ось приклад файлу конфігурації:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Створіть обʼєкт за допомогою kubectl apply:

kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml

Примітка:

Для наочності наведена вище команда посилається на один файл конфігурації, а не на теку.

Виведіть живу конфігурацію за допомогою kubectl get:

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

Вивід показує, що анотація kubectl.kubernetes.io/last-applied-configuration була записана до живої конфігурації та відповідає файлу конфігурації:

kind: Deployment
metadata:
  annotations:
    # ...
    # Це json-представлення simple_deployment.yaml
    # Його записав kubectl apply під час створення обʼєкта
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}
  # ...
spec:
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

Оновіть поле replicas безпосередньо в живій конфігурації за допомогою kubectl scale. Тут kubectl apply не використовується:

kubectl scale deployment/nginx-deployment --replicas=2

Виведіть живу конфігурацію за допомогою kubectl get:

kubectl get deployment nginx-deployment -o yaml

Вивід показує, що поле replicas встановлено на 2, і анотація last-applied-configuration не містить поле replicas:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # зверніть увагу, що анотація не містить replicas
    # оскільки це поле не оновлювалося через apply
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}
  # ...
spec:
  replicas: 2 # записано командою scale
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
      # ...

Оновіть файл конфігурації simple_deployment.yaml, щоб змінити образ з nginx:1.14.2 на nginx:1.16.1 та видалити поле minReadySeconds:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1 # update the image
        ports:
        - containerPort: 80

Застосуйте зміни, внесені до файлу конфігурації:

kubectl diff -f https://k8s.io/examples/application/update_deployment.yaml
kubectl apply -f https://k8s.io/examples/application/update_deployment.yaml

Виведіть живу конфігурацію за допомогою kubectl get:

kubectl get -f https://k8s.io/examples/application/update_deployment.yaml -o yaml

Вивід показує такі зміни в живій конфігурації:

  • Поле replicas зберігає значення 2, встановлене kubectl scale. Це можливо, бо воно відсутнє у файлі конфігурації.
  • Поле image оновлено з nginx:1.14.2 до nginx:1.16.1.
  • Анотацію last-applied-configuration оновлено новим образом.
  • Поле minReadySeconds очищено.
  • Анотація last-applied-configuration більше не містить поле minReadySeconds.
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # Анотація містить оновлений образ nginx 1.16.1,
    # але не містить оновлення replicas до 2
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}
    # ...
spec:
  replicas: 2 # Встановлено за допомогою `kubectl scale`. Ігнорується `kubectl apply`.
  # minReadySeconds очищено за допомогою `kubectl apply`
  # ...
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.16.1 # Встановлено за допомогою `kubectl apply`
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

Попередження:

Поєднання kubectl apply з командами імперативної конфігурації обʼєктів create і replace не підтримується. Це тому, що create і replace не зберігають kubectl.kubernetes.io/last-applied-configuration, який kubectl apply використовує для обчислення оновлень.

Як видалити обʼєкти

Існують два підходи до видалення обʼєктів, керованих за допомогою kubectl apply.

Рекомендований підхід — видаляти обʼєкти вручну за допомогою імперативної команди, оскільки так явніше видно, що саме видаляється, і менша ймовірність, що користувач випадково щось видалить:

kubectl delete -f <filename>

Альтернатива: kubectl apply -f <directory> --prune

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

У Kubernetes 1.37 у kubectl apply доступні два режими очищення:

  • Очищення на основі allowlist: цей режим існує з kubectl v1.5, але досі перебуває на етапі альфа через проблеми зі зручністю використання, коректністю та продуктивністю його дизайну. Режим на основі ApplySet призначений для його заміни.
  • Очищення на основі ApplySet: apply set — це обʼєкт на стороні сервера (стандартно Secret), який kubectl може використовувати для точного й ефективного відстеження членства в наборі під час операцій apply. Цей режим зʼявився як альфа у kubectl v1.27 на заміну очищенню на основі allowlist.
СТАН ФУНКЦІОНАЛУ: Alpha since Kubernetes v1.5

Попередження:

Будьте обережні, використовуючи --prune з kubectl apply у режимі allowlist. Те, які обʼєкти очищаються, залежить від значень прапорців --prune-allowlist, --selector і --namespace та ґрунтується на динамічному виявленні обʼєктів в області дії. Особливо якщо значення прапорців змінюються між викликами, це може призвести до неочікуваного видалення або збереження обʼєктів.

Щоб використовувати очищення на основі allowlist, додайте такі прапорці до виклику kubectl apply:

  • --prune: видалити раніше застосовані обʼєкти, яких немає в наборі, переданому поточному виклику.
  • --prune-allowlist: список груп-версій-типів (GVK) для розгляду під час очищення. Цей прапорець необовʼязковий, але наполегливо рекомендований, оскільки його стандартне значення — це частковий список типів як у просторах імен, так і в області кластера, що може призвести до несподіваних результатів.
  • --selector/-l: використовуйте селектор міток, щоб обмежити набір обʼєктів, вибраних для очищення. Цей прапорець необовʼязковий, але наполегливо рекомендований.
  • --all: використовуйте замість --selector/-l, щоб явно вибрати всі раніше застосовані обʼєкти типів зі списку дозволених.

Очищення на основі allowlist запитує в API-сервера всі обʼєкти дозволених GVK, що відповідають заданим міткам (якщо такі є), і намагається зіставити отримані живі конфігурації обʼєктів із файлами маніфестів обʼєктів. Якщо обʼєкт відповідає запиту, не має маніфесту в теці та має анотацію kubectl.kubernetes.io/last-applied-configuration, його буде видалено.

kubectl apply -f <directory> --prune -l <labels> --prune-allowlist=<gvk-list>

Попередження:

Apply із prune слід виконувати лише для кореневої теки, що містить маніфести обʼєктів. Виконання для підтек може призвести до ненавмисного видалення обʼєктів, які раніше були застосовані, мають задані мітки (якщо є) і не зʼявляються в підтеці.
СТАН ФУНКЦІОНАЛУ: Alpha since Kubernetes v1.27

Увага:

kubectl apply --prune --applyset перебуває на етапі альфа, і в наступних випусках можуть зʼявитися несумісні зміни.

Щоб використовувати очищення на основі ApplySet, встановіть змінну середовища KUBECTL_APPLYSET=true і додайте такі прапорці до виклику kubectl apply:

  • --prune: видалити раніше застосовані обʼєкти, яких немає в наборі, переданому поточному виклику.
  • --applyset: назва обʼєкта, який kubectl може використовувати для точного й ефективного відстеження членства в наборі під час операцій apply.
KUBECTL_APPLYSET=true kubectl apply -f <directory> --prune --applyset=<name>

Стандартно тип батьківського обʼєкта ApplySet — Secret. Однак також можна використовувати ConfigMaps у форматі --applyset=configmaps/<name>. Якщо використовується Secret або ConfigMap, kubectl створить обʼєкт, якщо його ще немає.

Також можна використовувати власні ресурси як батьківські обʼєкти ApplySet. Для цього додайте до Custom Resource Definition (CRD), що визначає потрібний ресурс, мітку applyset.kubernetes.io/is-parent-type: true. Потім створіть обʼєкт, який ви хочете використовувати як батьківський обʼєкт ApplySet (kubectl не робить цього автоматично для власних ресурсів). Нарешті, посилайтеся на цей обʼєкт у прапорці applyset так: --applyset=<resource>.<group>/<name> (наприклад, widgets.custom.example.com/widget-name).

Під час очищення на основі ApplySet kubectl додає мітку applyset.kubernetes.io/part-of=<parentID> до кожного обʼєкта в наборі перед надсиланням на сервер. З міркувань продуктивності він також збирає список типів ресурсів і просторів імен, що містить набір, і додає їх в анотації живого батьківського обʼєкта. Нарешті, наприкінці операції apply він запитує в API-сервера обʼєкти цих типів у цих просторах імен (або в області кластера, якщо потрібно), що належать до набору, визначеного міткою applyset.kubernetes.io/part-of=<parentID>.

Застереження та обмеження:

  • Кожен обʼєкт може бути членом не більше одного набору.
  • Прапорець --namespace обовʼязковий під час використання будь-якого батьківського обʼєкта в просторі імен, зокрема стандартного Secret. Це означає, що ApplySets, які охоплюють кілька просторів імен, мають використовувати як батьківський обʼєкт власний ресурс в області кластера.
  • Щоб безпечно використовувати очищення на основі ApplySet з кількома теками, використовуйте унікальну назву ApplySet для кожної.

Як переглянути обʼєкт

Ви можете використовувати kubectl get з -o yaml, щоб переглянути конфігурацію живого обʼєкта:

kubectl get -f <filename|url> -o yaml

Як apply обчислює різницю та обʼєднує зміни

Увага:

Патч — це операція оновлення, обмежена конкретними полями обʼєкта, а не всім обʼєктом. Це дає змогу оновлювати лише певний набір полів обʼєкта без попереднього читання обʼєкта.

Коли kubectl apply оновлює живу конфігурацію обʼєкта, він робить це, надсилаючи запит на патч до API-сервера. Патч визначає оновлення для конкретних полів конфігурації живого обʼєкта. Команда kubectl apply обчислює цей запит на патч за допомогою файлу конфігурації, живої конфігурації та анотації last-applied-configuration, збереженої в живій конфігурації.

Обчислення merge patch

Команда kubectl apply записує вміст файлу конфігурації до анотації kubectl.kubernetes.io/last-applied-configuration. Вона використовується для визначення полів, які було вилучено з файлу конфігурації й потрібно очистити з живої конфігурації. Ось кроки для обчислення того, які поля слід видалити або встановити:

  1. Обчислити поля для видалення. Це поля, які присутні в last-applied-configuration та відсутні у файлі конфігурації.
  2. Обчислити поля для додавання або встановлення. Це поля, які присутні у файлі конфігурації, значення яких не відповідають живій конфігурації.

Ось приклад. Припустимо, що це файл конфігурації для обʼєкта Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1 # update the image
        ports:
        - containerPort: 80

Також, припустимо, що це жива конфігурація для того самого обʼєкта Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # зверніть увагу, що анотація не містить replicas
    # оскільки це поле не оновлювалося через apply
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}
  # ...
spec:
  replicas: 2 # записано командою scale
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
      # ...

Ось обчислення злиття, які виконає kubectl apply:

  1. Обчислити поля для видалення, прочитавши значення з last-applied-configuration і порівнявши їх зі значеннями у файлі конфігурації. Очистити поля, явно встановлені в null у локальному файлі конфігурації обʼєкта, незалежно від того, чи є вони в last-applied-configuration. У цьому прикладі minReadySeconds є в анотації last-applied-configuration, але немає у файлі конфігурації. Дія: очистити minReadySeconds у живій конфігурації.
  2. Обчислити поля для встановлення, прочитавши значення з файлу конфігурації й порівнявши їх зі значеннями в живій конфігурації. У цьому прикладі значення image у файлі конфігурації не збігається зі значенням у живій конфігурації. Дія: встановити значення image у живій конфігурації.
  3. Встановити анотацію last-applied-configuration, щоб вона відповідала значенню файлу конфігурації.
  4. Обʼєднати результати з 1, 2, 3 у єдиний запит на патч до API-сервера.

Ось жива конфігурація, яка є результатом злиття:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # Анотація містить оновлений образ nginx 1.16.1,
    # але не містить оновлення replicas до 2
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}
    # ...
spec:
  selector:
    matchLabels:
      # ...
      app: nginx
  replicas: 2 # Встановлено за допомогою `kubectl scale`. Ігнорується `kubectl apply`.
  # minReadySeconds очищено за допомогою `kubectl apply`
  # ...
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.16.1 # Встановлено за допомогою `kubectl apply`
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

Як зливаються поля різних типів

Те, як певне поле у файлі конфігурації зливається з живою конфігурацією, залежить від типу поля. Існує кілька типів полів:

  • primitive: поле типу рядок, ціле число або логічне значення. Наприклад, image і replicas є полями primitive. Дія: замінити.

  • map, також званий object: поле типу map або складний тип, що містить підполя. Наприклад, labels, annotations, spec і metadata — це map. Дія: злити елементи або підполя.

  • list: поле, що містить список елементів, які можуть бути типів primitive або map. Наприклад, containers, ports і args є списками. Дія: залежить від випадку.

Коли kubectl apply оновлює поле map або list, він зазвичай не замінює все поле, а оновлює окремі піделементи. Наприклад, під час злиття spec у Deployment весь spec не замінюється. Натомість порівнюються й зливаються підполя spec, як-от replicas.

Злиття змін для полів типу primitive

Поля primitive замінюються або очищаються.

Примітка:

- використовується для "not applicable", оскільки значення не використовується.
Поле у файлі конфігурації обʼєктаПоле в живій конфігурації обʼєктаПоле в last-applied-configurationДія
ТакТак-Встановити живе значення з файлу конфігурації.
ТакНі-Встановити живе значення з локальної конфігурації.
Ні-ТакОчистити з живої конфігурації.
Ні-НіНічого не робити. Зберегти живе значення.

Злиття змін у полях типу map

Поля, які є map, зливаються шляхом порівняння кожного з підполів або елементів map:

Примітка:

- використовується для "not applicable", оскільки значення не використовується.
Ключ у файлі конфігурації обʼєктаКлюч у живій конфігурації обʼєктаПоле в last-applied-configurationДія
ТакТак-Порівняти значення підполів.
ТакНі-Встановити живе значення з локальної конфігурації.
Ні-ТакВидалити з живої конфігурації.
Ні-НіНічого не робити. Зберегти живе значення.

Злиття змін для полів типу list

Злиття змін у list використовує одну з трьох стратегій:

  • Заміна list, якщо всі його елементи є primitive.
  • Злиття окремих елементів у списку складних елементів.
  • Злиття list елементів primitive.

Вибір стратегії залежить від конкретного поля.

Заміна list, якщо всі його елементи є primitive

Список обробляється так само, як поле primitive. Замініть або видаліть увесь список. Це зберігає порядок.

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

# Значення last-applied-configuration
    args: ["a", "b"]

# Значення файлу конфігурації
    args: ["a", "c"]

# Жива конфігурація
    args: ["a", "b", "d"]

# Результат після злиття
    args: ["a", "c"]

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

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

Обробляйте список як map, а конкретне поле кожного елемента — як ключ. Додавайте, видаляйте або оновлюйте окремі елементи. Це не зберігає порядок.

Ця стратегія злиття використовує спеціальний теґ кожного поля, який називається patchMergeKey. patchMergeKey визначено для кожного поля у вихідному коді Kubernetes: types.go Під час злиття списку map поле, вказане як patchMergeKey для певного елемента, використовується як ключ map для цього елемента.

Приклад: Використайте kubectl apply, щоб оновити поле containers у PodSpec. Це зливає список так, ніби він є map, у якому ключем кожного елемента є name.

# Значення last-applied-configuration
    containers:
    - name: nginx
      image: nginx:1.16
    - name: nginx-helper-a # ключ: nginx-helper-a; буде видалено в результаті
      image: helper:1.3
    - name: nginx-helper-b # ключ: nginx-helper-b; буде збережено
      image: helper:1.3

# Значення файлу конфігурації
    containers:
    - name: nginx
      image: nginx:1.16
    - name: nginx-helper-b
      image: helper:1.3
    - name: nginx-helper-c # ключ: nginx-helper-c; буде додано в результаті
      image: helper:1.3

# Жива конфігурація
    containers:
    - name: nginx
      image: nginx:1.16
    - name: nginx-helper-a
      image: helper:1.3
    - name: nginx-helper-b
      image: helper:1.3
      args: ["run"] # Поле буде збережено
    - name: nginx-helper-d # ключ: nginx-helper-d; буде збережено
      image: helper:1.3

# Результат після злиття
    containers:
    - name: nginx
      image: nginx:1.16
      # Елемент nginx-helper-a видалено
    - name: nginx-helper-b
      image: helper:1.3
      args: ["run"] # Поле збережено
    - name: nginx-helper-c # Елемент додано
      image: helper:1.3
    - name: nginx-helper-d # Елемент проігноровано
      image: helper:1.3

Пояснення:

  • Контейнер з назвою "nginx-helper-a" видалено, оскільки у файлі конфігурації немає контейнера з назвою "nginx-helper-a".
  • Контейнер з назвою "nginx-helper-b" зберіг зміни в args у живій конфігурації. kubectl apply зміг визначити, що "nginx-helper-b" у живій конфігурації — це той самий "nginx-helper-b", що й у файлі конфігурації, хоча їхні поля мали різні значення (у файлі конфігурації немає args). Це тому, що значення поля patchMergeKey (name) було однаковим в обох.
  • Контейнер з назвою "nginx-helper-c" додано, оскільки в живій конфігурації не було контейнера з такою назвою, а у файлі конфігурації він був.
  • Контейнер з назвою "nginx-helper-d" збережено, оскільки в last-applied-configuration не було елемента з такою назвою.

Злиття списку елементів типу primitive

Станом на Kubernetes 1.5 злиття списків елементів типу primitive не підтримується.

Примітка:

Вибір стратегії для певного поля визначається теґом patchStrategy у types.go Якщо для поля типу list не вказано patchStrategy, список замінюється.

Стандартні значення полів

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

Ось файл конфігурації для обʼєкта Deployment. У файлі не вказано strategy:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Створіть обʼєкт, використовуючи kubectl apply:

kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml

Виведіть живу конфігурацію, використовуючи kubectl get:

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

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

apiVersion: apps/v1
kind: Deployment
# ...
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  replicas: 1 # стандартне значення від apiserver
  strategy:
    rollingUpdate: # стандартне значення від apiserver, виведене з strategy.type
      maxSurge: 1
      maxUnavailable: 1
    type: RollingUpdate # стандартне значення від apiserver
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        imagePullPolicy: IfNotPresent # стандартне значення від apiserver
        name: nginx
        ports:
        - containerPort: 80
          protocol: TCP # стандартне значення від apiserver
        resources: {} # стандартне значення від apiserver
        terminationMessagePath: /dev/termination-log # стандартне значення від apiserver
      dnsPolicy: ClusterFirst # стандартне значення від apiserver
      restartPolicy: Always # стандартне значення від apiserver
      securityContext: {} # стандартне значення від apiserver
      terminationGracePeriodSeconds: 30 # стандартне значення від apiserver
# ...

У запиті на патч поля зі стандартними значеннями не отримують стандартні значення повторно, якщо їх явно не очищено в цьому запиті. Це може спричинити неочікувану поведінку полів, стандартні значення яких залежать від інших полів. Коли ці інші поля згодом змінюються, виведені з них значення не оновлюються, якщо їх явно не очистити.

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

Приклад:

# last-applied-configuration
spec:
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# Файл конфігурації
spec:
  strategy:
    type: Recreate # оновлене значення
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# Жива конфігурація
spec:
  strategy:
    type: RollingUpdate # стандартне значення
    rollingUpdate: # стандартне значення, виведене з type
      maxSurge : 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# Результат після злиття — ПОМИЛКА!
spec:
  strategy:
    type: Recreate # оновлене значення: несумісне з rollingUpdate
    rollingUpdate: # стандартне значення: несумісне з "type: Recreate"
      maxSurge : 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Пояснення:

  1. Користувач створює Deployment без визначення strategy.type.
  2. Сервер встановлює для strategy.type стандартне значення RollingUpdate і стандартні значення для strategy.rollingUpdate.
  3. Користувач змінює strategy.type на Recreate. Значення strategy.rollingUpdate лишаються стандартними, хоча сервер очікує, що їх буде очищено. Якби значення strategy.rollingUpdate було спочатку визначено у файлі конфігурації, було б зрозуміліше, що їх потрібно видалити.
  4. Apply завершується збоєм, бо strategy.rollingUpdate не очищено. Поле strategy.rollingupdate не можна визначати, якщо strategy.type дорівнює Recreate.

Рекомендація: ці поля слід явно визначати у файлі конфігурації обʼєкта:

  • Селектори та мітки PodTemplate робочих навантажень, як-от Deployment, StatefulSet, Job, DaemonSet, ReplicaSet і ReplicationController
  • Стратегія розгортання Deployment

Як очистити поля зі стандартними значеннями сервера або поля, встановлені іншими записувачами

Поля, яких немає у файлі конфігурації, можна очистити, встановивши їхні значення в null і застосувавши файл конфігурації. Для полів зі стандартними значеннями сервера це повторно встановлює стандартні значення.

Як змінити власника поля між файлом конфігурації та прямими імперативними записувачами

Лише цими методами слід змінювати окреме поле обʼєкта:

  • Використовуйте kubectl apply.
  • Записуйте безпосередньо в живу конфігурацію без зміни файлу конфігурації: наприклад, використовуйте kubectl scale.

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

Додайте поле до файлу конфігурації. Для цього поля припиніть прямі оновлення живої конфігурації, які не проходять через kubectl apply.

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

Станом на Kubernetes 1.5 зміна власника поля з файлу конфігурації на імперативного записувача потребує ручних кроків:

  • Видаліть поле з файлу конфігурації.
  • Видаліть поле з анотації kubectl.kubernetes.io/last-applied-configuration на живому обʼєкті.

Зміна методів керування

Обʼєктами Kubernetes слід керувати лише одним методом одночасно. Перехід з одного методу на інший можливий, але виконується вручну.

Примітка:

Можна використовувати імперативне видалення разом із декларативним керуванням.

Міграція з керування імперативними командами на декларативну конфігурацію обʼєктів

Міграція з керування імперативними командами на декларативну конфігурацію обʼєктів складається з кількох ручних кроків:

  1. Експортуйте живий обʼєкт у локальний файл конфігурації:

    kubectl get <kind>/<name> -o yaml > <kind>_<name>.yaml
    
  2. Видаліть вручну поле status з файлу конфігурації.

    Примітка:

    Цей крок є необовʼязковим, оскільки kubectl apply не оновлює поле статусу, навіть якщо воно присутнє у файлі конфігурації.
  3. Встановіть анотацію kubectl.kubernetes.io/last-applied-configuration на обʼєкті:

    kubectl replace --save-config -f <kind>_<name>.yaml
    
  4. Змініть процеси так, щоб для керування обʼєктом використовувався виключно kubectl apply.

Міграція з імперативного конфігурування обʼєктів на декларативну конфігурацію обʼєктів

  1. Встановіть анотацію kubectl.kubernetes.io/last-applied-configuration на обʼєкті:

    kubectl replace --save-config -f <kind>_<name>.yaml
    
  2. Змініть процеси так, щоб для керування обʼєктом використовувався виключно kubectl apply.

Визначення селекторів контролера та міток PodTemplate

Попередження:

Оновлювати селектори контролерів категорично не рекомендовано.

Рекомендований підхід — визначити одну незмінну мітку PodTemplate, яка використовується тільки селектором контролера й не має іншого семантичного значення.

Приклад:

selector:
  matchLabels:
      controller-selector: "apps/v1/deployment/nginx"
template:
  metadata:
    labels:
      controller-selector: "apps/v1/deployment/nginx"

Що далі

2 - Декларативне керування обʼєктами Kubernetes за допомогою Kustomize

Kustomize — це окремий інструмент для налаштування обʼєктів Kubernetes за допомогою файлу kustomization.

Починаючи з версії 1.14, kubectl також підтримує керування обʼєктами Kubernetes за допомогою файлу kustomization. Щоб переглянути ресурси, знайдені в теці з файлом kustomization, виконайте таку команду:

kubectl kustomize <kustomization_directory>

Щоб застосувати ці ресурси, виконайте kubectl apply із прапорцем --kustomize або -k:

kubectl apply -k <kustomization_directory>

Перш ніж ви розпочнете

Встановіть kubectl.

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Для перевірки версії введіть kubectl version.

Огляд Kustomize

Kustomize — це інструмент для налаштування конфігурацій Kubernetes. Він має такі можливості для керування файлами конфігурації застосунків:

  • генерування ресурсів з інших джерел
  • встановлення наскрізних полів для ресурсів
  • компонування та налаштування колекцій ресурсів

Генерування ресурсів

ConfigMaps і Secrets зберігають конфігураційні або конфіденційні дані, які використовуються іншими обʼєктами Kubernetes, наприклад Podʼами. Джерело істини для ConfigMaps або Secrets зазвичай розташоване поза кластером, наприклад це файл .properties або файл ключа SSH. Kustomize має secretGenerator і configMapGenerator, які генерують Secret і ConfigMap із файлів або літералів.

configMapGenerator

Щоб згенерувати ConfigMap з файлу, додайте запис до списку files у configMapGenerator. Ось приклад генерування ConfigMap з елементом даних із файлу .properties:

# Створіть файл application.properties
cat <<EOF >application.properties
FOO=Bar
EOF

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
  files:
  - application.properties
EOF

Згенерований ConfigMap можна переглянути за допомогою такої команди:

kubectl kustomize ./

Згенерований ConfigMap виглядає так:

apiVersion: v1
data:
  application.properties: |
    FOO=Bar
kind: ConfigMap
metadata:
  name: example-configmap-1-8mbdf7882g

Щоб згенерувати ConfigMap з файлу env, додайте запис до списку envs у configMapGenerator. Ось приклад генерування ConfigMap з елементом даних із файлу .env:

# Створіть файл .env
cat <<EOF >.env
FOO=Bar
EOF

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
  envs:
  - .env
EOF

Згенерований ConfigMap можна переглянути за допомогою такої команди:

kubectl kustomize ./

Згенерований ConfigMap виглядає так:

apiVersion: v1
data:
  FOO: Bar
kind: ConfigMap
metadata:
  name: example-configmap-1-42cfbf598f

Примітка:

Кожна змінна у файлі .env стає окремим ключем у згенерованому ConfigMap. Це відрізняється від попереднього прикладу, де файл з назвою application.properties (з усіма його записами) вбудовується як значення одного ключа.

ConfigMaps також можна генерувати з літеральних пар ключ-значення. Щоб згенерувати ConfigMap з літеральної пари ключ-значення, додайте запис до списку literals у configMapGenerator. Ось приклад генерування ConfigMap з елементом даних із пари ключ-значення:

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-2
  literals:
  - FOO=Bar
EOF

Згенерований ConfigMap можна перевірити за допомогою такої команди:

kubectl kustomize ./

Згенерований ConfigMap виглядає так:

apiVersion: v1
data:
  FOO: Bar
kind: ConfigMap
metadata:
  name: example-configmap-2-g2hdhfc6tk

Щоб використати згенерований ConfigMap у Deployment, посилайтеся на нього за назвою configMapGenerator. Kustomize автоматично замінить цю назву згенерованою.

Ось приклад Deployment, що використовує згенерований ConfigMap:

# Створіть файл application.properties
cat <<EOF >application.properties
FOO=Bar
EOF

cat <<EOF >deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-app
        volumeMounts:
        - name: config
          mountPath: /config
      volumes:
      - name: config
        configMap:
          name: example-configmap-1
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
configMapGenerator:
- name: example-configmap-1
  files:
  - application.properties
EOF

Згенеруйте ConfigMap та Deployment:

kubectl kustomize ./

Згенерований Deployment посилатиметься на згенерований ConfigMap за назвою:

apiVersion: v1
data:
  application.properties: |
    FOO=Bar
kind: ConfigMap
metadata:
  name: example-configmap-1-g4hk9g2ff8
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: my-app
  name: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - image: my-app
        name: app
        volumeMounts:
        - mountPath: /config
          name: config
      volumes:
      - configMap:
          name: example-configmap-1-g4hk9g2ff8
        name: config

secretGenerator

Ви можете генерувати Secrets із файлів або літеральних пар ключ-значення. Щоб згенерувати Secret з файлу, додайте запис до списку files у secretGenerator. Ось приклад генерування Secret з елементом даних із файлу:

# Створіть файл password.txt
cat <<EOF >./password.txt
username=admin
password=secret
EOF

cat <<EOF >./kustomization.yaml
secretGenerator:
- name: example-secret-1
  files:
  - password.txt
EOF

Згенерований Secret має такий вигляд:

apiVersion: v1
data:
  password.txt: dXNlcm5hbWU9YWRtaW4KcGFzc3dvcmQ9c2VjcmV0Cg==
kind: Secret
metadata:
  name: example-secret-1-t2kt65hgtb
type: Opaque

Щоб згенерувати Secret з літеральної пари ключ-значення, додайте запис до списку literals у secretGenerator. Ось приклад генерування Secret з елементом даних із пари ключ-значення:

cat <<EOF >./kustomization.yaml
secretGenerator:
- name: example-secret-2
  literals:
  - username=admin
  - password=secret
EOF

Згенерований Secret має такий вигляд:

apiVersion: v1
data:
  password: c2VjcmV0
  username: YWRtaW4=
kind: Secret
metadata:
  name: example-secret-2-t52t6g96d8
type: Opaque

Подібно до ConfigMaps, згенеровані Secrets можна використовувати в Deployments, посилаючись на назву secretGenerator:

# Створіть файл password.txt
cat <<EOF >./password.txt
username=admin
password=secret
EOF

cat <<EOF >deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-app
        volumeMounts:
        - name: password
          mountPath: /secrets
      volumes:
      - name: password
        secret:
          secretName: example-secret-1
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
secretGenerator:
- name: example-secret-1
  files:
  - password.txt
EOF

generatorOptions

До згенерованих ConfigMaps і Secrets додається суфікс із хешем вмісту. Це гарантує, що під час зміни вмісту генерується новий ConfigMap або Secret. Щоб вимкнути додавання суфікса, можна використати generatorOptions. Крім того, можна вказати наскрізні параметри для згенерованих ConfigMaps і Secrets.

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-3
  literals:
  - FOO=Bar
generatorOptions:
  disableNameSuffixHash: true
  labels:
    type: generated
  annotations:
    note: generated
EOF

Виконайте kubectl kustomize ./, щоб переглянути згенерований ConfigMap:

apiVersion: v1
data:
  FOO: Bar
kind: ConfigMap
metadata:
  annotations:
    note: generated
  labels:
    type: generated
  name: example-configmap-3

Встановлення наскрізних полів

Досить поширена практика — встановлювати наскрізні поля для всіх ресурсів Kubernetes у проєкті. Деякі випадки використання наскрізних полів:

  • встановлення того самого простору імен для всіх ресурсів
  • додавання того самого префікса або суфікса назви
  • додавання того самого набору міток
  • додавання того самого набору анотацій

Ось приклад:

# Створіть deployment.yaml
cat <<EOF >./deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
EOF

cat <<EOF >./kustomization.yaml
namespace: my-namespace
namePrefix: dev-
nameSuffix: "-001"
labels:
  - pairs:
      app: bingo
    includeSelectors: true
commonAnnotations:
  oncallPager: 800-555-1212
resources:
- deployment.yaml
EOF

Виконайте kubectl kustomize ./, щоб побачити, що всі ці поля встановлено в ресурсі Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    oncallPager: 800-555-1212
  labels:
    app: bingo
  name: dev-nginx-deployment-001
  namespace: my-namespace
spec:
  selector:
    matchLabels:
      app: bingo
  template:
    metadata:
      annotations:
        oncallPager: 800-555-1212
      labels:
        app: bingo
    spec:
      containers:
      - image: nginx
        name: nginx

Компонування та налаштування ресурсів

Часто в проєкті компонують набір ресурсів і керують ними в одному файлі чи теці. Kustomize дає змогу компонувати ресурси з різних файлів і застосовувати до них патчі або інші налаштування.

Компонування

Kustomize підтримує компонування різних ресурсів. Поле resources у файлі kustomization.yaml визначає список ресурсів, які слід включити в конфігурацію. Вкажіть шлях до файлу конфігурації ресурсу у списку resources. Ось приклад застосунку NGINX, що складається з Deployment і Service:

# Створіть файл deployment.yaml
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# Створіть файл service.yaml
cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
  labels:
    run: my-nginx
spec:
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: my-nginx
EOF

# Створіть файл kustomization.yaml та скомпонуйте їх
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF

Ресурси з kubectl kustomize ./ містять обидва обʼєкти: Deployment і Service.

Налаштування

Патчі можна використовувати для застосування різних налаштувань до ресурсів. Kustomize підтримує різні механізми патчів через StrategicMerge і Json6902 за допомогою поля patches. patches може бути файлом або вбудованим рядком, спрямованим на один або кілька ресурсів.

Поле patches містить список патчів, які застосовуються в порядку їх зазначення. Ціль патча вибирає ресурси за group, version, kind, name, namespace, labelSelector і annotationSelector.

Рекомендовано створювати невеликі патчі, які роблять щось одне. Наприклад, створіть один патч для збільшення кількості реплік Deployment, а інший — для встановлення обмеження памʼяті. Цільовий ресурс визначається за полями group, version, kind і name з файлу патча.

# Створіть файл deployment.yaml
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# Створіть патч increase_replicas.yaml
cat <<EOF > increase_replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
EOF

# Створіть інший патч set_memory.yaml
cat <<EOF > set_memory.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  template:
    spec:
      containers:
      - name: my-nginx
        resources:
          limits:
            memory: 512Mi
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
patches:
  - path: increase_replicas.yaml
  - path: set_memory.yaml
EOF

Виконайте kubectl kustomize ./, щоб переглянути Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - image: nginx
        name: my-nginx
        ports:
        - containerPort: 80
        resources:
          limits:
            memory: 512Mi

Не всі ресурси чи поля підтримують патчі strategicMerge. Для зміни довільних полів у довільних ресурсах Kustomize пропонує застосування JSON patch через Json6902. Щоб знайти правильний ресурс для патча Json6902, обовʼязково потрібно вказати поле target у файлі kustomization.yaml.

Наприклад, збільшити кількість реплік обʼєкта Deployment можна також за допомогою патча Json6902. Цільовий ресурс визначається за group, version, kind і name з поля target.

# Створіть файл deployment.yaml
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# Створіть json патч
cat <<EOF > patch.yaml
- op: replace
  path: /spec/replicas
  value: 3
EOF

# Створіть kustomization.yaml
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml

patches:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: my-nginx
  path: patch.yaml
EOF

Виконайте kubectl kustomize ./, щоб побачити, що поле replicas оновлено:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - image: nginx
        name: my-nginx
        ports:
        - containerPort: 80

Крім патчів, Kustomize також дає змогу налаштовувати образи контейнерів або вставляти значення полів з інших обʼєктів у контейнери без створення патчів. Наприклад, можна змінити образ, що використовується в контейнерах, вказавши новий образ у полі images у kustomization.yaml.

cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
images:
- name: nginx
  newName: my.image.registry/nginx
  newTag: "1.4.0"
EOF

Виконайте kubectl kustomize ./, щоб побачити, що використовуваний образ оновлено:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - image: my.image.registry/nginx:1.4.0
        name: my-nginx
        ports:
        - containerPort: 80

Іноді застосунку, що працює в Podʼі, потрібні значення конфігурації з інших обʼєктів. Наприклад, Pod з обʼєкта Deployment має прочитати відповідну назву Service зі змінної середовища або з аргументу команди. Оскільки назва Service може змінюватися, коли у файлі kustomization.yaml додається namePrefix або nameSuffix, не рекомендовано жорстко задавати назву Service в аргументі команди. Для цього Kustomize може вставити назву Service у контейнери через replacements.

# Створіть файл deployment.yaml (взявши в лапки роздільник here doc)
cat <<'EOF' > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        command: ["start", "--host", "MY_SERVICE_NAME_PLACEHOLDER"]
EOF

# Створіть файл service.yaml
cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
  labels:
    run: my-nginx
spec:
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: my-nginx
EOF

cat <<EOF >./kustomization.yaml
namePrefix: dev-
nameSuffix: "-001"

resources:
- deployment.yaml
- service.yaml

replacements:
- source:
    kind: Service
    name: my-nginx
    fieldPath: metadata.name
  targets:
  - select:
      kind: Deployment
      name: my-nginx
    fieldPaths:
    - spec.template.spec.containers.0.command.2
EOF

Виконайте kubectl kustomize ./, щоб побачити, що назва Service, вставлена в контейнери, — це dev-my-nginx-001:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dev-my-nginx-001
spec:
  replicas: 2
  selector:
    matchLabels:
      run: my-nginx
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - command:
        - start
        - --host
        - dev-my-nginx-001
        image: nginx
        name: my-nginx

Base та Overlay

У Kustomize є поняття base і overlay. Base — це тека з файлом kustomization.yaml, яка містить набір ресурсів і повʼязані налаштування. Base може бути локальною текою або текою з віддаленого репозиторію, якщо всередині є файл kustomization.yaml. Overlay — це тека з файлом kustomization.yaml, яка посилається на інші теки kustomization як на свої bases. Base нічого не знає про overlay і може використовуватися в кількох overlay.

Файл kustomization.yaml у теці overlay може посилатися на кілька bases, обʼєднуючи всі ресурси, визначені в цих base, в єдину конфігурацію. Крім того, він може застосовувати налаштування поверх цих ресурсів для задоволення певних вимог.

Ось приклад base:

# Створіть теку для зберігання base
mkdir base
# Створіть файл base/deployment.yaml
cat <<EOF > base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
EOF

# Створіть файл base/service.yaml
cat <<EOF > base/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
  labels:
    run: my-nginx
spec:
  ports:
  - port: 80
    protocol: TCP
  selector:
    run: my-nginx
EOF
# Створіть файл base/kustomization.yaml
cat <<EOF > base/kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF

Цей base можна використовувати в кількох overlay. Ви можете додавати різні namePrefix або інші наскрізні поля в різних overlay. Ось два overlay, які використовують той самий base.

mkdir dev
cat <<EOF > dev/kustomization.yaml
resources:
- ../base
namePrefix: dev-
EOF

mkdir prod
cat <<EOF > prod/kustomization.yaml
resources:
- ../base
namePrefix: prod-
EOF

Як застосовувати, переглядати й видаляти обʼєкти за допомогою Kustomize

Використовуйте --kustomize або -k у командах kubectl, щоб розпізнавати ресурси, якими керує kustomization.yaml. Зверніть увагу, що -k має вказувати на теку kustomization, наприклад,

kubectl apply -k <kustomization directory>/

Для такого kustomization.yaml,

# Створіть файл deployment.yaml
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      run: my-nginx
  replicas: 2
  template:
    metadata:
      labels:
        run: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
EOF

# Створіть файл kustomization.yaml
cat <<EOF >./kustomization.yaml
namePrefix: dev-
labels:
  - pairs:
      app: my-nginx
    includeSelectors: true
resources:
- deployment.yaml
EOF

Виконайте таку команду, щоб застосувати обʼєкт Deployment dev-my-nginx:

> kubectl apply -k ./
deployment.apps/dev-my-nginx created

Виконайте одну з наведених нижче команд, щоб переглянути обʼєкт Deployment dev-my-nginx:

kubectl get -k ./
kubectl describe -k ./

Виконайте таку команду, щоб порівняти обʼєкт Deployment dev-my-nginx зі станом, у якому був би кластер, якби маніфест було застосовано:

kubectl diff -k ./

Виконайте таку команду, щоб видалити обʼєкт Deployment dev-my-nginx:

> kubectl delete -k ./
deployment.apps "dev-my-nginx" deleted

Перелік можливостей Kustomize

ПолеТипПояснення
bases[]stringКожен запис у цьому списку має вказувати на теку, що містить файл kustomization.yaml
commonAnnotationsmap[string]stringанотації, які додаються до всіх ресурсів
commonLabelsmap[string]stringмітки, які додаються до всіх ресурсів та селекторів
configMapGenerator[]ConfigMapArgsКожен запис у цьому списку генерує ConfigMap
configurations[]stringКожен запис у цьому списку має вказувати на файл, що містить конфігурації трансформаторів Kustomize
crds[]stringКожен запис у цьому списку має вказувати на файл визначення OpenAPI для типів Kubernetes
generatorOptionsGeneratorOptionsЗмінює поведінку всіх генераторів ConfigMap та Secret
images[]ImageКожен запис змінює назву, теґи та/або дайджест для одного образу без створення патчів
labelsmap[string]stringДодає мітки без автоматичного додавання відповідних селекторів
namePrefixstringзначення цього поля додається на початок назв усіх ресурсів
nameSuffixstringзначення цього поля додається в кінець назв усіх ресурсів
patchesJson6902[]PatchКожен запис у цьому списку має вказувати на обʼєкт Kubernetes та Json Patch
patchesStrategicMerge[]stringКожен запис у цьому списку має вказувати на strategic merge patch обʼєкта Kubernetes
replacements[]Replacementsкопіює значення з поля ресурсу в будь-яку кількість зазначених цілей
resources[]stringКожен запис у цьому списку має вказувати на наявний файл конфігурації ресурсу
secretGenerator[]SecretArgsКожен запис у цьому списку генерує Secret
vars[]VarКожен запис призначений для захоплення тексту з поля одного ресурсу

Що далі

3 - Керування обʼєктами Kubernetes за допомогою імперативних команд

Обʼєкти Kubernetes можна швидко створювати, оновлювати й видаляти безпосередньо за допомогою імперативних команд, вбудованих в інструмент командного рядка kubectl. У цьому документі пояснено, як організовано ці команди та як їх використовувати для керування живими обʼєктами.

Перш ніж ви розпочнете

Встановіть kubectl.

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Для перевірки версії введіть kubectl version.

Компроміси

Інструмент kubectl підтримує три види керування обʼєктами:

  • Імперативні команди
  • Імперативне конфігурування обʼєктів
  • Декларативна конфігурація обʼєктів

Переваги й недоліки кожного виду керування обʼєктами розглянуто в розділі Управління обʼєктами Kubernetes.

Як створювати обʼєкти

Інструмент kubectl підтримує команди на основі дієслів для створення деяких найпоширеніших типів обʼєктів. Команди названо так, щоб їх могли розпізнати користувачі, не знайомі з типами обʼєктів Kubernetes.

  • run: створює новий Pod для запуску контейнера.
  • expose: створює новий обʼєкт Service для балансування трафіку між Podʼами.
  • autoscale: створює новий обʼєкт Autoscaler для автоматичного горизонтального масштабування контролера, наприклад Deployment.

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

  • create <objecttype> [<subtype>] <instancename>

Деякі типи обʼєктів мають підтипи, які можна вказати в команді create. Наприклад, обʼєкт Service має кілька підтипів, зокрема ClusterIP, LoadBalancer і NodePort. Ось приклад створення Service з підтипом NodePort:

kubectl create service nodeport <myservicename>

У наведеному вище прикладі команда create service nodeport називається підкомандою команди create service.

Ви можете використати прапорець -h, щоб знайти аргументи й прапорці, які підтримує підкоманда:

kubectl create service nodeport -h

Як оновлювати обʼєкти

Команда kubectl підтримує команди на основі дієслів для деяких поширених операцій оновлення. Ці команди названо так, щоб користувачі, не знайомі з обʼєктами Kubernetes, могли виконувати оновлення, не знаючи конкретних полів, які потрібно встановити:

  • scale: горизонтально масштабувати контролер, щоб додати або вилучити Podʼи, оновивши кількість реплік контролера.
  • annotate: додати анотацію до обʼєкта або вилучити її.
  • label: додати мітку до обʼєкта або вилучити її.

Команда kubectl також підтримує команди оновлення на основі аспекту обʼєкта. Встановлення цього аспекту може встановлювати різні поля для різних типів обʼєктів:

  • set <field>: встановити аспект обʼєкта.

Примітка:

У версії Kubernetes 1.5 не кожна команда на основі дієслова має відповідну команду на основі аспекту.

Інструмент kubectl підтримує ці додаткові способи безпосереднього оновлення живого обʼєкта, однак вони вимагають кращого розуміння схеми обʼєктів Kubernetes.

  • edit: безпосередньо редагувати необроблену конфігурацію живого обʼєкта, відкриваючи її в редакторі.
  • patch: безпосередньо змінювати конкретні поля живого обʼєкта за допомогою рядка патча. Докладніше про рядки патча дивіться в розділі про патчі в API Conventions.

Як видаляти обʼєкти

Ви можете використовувати команду delete, щоб видалити обʼєкт з кластера:

  • delete <type>/<name>

Примітка:

Ви можете використовувати kubectl delete як для імперативних команд, так і для імперативного конфігурування обʼєктів. Різниця полягає в аргументах, переданих команді. Щоб використати kubectl delete як імперативну команду, передайте обʼєкт для видалення як аргумент. Ось приклад, який передає обʼєкт Deployment з назвою nginx:
kubectl delete deployment/nginx

Як переглянути обʼєкт

Існує кілька команд для виведення інформації про обʼєкт:

  • get: виводить базову інформацію про відповідні обʼєкти. Використайте get -h, щоб побачити список параметрів.
  • describe: виводить агреговану детальну інформацію про відповідні обʼєкти.
  • logs: виводить stdout і stderr контейнера, що працює в Podʼі.

Використання команд set для модифікації обʼєктів перед створенням

Деякі поля обʼєктів не мають прапорця, який можна використати в команді create. У деяких із цих випадків можна використати комбінацію set і create, щоб вказати значення поля перед створенням обʼєкта. Для цього вивід команди create передається через канал до команди set, а потім назад до команди create. Ось приклад:

kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run=client | kubectl set selector --local -f - 'environment=qa' -o yaml | kubectl create -f -
  1. Команда kubectl create service -o yaml --dry-run=client створює конфігурацію для Service, але виводить її в stdout у форматі YAML замість надсилання до API-сервера Kubernetes.
  2. Команда kubectl set selector --local -f - -o yaml читає конфігурацію зі stdin і записує оновлену конфігурацію в stdout у форматі YAML.
  3. Команда kubectl create -f - створює обʼєкт, використовуючи конфігурацію, отриману через stdin.

Використання --edit для модифікації обʼєктів перед створенням

Можна використати kubectl create --edit, щоб внести довільні зміни в обʼєкт перед його створенням. Ось приклад:

kubectl create service clusterip my-svc --clusterip="None" -o yaml --dry-run=client > /tmp/srv.yaml
kubectl create --edit -f /tmp/srv.yaml
  1. Команда kubectl create service створює конфігурацію для Service та зберігає її у /tmp/srv.yaml.
  2. Команда kubectl create --edit відкриває файл конфігурації для редагування перед створенням обʼєкта.

Що далі

4 - Імперативне керування обʼєктами Kubernetes за допомогою файлів конфігурації

Обʼєкти Kubernetes можна створювати, оновлювати й видаляти за допомогою інструмента командного рядка kubectl разом із файлом конфігурації обʼєкта у форматі YAML або JSON. У цьому документі пояснено, як визначати обʼєкти й керувати ними за допомогою файлів конфігурації.

Перш ніж ви розпочнете

Встановіть kubectl.

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Для перевірки версії введіть kubectl version.

Компроміси

Інструмент kubectl підтримує три види керування обʼєктами:

  • Імперативні команди
  • Імперативне конфігурування обʼєктів
  • Декларативна конфігурація обʼєктів

Переваги й недоліки кожного виду керування обʼєктами розглянуто в розділі Управління обʼєктами Kubernetes.

Як створювати обʼєкти

Ви можете використовувати kubectl create -f, щоб створити обʼєкт з файлу конфігурації. Докладніше дивіться в довіднику API Kubernetes.

  • kubectl create -f <filename|url>

Як оновити обʼєкти

Попередження:

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

Ви можете використовувати kubectl replace -f, щоб оновити живий обʼєкт відповідно до файлу конфігурації.

  • kubectl replace -f <filename|url>

Як видалити обʼєкти

Ви можете використовувати kubectl delete -f, щоб видалити обʼєкт, описаний у файлі конфігурації.

  • kubectl delete -f <filename|url>

Примітка:

Якщо файл конфігурації задає поле generateName у розділі metadata замість поля name, ви не можете видалити обʼєкт за допомогою kubectl delete -f <filename|url>. Для видалення обʼєкта доведеться використати інші прапорці. Наприклад:

kubectl delete <type> <name>
kubectl delete <type> -l <label>

Як переглянути обʼєкт

Ви можете використовувати kubectl get -f, щоб переглянути інформацію про обʼєкт, описаний у файлі конфігурації.

  • kubectl get -f <filename|url> -o yaml

Прапорець -o yaml вказує, що треба вивести повну конфігурацію обʼєкта. Використайте kubectl get -h, щоб побачити список параметрів.

Обмеження

Команди create, replace і delete добре працюють, коли конфігурація кожного обʼєкта повністю визначена й записана в його файлі конфігурації. Однак якщо живий обʼєкт оновлено, а оновлення не внесено до його файлу конфігурації, вони будуть втрачені під час наступного виконання replace. Це може статися, якщо контролер, як-от HorizontalPodAutoscaler, вносить оновлення безпосередньо в живий обʼєкт. Ось приклад:

  1. Ви створюєте обʼєкт з файлу конфігурації.
  2. Інше джерело оновлює обʼєкт, змінюючи якесь поле.
  3. Ви замінюєте обʼєкт з файлу конфігурації. Зміни, внесені іншим джерелом на кроці 2, втрачаються.

Якщо вам потрібна підтримка кількох записувачів для одного обʼєкта, можна використовувати kubectl apply для керування обʼєктом.

Створення та редагування обʼєкта за URL без збереження конфігурації

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

kubectl create -f <url> --edit

Міграція від імперативних команд до імперативного конфігурування обʼєктів

Міграція від імперативних команд до імперативного конфігурування обʼєктів складається з кількох кроків, які виконуються вручну.

  1. Експортуйте живий обʼєкт у локальний файл конфігурації обʼєкта:

    kubectl get <kind>/<name> -o yaml > <kind>_<name>.yaml
    
  2. Вручну вилучіть поле status із файлу конфігурації обʼєкта.

  3. Для подальшого керування обʼєктом використовуйте виключно replace.

    kubectl replace -f <kind>_<name>.yaml
    

Визначення селекторів контролерів та міток PodTemplate

Попередження:

Оновлювати селектори контролерів категорично не рекомендовано.

Рекомендований підхід — визначити одну незмінну мітку PodTemplate, яка використовується тільки селектором контролера без іншого семантичного значення.

Приклад мітки:

selector:
  matchLabels:
      controller-selector: "apps/v1/deployment/nginx"
template:
  metadata:
    labels:
      controller-selector: "apps/v1/deployment/nginx"

Що далі

5 - Оновлення обʼєктів API на місці за допомогою kubectl patch

Використовуйте kubectl patch для оновлення обʼєктів Kubernetes API на місці. Виконайте strategic merge patch або JSON merge patch.

У цьому завданні показано, як використовувати kubectl patch для оновлення обʼєкта API на місці. Вправи цього завдання демонструють strategic merge patch і JSON merge patch.

Перш ніж ви розпочнете

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Для перевірки версії введіть kubectl version.

Використання strategic merge patch для оновлення Deployment

Ось файл конфігурації для Deployment, що має дві репліки. Кожна репліка є Podʼом, який має один контейнер:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: patch-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: patch-demo-ctr
        image: nginx
      tolerations:
      - effect: NoSchedule
        key: dedicated
        value: test-team

Створіть Deployment:

kubectl apply -f https://k8s.io/examples/application/deployment-patch.yaml

Перегляньте Podʼи, повʼязані з вашим Deployment:

kubectl get pods

Вивід показує, що Deployment має два Podʼи. 1/1 вказує на те, що кожен Pod має один контейнер:

NAME                        READY     STATUS    RESTARTS   AGE
patch-demo-28633765-670qr   1/1       Running   0          23s
patch-demo-28633765-j5qs3   1/1       Running   0          23s

Запишіть назви запущених Podʼів. Пізніше ви побачите, що ці Podʼи будуть завершені й замінені новими.

На цей момент кожен Pod має один контейнер, який запускає образ nginx. Тепер припустимо, що ви хочете, щоб кожен Pod мав два контейнери: один запускає nginx, а інший — redis.

Створіть файл з назвою patch-file.yaml із таким вмістом:

spec:
  template:
    spec:
      containers:
      - name: patch-demo-ctr-2
        image: redis

Застосуйте патч до вашого Deployment:

kubectl patch deployment patch-demo --patch-file patch-file.yaml

Перегляньте Deployment після накладання патчу:

kubectl get deployment patch-demo --output yaml

Вивід показує, що PodSpec у Deployment має два контейнери:

containers:
- image: redis
  imagePullPolicy: Always
  name: patch-demo-ctr-2
  ...
- image: nginx
  imagePullPolicy: Always
  name: patch-demo-ctr
  ...

Перегляньте Podʼи, повʼязані з вашим Deployment після накладання патчу:

kubectl get pods

Вивід показує, що запущені Podʼи мають інші назви, ніж Podʼи, які працювали раніше. Deployment завершив старі Podʼи й створив два нові Podʼи, що відповідають оновленій специфікації Deployment. 2/2 вказує на те, що кожен Pod має два контейнери:

NAME                          READY     STATUS    RESTARTS   AGE
patch-demo-1081991389-2wrn5   2/2       Running   0          1m
patch-demo-1081991389-jmg7b   2/2       Running   0          1m

Придивіться уважніше до одного з Podʼів patch-demo:

kubectl get pod <your-pod-name> --output yaml

Вивід показує, що Pod має два контейнери: один, який запускає nginx, і один, який запускає redis:

containers:
- image: redis
  ...
- image: nginx
  ...

Примітки щодо strategic merge patch

Патч, який ви виконали в попередній вправі, називається strategic merge patch. Зверніть увагу, що патч не замінив список containers. Натомість він додав до списку новий контейнер. Іншими словами, список у патчі обʼєднано з наявним списком. Так відбувається не завжди, коли ви застосовуєте strategic merge patch до списку. У деяких випадках список замінюється, а не обʼєднується.

Під час strategic merge patch список або замінюється, або обʼєднується залежно від його стратегії патча. Стратегія патча задається значенням ключа patchStrategy у теґу поля у вихідному коді Kubernetes. Наприклад, поле Containers структури PodSpec має patchStrategy зі значенням merge:

type PodSpec struct {
  ...
  Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" ...`
  ...
}

Ви також можете побачити стратегію патча в специфікації OpenApi:

"io.k8s.api.core.v1.PodSpec": {
    ...,
    "containers": {
        "description": "List of containers belonging to the pod.  ...."
    },
    "x-kubernetes-patch-merge-key": "name",
    "x-kubernetes-patch-strategy": "merge"
}

І ви можете побачити стратегію патча в документації Kubernetes API.

Створіть файл з назвою patch-file-tolerations.yaml із таким вмістом:

spec:
  template:
    spec:
      tolerations:
      - effect: NoSchedule
        key: disktype
        value: ssd

Застосуйте патч до вашого Deployment:

kubectl patch deployment patch-demo --patch-file patch-file-tolerations.yaml

Перегляньте Deployment після накладання патчу:

kubectl get deployment patch-demo --output yaml

Вивід показує, що PodSpec у Deployment має лише один Toleration:

tolerations:
- effect: NoSchedule
  key: disktype
  value: ssd

Зверніть увагу, що список tolerations у PodSpec замінено, а не обʼєднано. Це тому, що поле Tolerations у PodSpec не має ключа patchStrategy у своєму теґу поля. Тож strategic merge patch використовує стандартну стратегію патча, тобто replace.

type PodSpec struct {
  ...
  Tolerations []Toleration `json:"tolerations,omitempty" protobuf:"bytes,22,opt,name=tolerations"`
  ...
}

Використання JSON merge patch для оновлення Deployment

Strategic merge patch відрізняється від JSON merge patch. Якщо під час JSON merge patch потрібно оновити список, слід вказати весь новий список. Новий список повністю замінює наявний.

Команда kubectl patch має параметр type, який ви можете встановити на одне з цих значень:

Значення параметраТип злиття
jsonJSON Patch, RFC 6902
mergeJSON Merge Patch, RFC 7386
strategicStrategic merge patch

Порівняння JSON patch і JSON merge patch дивіться в JSON Patch and JSON Merge Patch.

Стандартне значення параметра type — strategic. Тож у попередній вправі ви виконали strategic merge patch.

Далі виконайте JSON merge patch для того самого Deployment. Створіть файл з назвою patch-file-2.yaml із таким вмістом:

spec:
  template:
    spec:
      containers:
      - name: patch-demo-ctr-3
        image: gcr.io/google-samples/hello-app:2.0

У вашій команді патча встановіть type на merge:

kubectl patch deployment patch-demo --type merge --patch-file patch-file-2.yaml

Перегляньте Deployment після накладання патчу:

kubectl get deployment patch-demo --output yaml

Список containers, який ви вказали у патчі, має лише один контейнер. Вивід показує, що ваш список з одним контейнером замінив наявний список containers.

spec:
  containers:
  - image: gcr.io/google-samples/hello-app:2.0
    ...
    name: patch-demo-ctr-3

Перегляньте запущені Podʼи:

kubectl get pods

У виводі ви можете побачити, що наявні Podʼи були завершені, а нові Podʼи — створені. 1/1 вказує на те, що кожен новий Pod працює лише з одним контейнером.

NAME                          READY     STATUS    RESTARTS   AGE
patch-demo-1307768864-69308   1/1       Running   0          1m
patch-demo-1307768864-c86dc   1/1       Running   0          1m

Використання strategic merge patch для оновлення Deployment зі стратегією retainKeys

Ось файл конфігурації для Deployment, що використовує стратегію RollingUpdate:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: retainkeys-demo
spec:
  selector:
    matchLabels:
      app: nginx
  strategy:
    rollingUpdate:
      maxSurge: 30%
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: retainkeys-demo-ctr
        image: nginx

Створіть Deployment:

kubectl apply -f https://k8s.io/examples/application/deployment-retainkeys.yaml

На цей момент Deployment створено і використовує стратегію RollingUpdate.

Створіть файл з назвою patch-file-no-retainkeys.yaml з таким вмістом:

spec:
  strategy:
    type: Recreate

Застосуйте патч до вашого Deployment:

kubectl patch deployment retainkeys-demo --type strategic --patch-file patch-file-no-retainkeys.yaml

У виводі ви побачите, що неможливо встановити type як Recreate, коли значення визначено для spec.strategy.rollingUpdate:

The Deployment "retainkeys-demo" is invalid: spec.strategy.rollingUpdate: Forbidden: may not be specified when strategy `type` is 'Recreate'

Щоб вилучити значення spec.strategy.rollingUpdate під час оновлення значення type, використовуйте стратегію retainKeys для strategic merge patch.

Створіть ще один файл з назвою patch-file-retainkeys.yaml з таким вмістом:

spec:
  strategy:
    $retainKeys:
    - type
    type: Recreate

Цим патчем ми вказуємо, що хочемо зберегти лише ключ type обʼєкта strategy. Таким чином, під час операції патча rollingUpdate буде вилучено.

Знову застосуйте патч до вашого Deployment з цим новим патчем:

kubectl patch deployment retainkeys-demo --type strategic --patch-file patch-file-retainkeys.yaml

Дослідіть вміст Deployment:

kubectl get deployment retainkeys-demo --output yaml

У виводі показано, що обʼєкт стратегії в Deployment більше не містить ключа rollingUpdate:

spec:
  strategy:
    type: Recreate
  template:

Примітки щодо strategic merge patch зі стратегією retainKeys

Патч, який ви виконали в попередній вправі, називається strategic merge patch зі стратегією retainKeys. Цей метод вводить нову директиву $retainKeys, що має такі стратегії:

  • Вона містить список рядків.
  • Усі поля, які потрібно зберегти, повинні бути присутні в списку $retainKeys.
  • Присутні поля буде обʼєднано з живим обʼєктом.
  • Всі відсутні поля будуть очищені під час застосування патча.
  • Усі поля у списку $retainKeys повинні бути надмножиною або такими ж, як і поля, що присутні в патчі.

Стратегія retainKeys працює не для всіх обʼєктів. Вона працює лише тоді, коли значення ключа patchStrategy у теґу поля у вихідному коді Kubernetes містить retainKeys. Наприклад, поле Strategy структури DeploymentSpec має patchStrategy зі значенням retainKeys:

type DeploymentSpec struct {
  ...
  // +patchStrategy=retainKeys
  Strategy DeploymentStrategy `json:"strategy,omitempty" patchStrategy:"retainKeys" ...`
  ...
}

Ви також можете побачити стратегію retainKeys в специфікації OpenApi:

"io.k8s.api.apps.v1.DeploymentSpec": {
    ...,
    "strategy": {
        "$ref": "#/definitions/io.k8s.api.apps.v1.DeploymentStrategy",
        "description": "The deployment strategy to use to replace existing pods with new ones.",
        "x-kubernetes-patch-strategy": "retainKeys"
    },
    ....
}

Також стратегію retainKeys можна побачити в документації Kubernetes API.

Альтернативні форми команди kubectl patch

Команда kubectl patch приймає YAML або JSON. Вона може приймати патч як файл або безпосередньо в командному рядку.

Створіть файл з назвою patch-file.json з таким вмістом:

{
   "spec": {
      "template": {
         "spec": {
            "containers": [
               {
                  "name": "patch-demo-ctr-2",
                  "image": "redis"
               }
            ]
         }
      }
   }
}

Наведені нижче команди еквівалентні:

kubectl patch deployment patch-demo --patch-file patch-file.yaml
kubectl patch deployment patch-demo --patch 'spec:\n template:\n  spec:\n   containers:\n   - name: patch-demo-ctr-2\n     image: redis'

kubectl patch deployment patch-demo --patch-file patch-file.json
kubectl patch deployment patch-demo --patch '{"spec": {"template": {"spec": {"containers": [{"name": "patch-demo-ctr-2","image": "redis"}]}}}}'

Оновлення кількості реплік обʼєкта за допомогою kubectl patch з --subresource

Прапорець --subresource=[subresource-name] використовується з командами kubectl, як-от get, patch, edit, apply і replace, для отримання та оновлення субресурсів status, scale і resize вказаних вами ресурсів. Ви можете вказати субресурс для будь-якого ресурсу API Kubernetes (вбудованого або CR), що має субресурс status, scale або resize.

Наприклад, Deployment має субресурси status і scale, тож ви можете використовувати kubectl, щоб отримати або змінити лише субресурс status Deployment.

Ось маніфест для Deployment, що має дві репліки:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2 # tells deployment to run 2 pods matching the template
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Створіть Deployment:

kubectl apply -f https://k8s.io/examples/application/deployment.yaml

Перегляньте Podʼи, повʼязані з вашим Deployment:

kubectl get pods -l app=nginx

У виводі видно, що Deployment має два Podʼи. Наприклад:

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-7fb96c846b-22567   1/1     Running   0          47s
nginx-deployment-7fb96c846b-mlgns   1/1     Running   0          47s

Тепер застосуйте патч до Deployment з прапорцем --subresource=[subresource-name]:

kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":3}}'

Вивід:

scale.autoscaling/nginx-deployment patched

Перегляньте Podʼи, повʼязані з вашим Deployment після патчу:

kubectl get pods -l app=nginx

У виводі видно, що створено один новий Pod, тож тепер у вас 3 запущені Podʼи.

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-7fb96c846b-22567   1/1     Running   0          107s
nginx-deployment-7fb96c846b-lxfr2   1/1     Running   0          14s
nginx-deployment-7fb96c846b-mlgns   1/1     Running   0          107s

Перегляньте Deployment після патчу:

kubectl get deployment nginx-deployment -o yaml
...
spec:
  replicas: 3
  ...
status:
  ...
  availableReplicas: 3
  readyReplicas: 3
  replicas: 3

Примітка:

Якщо ви запускаєте kubectl patch і вказуєте прапорець --subresource для ресурсу, який не підтримує цей конкретний субресурс, API-сервер повертає помилку 404 Not Found.

Підсумки

У цій вправі ви використали kubectl patch, щоб змінити живу конфігурацію обʼєкта Deployment. Ви не змінювали файл конфігурації, за допомогою якого спочатку створили обʼєкт Deployment. Інші команди для оновлення обʼєктів API: kubectl annotate, kubectl edit, kubectl replace, kubectl scale і kubectl apply.

Примітка:

Strategic merge patch не підтримується для власних ресурсів.

Що далі

6 - Міграція обʼєктів Kubernetes за допомогою міграції версій сховища

СТАН ФУНКЦІОНАЛУ: Beta since Kubernetes v1.35; (стандартно вимкнено)
More information about this feature

To use this feature, you (or a cluster administrator) will need to enable the StorageVersionMigrator feature gate for all relevant components in your cluster.

See Enable Or Disable Feature Gates for more information.

Kubernetes покладається на активне переписування даних API для підтримки деяких операцій обслуговування, повʼязаних зі зберіганням у стані спокою. Два помітні приклади — версійна схема збережених ресурсів (тобто зміна бажаної схеми зберігання з v1 на v2 для певного ресурсу) та шифрування у стані спокою (тобто перезапис застарілих даних через зміну способу шифрування даних).

Виконання міграції версій сховища гарантує, що всі обʼєкти ресурсу перенесено із застарілої версії сховища. Вимога до виконання міграції сховища — ресурс повинен мати цілочисельну версію ресурсу. Усі ресурси Kubernetes і CRD гарантовано мають цю властивість, але міграція завершиться збоєм, якщо це не так, наприклад для агрегованих API.

Перш ніж ви розпочнете

Встановіть kubectl.

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Версія вашого Kubernetes сервера має бути не старішою ніж v1.30.

Для перевірки версії введіть kubectl version.

Функціональна можливість StorageVersionMigrator та REST API storagemigration.k8s.io/v1 стандартно увімкнені в усіх кластерах.

Повторне шифрування Secrets Kubernetes за допомогою міграції версій сховища

  • Спочатку налаштуйте постачальника KMS для шифрування даних у стані спокою в etcd за допомогою такої конфігурації шифрування.

    kind: EncryptionConfiguration
    apiVersion: apiserver.config.k8s.io/v1
    resources:
    - resources:
      - secrets
      providers:
      - aescbc:
          keys:
          - name: key1
            secret: c2VjcmV0IGlzIHNlY3VyZQ==
    

    Обовʼязково увімкніть автоматичне перезавантаження файлу конфігурації шифрування, встановивши --encryption-provider-config-automatic-reload у true.

  • Створіть Secret за допомогою kubectl.

    kubectl create secret generic my-secret --from-literal=key1=supersecret
    
  • Перевірте, що серіалізовані дані цього обʼєкта Secret починаються з k8s:enc:aescbc:v1:key1.

  • Оновіть файл конфігурації шифрування таким чином, щоб виконати ротацію ключа шифрування.

    kind: EncryptionConfiguration
    apiVersion: apiserver.config.k8s.io/v1
    resources:
    - resources:
      - secrets
      providers:
      - aescbc:
          keys:
          - name: key2
            secret: c2VjcmV0IGlzIHNlY3VyZSwgaXMgaXQ/
      - aescbc:
          keys:
          - name: key1
            secret: c2VjcmV0IGlzIHNlY3VyZQ==
    
  • Щоб забезпечити повторне шифрування раніше створеного Secret my-secret новим ключем key2, ви використаєте Storage Version Migration.

  • Створіть маніфест StorageVersionMigration з назвою migrate-secret.yaml з таким вмістом:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: secrets-migration
    spec:
      resource:
        group: ""
        resource: secrets
    

    Створіть обʼєкт за допомогою kubectl таким чином:

    kubectl apply -f migrate-secret.yaml
    
  • Стежте за міграцією Secrets, перевіряючи .status обʼєкта StorageVersionMigration. Успішна міграція повинна мати стан Succeeded зі значенням true. Отримайте обʼєкт StorageVersionMigration таким чином:

    kubectl wait --for=condition=Succeeded storageversionmigration.storagemigration.k8s.io/secrets-migration
    

    Вивід подібний до такого:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: secrets-migration
      uid: 628f6922-a9cb-4514-b076-12d3c178967c
      resourceVersion: "90"
      creationTimestamp: "2024-03-12T20:29:45Z"
    spec:
      resource:
        group: ""
        resource: secrets
    status:
      conditions:
      - type: Running
        status: "False"
        lastUpdateTime: "2024-03-12T20:29:46Z"
        reason: StorageVersionMigrationInProgress
      - type: Succeeded
        status: "True"
        lastUpdateTime: "2024-03-12T20:29:46Z"
        reason: StorageVersionMigrationSucceeded
      resourceVersion: "84"
    
  • Перевірте, що збережений Secret тепер починається з k8s:enc:aescbc:v1:key2.

Оновлення бажаної схеми зберігання CRD

Розгляньмо сценарій, у якому CustomResourceDefinition (CRD) створено для обслуговування власних ресурсів (CR) і встановлено як бажану схему зберігання. Коли настане час ввести v2 CRD, її можна додати лише для обслуговування за допомогою вебхука конвертації. Це забезпечує плавніший перехід, за якого користувачі можуть створювати CR за схемою v1 або v2, а вебхук виконує потрібну конвертацію схеми між ними. Перш ніж встановити v2 як бажану версію схеми зберігання, важливо переконатися, що всі наявні CR, збережені як v1, мігровано на v2. Цю міграцію можна виконати за допомогою Storage Version Migration, щоб перенести всі CR з v1 на v2.

  • Створіть маніфест для CRD з назвою test-crd.yaml з таким вмістом:

    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: selfierequests.example.com
    spec:
      group: example.com
      names:
        plural: selfierequests
        singular: selfierequest
        kind: SelfieRequest
        listKind: SelfieRequestList
      scope: Namespaced
      versions:
      - name: v1
        served: true
        storage: true
        schema:
          openAPIV3Schema:
            type: object
            properties:
              hostPort:
                type: string
      conversion:
        strategy: Webhook
        webhook:
          clientConfig:
            url: "https://127.0.0.1:9443/crdconvert"
            caBundle: <CABundle info>
        conversionReviewVersions:
        - v1
        - v2
    

    Збережена версія на цей момент має бути v1, переконайтеся в цьому, виконавши:

    kubectl get crd selfierequests.example.com -o jsonpath='{.spec.versions[?(@.storage==true)].name}'
    

    Створіть CRD за допомогою kubectl:

    kubectl apply -f test-crd.yaml
    
  • Створіть маніфест для прикладу testcrd. Назвіть маніфест cr1.yaml і використайте такий вміст:

    apiVersion: example.com/v1
    kind: SelfieRequest
    metadata:
      name: cr1
      namespace: default
    

    Створіть CR за допомогою kubectl:

    kubectl apply -f cr1.yaml
    
  • Перевірте, що CR записано і збережено як v1, отримавши обʼєкт з etcd.

    ETCDCTL_API=3 etcdctl get /kubernetes.io/example.com/testcrds/default/cr1 [...] | hexdump -C
    

    де [...] містить додаткові аргументи для зʼєднання із сервером etcd.

  • Оновіть CRD test-crd.yaml, щоб додати версію v2 для обслуговування й зберігання, а v1 залишити лише для обслуговування, таким чином:

    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: selfierequests.example.com
    spec:
      group: example.com
      names:
        plural: selfierequests
        singular: selfierequest
        kind: SelfieRequest
        listKind: SelfieRequestList
      scope: Namespaced
      versions:
        - name: v2
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                host:
                  type: string
                port:
                  type: string
        - name: v1
          served: true
          storage: false
          schema:
            openAPIV3Schema:
              type: object
              properties:
                hostPort:
                  type: string
      conversion:
        strategy: Webhook
        webhook:
          clientConfig:
            url: "https://127.0.0.1:9443/crdconvert"
            caBundle: <CABundle info>
          conversionReviewVersions:
            - v1
            - v2
    

    Збережена версія тепер має бути v2, переконайтеся в цьому:

    kubectl get crd selfierequests.example.com -o jsonpath='{.spec.versions[?(@.storage==true)].name}'
    

    Оновіть CRD за допомогою kubectl:

    kubectl apply -f test-crd.yaml
    
  • Створіть файл ресурсу CR з назвою cr2.yaml з таким вмістом:

    apiVersion: example.com/v2
    kind: SelfieRequest
    metadata:
      name: cr2
      namespace: default
    
  • Створіть CR за допомогою kubectl:

    kubectl apply -f cr2.yaml
    
  • Перевірте, що CR записано і збережено як v2, отримавши обʼєкт з etcd.

    ETCDCTL_API=3 etcdctl get /kubernetes.io/example.com/testcrds/default/cr2 [...] | hexdump -C
    

    де [...] містить додаткові аргументи для зʼєднання із сервером etcd.

  • Створіть маніфест StorageVersionMigration з назвою migrate-crd.yaml з таким вмістом:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: crdsvm
    spec:
      resource:
        group: example.com
        resource: selfierequests
    

    Створіть обʼєкт за допомогою kubectl таким чином:

    kubectl apply -f migrate-crd.yaml
    
  • Стежте за міграцією Secrets за допомогою статусу. Успішна міграція повинна мати стан Succeeded зі значенням "True" у полі статусу. Отримайте ресурс міграції таким чином:

    kubectl get storageversionmigration.storagemigration.k8s.io/crdsvm -o yaml
    

    Вивід подібний до такого:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: crdsvm
      uid: 13062fe4-32d7-47cc-9528-5067fa0c6ac8
      resourceVersion: "111"
      creationTimestamp: "2024-03-12T22:40:01Z"
    spec:
      resource:
        group: example.com
        resource: testcrds
    status:
      conditions:
        - type: Running
          status: "False"
          lastUpdateTime: "2024-03-12T22:40:03Z"
          reason: StorageVersionMigrationInProgress
        - type: Succeeded
          status: "True"
          lastUpdateTime: "2024-03-12T22:40:03Z"
          reason: StorageVersionMigrationSucceeded
      resourceVersion: "106"
    
  • Перевірте, що раніше створений cr1 тепер записано й збережено як v2, отримавши обʼєкт з etcd.

    ETCDCTL_API=3 etcdctl get /kubernetes.io/example.com/testcrds/default/cr1 [...] | hexdump -C
    

    де [...] містить додаткові аргументи для зʼєднання із сервером etcd.

  • Також перевірте, що статус збереженої версії CRD тепер лише v2:

    kubectl get crd testcrds.example.com -o yaml
    

    Вивід подібний до такого:

    kind: CustomResourceDefinition
    apiVersion: apiextensions.k8s.io/v1
    metadata:
      name: testcrds.example.com
    spec:
      group: example.com
      names:
        kind: TestCRD
        plural: testcrds
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: false
        - name: v2
          served: true
          storage: true
    status:
      acceptedNames:
        kind: TestCRD
        plural: testcrds
      conditions:
        - type: Established
          status: "True"
      storedVersions:
        - v2