# Server-Side Apply
LLMS index: [llms.txt](/llms.txt)
---
СТАН ФУНКЦІОНАЛУ:
Kubernetes v1.22 [stable](стандартно увімкнено)
Kubernetes підтримує співпрацю кількох аплікаторів для керування полями одного [обʼєкта](/docs/concepts/overview/working-with-objects/).
Server-Side Apply (Серверне застосування) надає необовʼязковий механізм для контролера вашого кластера, щоб відстежувати зміни в полях обʼєкта. На рівні конкретного ресурсу, Server-Side Apply записує та відстежує інформацію про контроль над полями цього обʼєкта.
Server-Side Apply допомагає користувачам та контролерам керувати своїми ресурсами за допомогою декларативної конфігурації. Клієнти можуть створювати та змінювати обʼєкти декларативно, подаючи їх _повністю визначений намір_.
Повністю визначений намір — це частковий обʼєкт, який містить лише ті поля та значення, щодо яких у користувача є чітке уявлення. Цей намір або створює новий обʼєкт (використовуючи стандартні значення для невизначених полів), або [обʼєднується](#merge-strategy) з наявним обʼєктом через API сервер.
[Порівняння з Client-Side Apply](#comparison-with-client-side-apply) пояснює, як Server-Side Apply відрізняється від початкової реалізації `kubectl apply` на стороні клієнта.
## Управління полями {#field-management}
Kubernetes API сервер відстежує _керовані поля_ для всіх новостворених обʼєктів.
При спробі застосувати обʼєкт, поля, які мають інше значення і належать іншому [менеджеру](#managers), спричинять [конфлікт](#conflicts). Це зроблено для того, щоб сигналізувати, що операція може скасувати зміни іншого спільника. Записи до обʼєктів з керованими полями можуть бути примусовими, в такому випадку значення будь-якого конфліктного поля буде перезаписане, а право власності передане.
Кожного разу, коли значення поля змінюється, право власності переходить від поточного менеджера до менеджера, що здійснює зміну.
Для того, щоб користувач міг керувати полем в контексті Server-Side Apply, він повинен покладатися на те, що значення поля не зміниться. Користувач, який останнім висловив свою думку щодо значення поля, буде записаний як поточний менеджер поля. Це можна зробити, змінивши дані менеджера поля явним чином за допомогою HTTP `POST` (**створення**), `PUT` (**оновлення**), або не-застосувального `PATCH` (**патч**). Ви також можете оголосити та записати менеджера поля, включивши значення для цього поля в операції Server-Side Apply.
Запит на **патч** в контексті Server-Side Apply вимагає від клієнта вказати свою ідентичність як [менеджера поля](#managers). При використанні Server-Side Apply спроба змінити поле, що контролюється іншим менеджером, призведе до відхилення запиту, якщо клієнт не виконає примусове перевизначення. Для деталей щодо примусових перевизначень дивіться [Конфлікти](#conflicts).
Коли два або більше аплікатора встановлюють поле на однакове значення, вони спільно володіють цим полем. Будь-яка спроба змінити значення спільного поля будь-ким з аплікаторів призведе до конфлікту. Спільні власники поля можуть відмовитися від права власності на поле, здійснивши запит на **патч** в контексті Server-Side Apply, який не включає це поле.
Деталі управління полями зберігаються в полі `managedFields`, яке є частиною [`metadata`](/docs/reference/kubernetes-api/common-definitions/object-meta/) обʼєкта.
Якщо ви видалите поле з маніфесту і застосуєте цей маніфест, Server-Side Apply перевірить, чи є інші менеджери полів, які також володіють цим полем. Якщо поле не належить жодному іншому менеджеру полів, воно буде або видалене з поточного обʼєкта, або скинуте до стандартного значення, якщо таке є. Те саме правило застосовується до елементів асоціативного списку або map.
У порівнянні з (застарілою) [`kubectl.kubernetes.io/last-applied-configuration`](/docs/reference/labels-annotations-taints/#kubectl-kubernetes-io-last-applied-configuration) анотацією, яка управляється `kubectl`, Server-Side Apply використовує більш декларативний підхід, який відстежує управління полями користувача (або клієнта), а не останній застосований стан користувача. Побічним ефектом використання Server-Side Apply є також доступність інформації про те, який менеджер поля управляє кожним полем в обʼєкті.
### Приклад {#ssa-example-configmap}
Простий приклад обʼєкта, створеного за допомогою Server-Side Apply, може виглядати так:
Примітка:
kubectl get типово пропускає керовані поля. Додайте --show-managed-fields щоб показати managedFields у виводі в формаі json або yaml.
```yaml
---
apiVersion: v1
kind: ConfigMap
metadata:
name: test-cm
namespace: default
labels:
test-label: test
managedFields:
- manager: kubectl
operation: Apply # зверніть увагу на великі літери: "Apply" (або "Update")
apiVersion: v1
time: "2010-10-10T0:00:00Z"
fieldsType: FieldsV1
fieldsV1:
f:metadata:
f:labels:
f:test-label: {}
f:data:
f:key: {}
data:
key: some value
```
Цей приклад обʼєкта ConfigMap містить один запис про управління полями в `.metadata.managedFields`. Запис управління полями складається з основної інформації про саму сутність, що виконує управління, а також з деталей про поля, якими управляють, та відповідну операцію (`Apply` або `Update`). Якщо запит, що останнім змінив це поле, був **патчем** Server-Side Apply, тоді значення `operation` буде `Apply`; в іншому випадку, це буде `Update`.
Є ще один можливий результат. Клієнт може подати недійсний запит. Якщо повністю зазначений намір не створює дійсний обʼєкт, запит не вдасться виконати.
Однак, можливо змінити `.metadata.managedFields` за допомогою операції **оновлення** або **патчу**, які не використовують Server-Side Apply. Це наполегливо не рекомендується, але може бути доцільно спробувати, якщо, наприклад, `.metadata.managedFields` потрапить у неконсистентний стан (що не повинно відбуватися при нормальній роботі).
Формат `managedFields` описаний у [довіднику API Kubernetes](/docs/reference/kubernetes-api/common-definitions/object-meta/#System).
Увага:
Поле .metadata.managedFields керується API сервером. Ви повинні уникати його ручного оновлення.
### Конфлікти {#conflicts}
_Конфлікт_ — це спеціальна помилка статусу, яка виникає, коли операція `Apply` намагається змінити поле, на яке інший менеджер також заявляє права на керування. Це запобігає ненавмисному перезапису значення, встановленого іншим користувачем. У разі конфлікту аплікатор має 3 варіанти для вирішення конфліктів:
* **Перезаписати значення, стати єдиним менеджером:** Якщо перезапис значення був навмисним (або якщо аплікатор є автоматичним процесом, таким як контролер), аплікатор повинен встановити параметр запиту `force` в `true` (для `kubectl apply` використовується параметр командного рядка `--force-conflicts`) і повторити запит. Це змусить операцію завершитись успішно, змінить значення поля та видалить це поле з усіх інших записів менеджерів у `managedFields`.
* **Не перезаписувати значення, відмовитися від права управління:** Якщо аплікатор більше не піклується про значення поля, він може видалити його зі своєї локальної моделі ресурсу і зробити новий запит, виключивши це конкретне поле. Це залишить значення незмінним і видалить поле із запису аплікатора у `managedFields`.
* **Не перезаписувати значення, стати спільним менеджером:** Якщо аплікатор все ще піклується про значення поля, але не хоче його перезаписувати, він може змінити значення цього поля у своїй локальній моделі ресурсу, щоб відповідати значенню обʼєкта на сервері, а потім зробити новий запит, враховуючи це локальне оновлення. Це залишить значення незмінним і зробить це поле керованим спільно аплікатором та всіма іншими менеджерами, які вже заявили про керування ним.
### Менеджери полів {#managers}
Менеджери визначають окремі робочі процеси, які змінюють обʼєкт (особливо корисно при конфліктах!), і можуть бути вказані через параметр запиту [`fieldManager`](/docs/reference/kubernetes-api/common-parameters/common-parameters/#fieldManager) як частина запиту на зміни. Коли ви застосовуєте зміни до ресурсу, параметр `fieldManager` є обовʼязковим. Для інших оновлень сервер API визначає ідентифікатор менеджера поля з заголовка HTTP "User-Agent:" (якщо він присутній).
Коли ви використовуєте інструмент `kubectl` для виконання операції Server-Side Apply, `kubectl` типово встановлює ідентифікатор менеджера в `"kubectl"`.
## Серіалізація {#serialization}
На рівні протоколу Kubernetes представляє тіла повідомлень Server-Side Apply у форматі [YAML](https://yaml.org/), з медіа типом `application/apply-patch+yaml`.
Примітка:
Незалежно від того, чи ви подаєте дані у форматі JSON чи YAML, використовуйте application/apply-patch+yaml як значення заголовка Content-Type.
Усі документи JSON є дійсними документами YAML. Однак, у Kubernetes є помилка, яка полягає в тому, що він використовує парсер YAML, який не повністю реалізує специфікацію YAML. Деякі JSON екранування можуть не бути розпізнаними.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
labels:
app: nginx
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.14.2
І користувач створив Deployment, використовуючи Server-Side Apply, наступним чином:
```shell
kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment.yaml --server-side
```
Пізніше автоматичне масштабування увімкнено для Deployment; наприклад:
```shell
kubectl autoscale deployment nginx-deployment --cpu=50% --min=1 --max=10
```
Тепер користувач хоче видалити `replicas` з конфігурації, щоб вони випадково не конфліктували з HorizontalPodAutoscaler (HPA) та його контролером. Однак виникають перегони: може пройти деякий час, перш ніж HPA вирішить змінити `.spec.replicas`; якщо користувач видаляє `.spec.replicas` перед тим, як HPA запише в поле і стане його власником, тоді API-сервер встановить `.spec.replicas` на 1 (стандартна кількість реплік для Deployment). Це не те, що хоче користувач, ще й тимчасово — це може погіршити робоче навантаження.
Є два рішення:
* (базовий) Залиште `replicas` в конфігурації; коли HPA нарешті запише в це поле, система сповістить користувачу про конфлікт при спробі зробити це. На цьому етапі безпечно видалити його з конфігурації.
* (більш розширений) Однак, якщо користувач не хоче чекати, наприклад, через те що вони хочуть, щоб кластер був зрозумілим для їх колег, тоді вони можуть виконати наступні кроки, щоб зробити видалення `replicas` з їх конфігурації безпечним:
Спочатку користувач визначає новий маніфест, що містить лише поле `replicas`:
```yaml
# Збережіть цей файл як 'nginx-deployment-replicas-only.yaml'.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
```
Примітка:
Файл YAML для SSA у цьому випадку містить лише поля, які ви хочете змінити. Вам не слід надавати повністю сумісний з Deployment маніфест, якщо ви хочете змінити лише поле spec.replicas, використовуючи SSA.
Користувач застосовує цей маніфест, використовуючи приватне імʼя менеджера полів. У цьому прикладі користувач вибрав `handover-to-hpa`:
```shell
kubectl apply -f nginx-deployment-replicas-only.yaml \
--server-side --field-manager=handover-to-hpa \
--validate=false
```
Якщо застосування призводить до конфлікту з контролером HPA, тоді нічого не робіть. Конфлікт вказує на те, що контролер вже вимагає поле на цьому етапі.
На цьому етапі користувач може видалити поле `replicas` з маніфесту:
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:1.14.2
Зауважте, що кожного разу, коли контролер HPA встановлює значення поля `replicas` на нове значення, тимчасовий менеджер полів більше не володіє жодними полями й буде автоматично видалений. Додаткового прибирання не потрібно.
### Передача власності між менеджерами {#transferring-ownership-between-managers}
Менеджери полів можуть передавати власність поля між собою, встановлюючи значення поля в тому самому значенні в обох їх застосованих конфігураціях, що призводить до того, що вони спільно володіють полем. Після цього менеджери можуть відмовитися від володіння полям та завершити передачу іншому менеджеру поля, видаливши поле з їх застосованої конфігурації.
## Порівняння з Client-Side Apply {#comparison-with-client-side-apply}
Server-Side Apply призначений як для заміни початкової реалізації команди `kubectl apply` на стороні клієнта, так і для забезпечення простого та ефективного механізму для контролерів, щоб впроваджувати свої зміни.
Порівняно з анотацією `last-applied`, якою керує `kubectl`, Server-Side Apply використовує більш декларативний підхід, що відстежує управління полями обʼєкта, а не останній стан, застосований користувачем. Це означає, що як побічний ефект використання Server-Side Apply, стає доступною інформація про те, який менеджер полів керує кожним полем в обʼєкті.
Наслідком виявлення та вирішення конфліктів, реалізованих у Server-Side Apply, є те, що аплікатор завжди має актуальні значення полів у своєму локальному стані. Якщо ні, то він отримає конфлікт під час наступного застосування. Будь-який з трьох варіантів розвʼязання конфліктів призводить до того, що застосована конфігурація стає актуальною підмножиною полів обʼєкта на сервері.
Це відрізняється від Client-Side Apply, де застарілі значення, які були перезаписані іншими користувачами, залишаються в локальній конфігурації аплікатора. Ці значення стають точними лише тоді, коли користувач оновлює конкретне поле, якщо взагалі оновлює, і аплікатор не має способу дізнатися, чи наступне застосування перезапише зміни інших користувачів.
Ще однією відмінністю є те, що аплікатор, використовуючи Client-Side Apply, не може змінити версію API, яку він використовує, тоді як Server-Side Apply підтримує цей випадок використання.
## Міграція між client-side і server-side apply {#migration-between-client-side-and-server-side-apply}
### Перехід з client-side apply на server-side apply {#migrating-from-client-side-to-server-side-apply}
Користувачі client-side apply, які керують ресурсом за допомогою `kubectl apply`, можуть почати використовувати server-side apply з наступним прапорцем.
```shell
kubectl apply --server-side [--dry-run=server]
```
Стандартно, управління полями обʼєкта переходить з client-side apply на kubectl server-side apply без виникнення конфліктів.
Увага:
Тримайте анотацію last-applied-configuration в актуальному стані. Анотація визначає поля, якими керує client-side apply. Будь-які поля, якими не керує client-side apply, викликають конфлікти.
Наприклад, якщо ви використовували kubectl scale для оновлення поля replicas після client-side apply, тоді це поле не належить client-side apply і створює конфлікти при kubectl apply --server-side.
Примітка:
Server-Side Apply не правильно відстежує власність на субресурси, які не отримують тип обʼєкта ресурсу. Якщо ви використовуєте Server-Side Apply з таким субресурсом, змінені поля можуть не відслідковуватися.
## Що далі
Ви можете прочитати про `managedFields` у довіднику API Kubernetes для верхнього рівня поля [`metadata`](/docs/reference/kubernetes-api/common-definitions/object-meta/).
