Довідник

• 1: Глосарій
• 2: Огляд API
• 2.1: Декларативна перевірка API
• 2.2: Концепції API Kubernetes
• 2.3: Server-Side Apply
• 2.4: Бібліотеки клієнтів
• 2.5: Загальна мова виразів у Kubernetes
• 2.6: Політика застарівання Kubernetes
• 2.7: Посібник з міграції від застарілих API
• 2.8: Точки доступу для моніторингу стану API Kubernetes
• 3: Управління доступом до API Kubernetes
• 3.1: Автентифікація
• 3.2: Автентифікація за допомогою Bootstrap-токенів
• 3.3: Авторизація
• 3.4: Використання RBAC авторизації
• 3.5: Використання авторизації вузлів
• 3.6: Режим Webhook
• 3.7: Використання ABAC авторизації
• 3.8: Контролери допуску в Kubernetes
• 3.9: Динамічне керування допуском
• 3.10: Імперсонізація користувача
• 3.11: Управління службовими обліковими записами
• 3.12: Сертифікати та запити на їх підписування
• 3.13: Зіставлення PodSecurityPolicies зі стандартами безпеки Podʼів
• 3.14: Автентифікація/авторизація kubelet
• 3.15: Початкове завантаження TLS
• 3.16: Змінювані політики допуску
• 3.17: Правила перевірки допуску
• 4: Відомі мітки, анотації та позначення
• 4.1: Анотації аудиту
• 5: API Kubernetes
• 5.1: Ресурси робочих навантажень
• 5.1.1: Pod
• 5.1.2: Binding
• 5.1.3: PodTemplate
• 5.1.4: ReplicationController
• 5.1.5: ReplicaSet
• 5.1.6: Deployment
• 5.1.7: StatefulSet
• 5.1.8: ControllerRevision
• 5.1.9: DaemonSet
• 5.1.10: Job
• 5.1.11: CronJob
• 5.1.12: HorizontalPodAutoscaler
• 5.1.13: HorizontalPodAutoscaler
• 5.1.14: PriorityClass
• 5.1.15: DeviceTaintRule v1alpha3
• 5.1.16: ResourceClaim v1
• 5.1.17: ResourceClaimTemplate v1
• 5.1.18: ResourceSlice v1
• 5.1.19: Workload v1alpha1
• 5.2: Ресурси Service
• 5.2.1: Service
• 5.2.2: Endpoints
• 5.2.3: EndpointSlice
• 5.2.4: Ingress
• 5.2.5: IngressClass
• 5.3: Ресурси конфігурації та зберігання
• 5.3.1: ConfigMap
• 5.3.2: Secret
• 5.3.3: CSIDriver
• 5.3.4: CSINode
• 5.3.5: CSIStorageCapacity
• 5.3.6: PersistentVolumeClaim
• 5.3.7: PersistentVolume
• 5.3.8: StorageClass
• 5.3.9: StorageVersionMigration v1beta1
• 5.3.10: Volume
• 5.3.11: VolumeAttachment
• 5.3.12: VolumeAttributesClass v1
• 5.4: Ресурси автентифікації
• 5.4.1: ServiceAccount
• 5.4.2: TokenRequest
• 5.4.3: TokenReview
• 5.4.4: CertificateSigningRequest
• 5.4.5: ClusterTrustBundle v1beta1
• 5.4.6: SelfSubjectReview
• 5.4.7: PodCertificateRequest v1beta1
• 5.5: Ресурси авторизації
• 5.5.1: LocalSubjectAccessReview
• 5.5.2: SelfSubjectAccessReview
• 5.5.3: SelfSubjectRulesReview
• 5.5.4: SubjectAccessReview
• 5.5.5: ClusterRole
• 5.5.6: ClusterRoleBinding
• 5.5.7: Role
• 5.5.8: RoleBinding
• 5.6: Ресурси політики
• 5.6.1: FlowSchema
• 5.6.2: LimitRange
• 5.6.3: ResourceQuota
• 5.6.4: NetworkPolicy
• 5.6.5: PodDisruptionBudget
• 5.6.6: PriorityLevelConfiguration
• 5.6.7: ValidatingAdmissionPolicy
• 5.6.8: ValidatingAdmissionPolicyBinding
• 5.6.9: MutatingAdmissionPolicy v1beta1
• 5.6.10: MutatingAdmissionPolicyBinding v1alpha1
• 5.7: Розширені ресурси
• 5.7.1: CustomResourceDefinition
• 5.7.2: DeviceClass
• 5.7.3: MutatingWebhookConfiguration
• 5.7.4: ValidatingWebhookConfiguration
• 5.8: Ресурси кластера
• 5.8.1: APIService
• 5.8.2: ComponentStatus
• 5.8.3: Event
• 5.8.4: IPAddress
• 5.8.5: Lease
• 5.8.6: LeaseCandidate v1beta1
• 5.8.7: Namespace
• 5.8.8: Node
• 5.8.9: RuntimeClass
• 5.8.10: ServiceCIDR
• 5.9: Загальні визначення
• 5.9.1: DeleteOptions
• 5.9.2: LabelSelector
• 5.9.3: ListMeta
• 5.9.4: LocalObjectReference.
• 5.9.5: NodeSelectorRequirement
• 5.9.6: ObjectFieldSelector
• 5.9.7: ObjectMeta
• 5.9.8: ObjectReference
• 5.9.9: Patch
• 5.9.10: Quantity
• 5.9.11: ResourceFieldSelector
• 5.9.12: Status
• 5.9.13: TypedLocalObjectReference
• 5.10: Other Resources
• 5.10.1: MutatingAdmissionPolicyBindingList v1beta1
• 5.11: Загальні параметри
• 6: Інструментування
• 6.1: Метрики SLI компонентів Kubernetes
• 6.2: Дані метрик вузла
• 6.3: Метрики Pod та Контейнерів CRI
• 6.4: Розуміння метрик Pressure Stall Information (PSI)
• 6.5: Kubernetes z-pages
• 6.6: Довідник Метрик Kubernetes
• 7: Безпека та проблеми Kubernetes
• 7.1: Трекер проблем Kubernetes
• 7.2: Процес розкриття інформації про безпеку в Kubernetes
• 7.3: Офіційний список CVE
• 8: Довідкова інформація про вузли
• 8.1: Kubelet Checkpoint API
• 8.2: Вимоги до версії ядра Linux
• 8.3: Статті про видалення dockershim та використання сумісних з CRI середовищ виконання
• 8.4: Мітки вузлів, які заповнює kubelet
• 8.5: Локальні файли та шляхи, які використовує Kubelet
• 8.6: Версії API Kubelet Device Manager
• 8.7: Обʼєднання конфігураційних тек Kubelet
• 8.8: Kubelet Systemd Watchdog
• 8.9: Seccomp та Kubernetes
• 8.10: Стан вузла
• 8.11: Поведінка свопу на вузлах Linux
• 9: Довідник з мережі
• 9.1: Протоколи Service
• 9.2: Порти та Протоколи
• 9.3: Віртуальні IP та Проксі для Service
• 10: Інструменти встановлення
• 10.1: Kubeadm
• 10.1.1: Kubeadm Generated
• 10.1.1.1:
• 10.1.1.2:
• 10.1.1.2.1:
• 10.1.1.2.2:
• 10.1.1.2.3:
• 10.1.1.2.4:
• 10.1.1.2.5:
• 10.1.1.2.6:
• 10.1.1.2.7:
• 10.1.1.2.8:
• 10.1.1.2.9:
• 10.1.1.2.10:
• 10.1.1.2.11:
• 10.1.1.2.12:
• 10.1.1.2.13:
• 10.1.1.2.14:
• 10.1.1.2.15:
• 10.1.1.2.16:
• 10.1.1.3:
• 10.1.1.4:
• 10.1.1.4.1:
• 10.1.1.4.2:
• 10.1.1.4.3:
• 10.1.1.4.4:
• 10.1.1.4.5:
• 10.1.1.4.6:
• 10.1.1.4.7:
• 10.1.1.4.8:
• 10.1.1.4.9:
• 10.1.1.4.10:
• 10.1.1.5:
• 10.1.1.5.1:
• 10.1.1.5.2:
• 10.1.1.5.3:
• 10.1.1.5.4:
• 10.1.1.5.5:
• 10.1.1.5.6:
• 10.1.1.5.7:
• 10.1.1.5.8:
• 10.1.1.5.9:
• 10.1.1.5.10:
• 10.1.1.5.11:
• 10.1.1.5.12:
• 10.1.1.5.13:
• 10.1.1.5.14:
• 10.1.1.5.15:
• 10.1.1.5.16:
• 10.1.1.5.17:
• 10.1.1.5.18:
• 10.1.1.5.19:
• 10.1.1.5.20:
• 10.1.1.5.21:
• 10.1.1.5.22:
• 10.1.1.5.23:
• 10.1.1.5.24:
• 10.1.1.5.25:
• 10.1.1.5.26:
• 10.1.1.5.27:
• 10.1.1.5.28:
• 10.1.1.5.29:
• 10.1.1.5.30:
• 10.1.1.5.31:
• 10.1.1.5.32:
• 10.1.1.5.33:
• 10.1.1.5.34:
• 10.1.1.5.35:
• 10.1.1.5.36:
• 10.1.1.5.37:
• 10.1.1.5.38:
• 10.1.1.5.39:
• 10.1.1.5.40:
• 10.1.1.5.41:
• 10.1.1.5.42:
• 10.1.1.5.43:
• 10.1.1.5.44:
• 10.1.1.5.45:
• 10.1.1.5.46:
• 10.1.1.6:
• 10.1.1.6.1:
• 10.1.1.6.2:
• 10.1.1.6.3:
• 10.1.1.6.4:
• 10.1.1.6.5:
• 10.1.1.6.6:
• 10.1.1.6.7:
• 10.1.1.6.8:
• 10.1.1.6.9:
• 10.1.1.6.10:
• 10.1.1.6.11:
• 10.1.1.6.12:
• 10.1.1.6.13:
• 10.1.1.6.14:
• 10.1.1.6.15:
• 10.1.1.6.16:
• 10.1.1.7:
• 10.1.1.7.1:
• 10.1.1.8:
• 10.1.1.8.1:
• 10.1.1.8.2:
• 10.1.1.8.3:
• 10.1.1.8.4:
• 10.1.1.9:
• 10.1.1.9.1:
• 10.1.1.9.2:
• 10.1.1.9.3:
• 10.1.1.9.4:
• 10.1.1.10:
• 10.1.1.10.1:
• 10.1.1.10.2:
• 10.1.1.10.3:
• 10.1.1.10.4:
• 10.1.1.10.5:
• 10.1.1.10.6:
• 10.1.1.10.7:
• 10.1.1.10.8:
• 10.1.1.10.9:
• 10.1.1.10.10:
• 10.1.1.10.11:
• 10.1.1.10.12:
• 10.1.1.10.13:
• 10.1.1.10.14:
• 10.1.1.10.15:
• 10.1.1.10.16:
• 10.1.1.10.17:
• 10.1.1.10.18:
• 10.1.1.10.19:
• 10.1.1.10.20:
• 10.1.1.10.21:
• 10.1.1.10.22:
• 10.1.1.10.23:
• 10.1.1.10.24:
• 10.1.1.10.25:
• 10.1.1.10.26:
• 10.1.1.10.27:
• 10.1.1.11:
• 10.1.2: kubeadm init
• 10.1.3: kubeadm join
• 10.1.4: kubeadm upgrade
• 10.1.5: kubeadm upgrade phase
• 10.1.6: kubeadm config
• 10.1.7: kubeadm reset
• 10.1.8: kubeadm token
• 10.1.9: kubeadm version
• 10.1.10: kubeadm alpha
• 10.1.11: kubeadm certs
• 10.1.12: kubeadm init phase
• 10.1.13: kubeadm join phase
• 10.1.14: kubeadm kubeconfig
• 10.1.15: kubeadm reset phase
• 10.1.16: Деталі реалізації
• 11: Інструмент командного рядка (kubectl)
• 11.1: Вступ до kubectl
• 11.2: Довідник kubectl
• 11.2.1: kubectl
• 11.2.2: kubectl alpha
• 11.2.2.1: kubectl alpha kuberc
• 11.2.2.2: kubectl alpha kuberc set
• 11.2.2.3: kubectl alpha kuberc view
• 11.2.3: kubectl annotate
• 11.2.4: kubectl api-resources
• 11.2.5: kubectl api-versions
• 11.2.6: kubectl apply
• 11.2.6.1: kubectl apply edit-last-applied
• 11.2.6.2: kubectl apply set-last-applied
• 11.2.6.3: kubectl apply view-last-applied
• 11.2.7: kubectl attach
• 11.2.8: kubectl auth
• 11.2.8.1: kubectl auth can-i
• 11.2.8.2: kubectl auth reconcile
• 11.2.8.3: kubectl auth whoami
• 11.2.9: kubectl autoscale
• 11.2.10: kubectl certificate
• 11.2.10.1: kubectl certificate approve
• 11.2.10.2: kubectl certificate deny
• 11.2.11: kubectl cluster-info
• 11.2.11.1: kubectl cluster-info dump
• 11.2.12: kubectl completion
• 11.2.13: kubectl config
• 11.2.13.1: kubectl config current-context
• 11.2.13.2: kubectl config delete-cluster
• 11.2.13.3: kubectl config delete-context
• 11.2.13.4: kubectl config delete-user
• 11.2.13.5: kubectl config get-clusters
• 11.2.13.6: kubectl config get-contexts
• 11.2.13.7: kubectl config get-users
• 11.2.13.8: kubectl config rename-context
• 11.2.13.9: kubectl config set
• 11.2.13.10: kubectl config set-cluster
• 11.2.13.11: kubectl config set-context
• 11.2.13.12: kubectl config set-credentials
• 11.2.13.13: kubectl config unset
• 11.2.13.14: kubectl config use-context
• 11.2.13.15: kubectl config view
• 11.2.14: kubectl cordon
• 11.2.15: kubectl cp
• 11.2.16: kubectl create
• 11.2.16.1: kubectl create clusterrole
• 11.2.16.2: kubectl create clusterrolebinding
• 11.2.16.3: kubectl create configmap
• 11.2.16.4: kubectl create cronjob
• 11.2.16.5: kubectl create deployment
• 11.2.16.6: kubectl create ingress
• 11.2.16.7: kubectl create job
• 11.2.16.8: kubectl create namespace
• 11.2.16.9: kubectl create poddisruptionbudget
• 11.2.16.10: kubectl create priorityclass
• 11.2.16.11: kubectl create quota
• 11.2.16.12: kubectl create role
• 11.2.16.13: kubectl create rolebinding
• 11.2.16.14: kubectl create secret
• 11.2.16.15: kubectl create secret docker-registry
• 11.2.16.16: kubectl create secret generic
• 11.2.16.17: kubectl create secret tls
• 11.2.16.18: kubectl create service
• 11.2.16.19: kubectl create service clusterip
• 11.2.16.20: kubectl create service externalname
• 11.2.16.21: kubectl create service loadbalancer
• 11.2.16.22: kubectl create service nodeport
• 11.2.16.23: kubectl create serviceaccount
• 11.2.16.24: kubectl create token
• 11.2.17: kubectl debug
• 11.2.18: kubectl delete
• 11.2.19: kubectl describe
• 11.2.20: kubectl diff
• 11.2.21: kubectl drain
• 11.2.22: kubectl edit
• 11.2.23: kubectl events
• 11.2.24: kubectl exec
• 11.2.25: kubectl explain
• 11.2.26: kubectl expose
• 11.2.27: kubectl get
• 11.2.28: kubectl kustomize
• 11.2.29: kubectl label
• 11.2.30: kubectl logs
• 11.2.31: kubectl options
• 11.2.32: kubectl patch
• 11.2.33: kubectl plugin
• 11.2.33.1: kubectl plugin list
• 11.2.34: kubectl port-forward
• 11.2.35: kubectl proxy
• 11.2.36: kubectl replace
• 11.2.37: kubectl rollout
• 11.2.37.1: kubectl rollout history
• 11.2.37.2: kubectl rollout pause
• 11.2.37.3: kubectl rollout restart
• 11.2.37.4: kubectl rollout resume
• 11.2.37.5: kubectl rollout status
• 11.2.37.6: kubectl rollout undo
• 11.2.38: kubectl run
• 11.2.39: kubectl scale
• 11.2.40: kubectl set
• 11.2.40.1: kubectl set env
• 11.2.40.2: kubectl set image
• 11.2.40.3: kubectl set resources
• 11.2.40.4: kubectl set selector
• 11.2.40.5: kubectl set serviceaccount
• 11.2.40.6: kubectl set subject
• 11.2.41: kubectl taint
• 11.2.42: kubectl top
• 11.2.42.1: kubectl top node
• 11.2.42.2: kubectl top pod
• 11.2.43: kubectl uncordon
• 11.2.44: kubectl version
• 11.2.45: kubectl wait
• 11.3: Швидкий довідник kubectl
• 11.4: Команди kubectl
• 11.5: kubectl
• 11.6: Підтримка JSONPath
• 11.7: kubectl для користувачів Docker
• 11.8: Правила використання kubectl
• 11.9: Налаштування користувача для kubectl (kuberc)
• 12: Кодування
• 12.1: Довідник KYAML
• 13: Компоненти інструментів
• 13.1: Функціональні можливості
• 13.2: Функціональні можливості (вилучені)
• 13.3: kube-apiserver
• 13.4: kube-controller-manager
• 13.5: kube-proxy
• 13.6: kube-scheduler
• 13.7: kubelet
• 14: Відлагодження кластера
• 14.1: Керування потоком
• 15: Конфігураційні API
• 15.1: Client Authentication (v1)
• 15.2: Client Authentication (v1beta1)
• 15.3: Event Rate Limit Configuration (v1alpha1)
• 15.4: Image Policy API (v1alpha1)
• 15.5: kube-apiserver Admission (v1)
• 15.6: kube-apiserver Audit Configuration (v1)
• 15.7: kube-apiserver Configuration (v1)
• 15.8: kube-apiserver Configuration (v1alpha1)
• 15.9: kube-apiserver Configuration (v1beta1)
• 15.10: kube-controller-manager Configuration (v1alpha1)
• 15.11: kube-proxy Configuration (v1alpha1)
• 15.12: kube-scheduler Configuration (v1)
• 15.13: kubeadm Configuration (v1beta3)
• 15.14: kubeadm Configuration (v1beta4)
• 15.15: kubeconfig (v1)
• 15.16: Kubelet Configuration (v1)
• 15.17: Kubelet Configuration (v1alpha1)
• 15.18: Kubelet Configuration (v1beta1)
• 15.19: Kubelet CredentialProvider (v1)
• 15.20: kuberc (v1alpha1)
• 15.21: kuberc (v1beta1)
• 15.22: WebhookAdmission Configuration (v1)
• 16: Зовнішні API
• 16.1: Kubernetes Custom Metrics (v1beta2)
• 16.2: Kubernetes External Metrics (v1beta1)
• 16.3: Kubernetes Metrics (v1beta1)
• 17: Планування
• 17.1: Налаштування Планувальника
• 17.2: Політики планування
• 18: Інші інструменти

1 - Глосарій

2 - Огляд API

Цей розділ містить довідкову інформацію про API Kubernetes.

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

Довідник API Kubernetes містить список API для версії Kubernetes v1.35.

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

Версіювання API

Схеми серіалізації JSON та Protobuf слідують однаковими принципами для змін схеми. Наступні описи стосуються обох форматів.

Версіювання API та версіювання програмного забезпечення непрямо повʼязані. Пропозиція з версіювання API та релізів описує відносини між версіюванням API та версіюванням програмного забезпечення.

Різні версії API вказують на різні рівні стабільності та підтримки. Докладнішу інформацію про критерії кожного рівня можна знайти в документації API Changes.

Ось короткий огляд кожного рівня:

• Alpha:

  • Назви версій містять alpha (наприклад, v1alpha1).
  • Вбудовані версії API рівня alpha типово вимкнені та повинні бути явно увімкнені в конфігурації kube-apiserver для використання.
  • Програмне забезпечення може містити помилки. Увімкнення функції може виявити помилки.
  • Підтримка alpha API може бути відключена в будь-який момент без попередження.
  • API може змінитися несумісним чином у подальших версіях програмного забезпечення без попередження.
  • Рекомендується використовувати програмне забезпечення тільки в тестових кластерах для короткочасного тестування через збільшений ризик помилок та відсутність довгострокової підтримки.

• Beta:

  • Назви версій містять beta (наприклад, v2beta3).

  • Вбудовані версії API рівня beta типово вимкнені та повинні бути явно увімкнені в конфігурації kube-apiserver для використання (за винятком бета-версій API, представлених до Kubernetes 1.22, які були типово увімкнені).

  • Вбудовані версії API рівня beta мають максимальний термін служби 9 місяців або 3 мінорні випуски (в залежності, що довше), починаючи від введення до застаріння, і 9 місяців або 3 мінорні випуски (в залежності, що довше) від застаріння до вилучення.

  • Програмне забезпечення добре протестоване. Увімкнення функції вважається безпечним.

  • Підтримка функції не буде відключена, хоча можуть змінитися деталі.

  • Схема та/або семантика обʼєктів може змінюватися несумісним чином у подальших версіях API рівня beta або стабільного. Коли це відбувається, надаються інструкції з міграції. Адаптація до наступної версії API рівня beta або стабільного може вимагати редагування чи повторного створення обʼєктів API, і це може бути не простим. Міграція може вимагати перерви у роботі застосунків, які покладаються на цю функцію.

  • Програмне забезпечення не рекомендується для використання в промисловій експлуатації. Подальші випуски можуть вносити несумісні зміни. Використання версій API рівня beta обовʼязкове для переходу до наступних версій API рівня beta або стабільного, якщо версія API рівня beta застаріє та більше не буде обслуговуватися.

  Примітка:

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

• Stable:

  • Назва версії — vX, де X – це ціле число.
  • Стабільні версії API залишаються доступними для всіх майбутніх випусків в межах основної версії Kubernetes, і немає поточних планів щодо ревізії основної версії Kubernetes, що вилучає стабільні API.

Групи API

Групи API спрощують розширення API Kubernetes. Група API вказується в REST-шляху та в полі apiVersion серіалізованого обʼєкта.

У Kubernetes існує кілька груп API:

• core (також називається legacy) група знаходиться за REST-шляхом /api/v1. Основна група не вказується як частина поля apiVersion, наприклад, apiVersion: v1.
• Названі групи знаходяться за REST-шляхом /apis/$GROUP_NAME/$VERSION та використовують apiVersion: $GROUP_NAME/$VERSION (наприклад, apiVersion: batch/v1). Повний список підтримуваних груп API можна знайти в довіднику API Kubernetes.

Увімкнення чи вимкнення груп API

Деякі ресурси та групи API типово увімкнені. Ви можете увімкнути чи вимкнути їх, встановивши --runtime-config на API-сервері. Прапорець --runtime-config приймає розділені комами пари <key>[=<value>], що описують конфігурацію запуску API-сервера. Якщо частина =<value> пропущена, вона розглядається так, ніби вказано =true. Наприклад:

• для вимкнення batch/v1 встановіть --runtime-config=batch/v1=false
• для увімкнення batch/v2alpha1 встановіть --runtime-config=batch/v2alpha1
• для увімкнення конкретної версії API, наприклад, storage.k8s.io/v1beta1/csistoragecapacities, встановіть --runtime-config=storage.k8s.io/v1beta1/csistoragecapacities

Збереження

Kubernetes зберігає свій серіалізований стан у термінах ресурсів API, записуючи їх в etcd.

Що далі

• Дізнайтеся більше про домовленості API
• Прочитайте документацію агрегатора
• Дізнайтесь про Декларативну перевірку API.

2.1 - Декларативна перевірка API

Kubernetes 1.35 включає необовʼязкову декларативну перевірку для API. Якщо її увімкнено, сервер API Kubernetes може використовувати цей механізм, а не застарілий підхід, який покладається на рукописний код Go (файли validation.go), щоб гарантувати, що запити до API є дійсними. Розробники Kubernetes та люди, які розширюють Kubernetes API, можуть визначати правила валідації безпосередньо поряд з визначеннями типів API (файли types.go). Автори коду визначають спеціальні теґи коментарів (наприклад, +k8s:minimum=0). Генератор коду (validation-gen) потім використовує ці теґи для створення оптимізованого коду Go для перевірки API.

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

Декларативна перевірка розгортається поступово. У Kubernetes 1.35, API, які використовують декларативну перевірку, включають:

• ReplicationController

• DeclarativeValidation: (Beta, стандартно: true) Якщо увімкнено, сервер API виконує як нову декларативну перевірку, так і стару ручну перевірку для перенесених типів/полів. Результати порівнюються внутрішньо.
• DeclarativeValidationTakeover: (Beta, стандартно: false) Ця можливість визначає, який результат перевірки є авторитетним (тобто, повертається користувачеві і використовується для прийняття рішень про допуск).

Типова поведінка (Kubernetes 1.35):

• Зі значеннями DeclarativeValidation=true та DeclarativeValidationTakeover=false ( стандартні значення для функціональних можливостей) працюють обидві системи валідації.
• Використовуються результати рукописної валідації. Декларативна валідація запускається у режимі розбіжностей для порівняння.
• Невідповідності між двома системами валідації реєструються сервером API і збільшують метрику declarative_validation_mismatch_total. Це допомагає розробникам виявляти та виправляти розбіжності на етапі бета-версії.
• Оновлення кластерів має бути безпечним щодо цієї функції, оскільки логіка авторитетної перевірки стандартно не змінюється.

Адміністратори можуть явно ввімкнути DeclarativeValidationTakeover=true, щоб зробити декларативну перевірку авторитетною для перенесених полів, зазвичай після перевірки стабільності в їхньому середовищі (наприклад, шляхом моніторингу метрики невідповідностей).

Вимкнення декларативної перевірки

Як адміністратор кластера, ви можете вимкнути декларативну перевірку, поки вона ще є бета-версією, за певних обставин:

• Неочікувана поведінка перевірки: Якщо увімкнення DeclarativeValidationTakeover призводить до неочікуваних помилок перевірки або дозволяє обʼєкти, які раніше були недійсними.
• Погіршення продуктивності: Якщо моніторинг вказує на значне збільшення затримок (наприклад, у apiserver_request_duration_seconds), повʼязане з увімкненням цієї функції.
• Високий рівень невідповідностей: Якщо метрика declarative_validation_mismatch_total показує часті невідповідності, що свідчить про потенційні помилки в декларативних правилах, які впливають на робочі навантаження кластера, навіть якщо DeclarativeValidationTakeover має значення false.

Щоб повернутися до використання лише рукописної перевірки (як це було до Kubernetes v1.33), вимкніть DeclarativeValidation feature gate, наприклад, за допомогою аргументів командного рядка: (--feature-gates=DeclarativeValidation=false). Це також неявно вимкне ефект DeclarativeValidationTakeover.

Міркування щодо пониження версії та відкату

Вимкнення цієї функції діє як механізм безпеки. Однак, памʼятайте про потенційний крайній випадок (який вважається малоймовірним завдяки ретельному тестуванню): Якщо помилка у декларативній перевірці (коли DeclarativeValidationTakeover=true) неправильно дозволила зберегти недійсний обʼєкт, вимкнення функціональних можливостей може призвести до блокування подальших оновлень цього конкретного обʼєкта за допомогою тепер авторизованої (і правильної) ручної перевірки. Розвʼязання цієї проблеми може вимагати ручного виправлення збереженого обʼєкта, можливо, за допомогою прямої модифікації etcd у рідкісних випадках.

Докладні відомості про керування функціональними можливостями наведено у статті Функціональні можливості.

Довідник теґів декларативної валідації

Цей документ містить вичерпну довідкову інформацію про всі доступні теґи декларативної валідації.

Каталог теґів

Довідник по теґам

+k8s:declarativeValidationNative

Опис:

Вказує, що всі перевірки для поля, включаючи будь-які перевірки типу поля, є декларативними і не мають відповідного еквівалента, написаного вручну. Це дозволено тільки для перевірок, які є 'Stable'. При використанні, помилки перевірки будуть позначені, щоб показати, що вони походять від виключно декларативної перевірки.

Рівень стабільності: Stable

Приклад використання:

type MyStruct struct {
    // +k8s:declarativeValidationNative
    // +k8s:maxLength=60
    MyField string `json:"myField"`
}

У цьому прикладі перевірка maxLength позначена як виключно декларативна.

+k8s:eachKey

Опис:

Оголошує валідацію для кожного ключа в map.

Рівень стабільності: Alpha

Корисне навантаження:

• <validation-tag>: Теґ для оцінки кожного ключа.

Приклад використання:

type MyStruct struct {
    // +k8s:eachKey=+k8s:minimum=1
    MyMap map[int]string `json:"myMap"`
}

У цьому прикладі eachKey використовується для вказівки, що теґ +k8s:minimum повинен застосовуватися до кожного ключа int в MyMap. Це означає, що всі ключі в map повинні бути >= 1.

+k8s:eachVal

Опис:

Оголошує валідацію для кожного значення в map або списку.

Рівень стабільності: Alpha

Корисне навантаження:

• <validation-tag>: Теґ для оцінки для кожного значення.

Приклад використання:

type MyStruct struct {
    // +k8s:eachVal=+k8s:minimum=1
    MyMap map[string]int `json:"myMap"`
}

У цьому прикладі eachVal використовується для вказівки, що теґ +k8s:minimum повинен застосовуватися до кожного елемента в MyList. Це означає, що всі поля в MyStruct повинні бути >= 1.

+k8s:enum

Опис:

Вказує, що тип рядка є enum (перерахуванням). Усі константи цього типу вважаються значеннями в перерахуванні.

Рівень стабільності: Beta

Приклад використання:

Спочатку визначте новий тип рядка та кілька констант цього типу:

// +k8s:enum
type MyEnum string

const (
    MyEnumA MyEnum = "A"
    MyEnumB MyEnum = "B"
)

Потім використовуйте цей тип в іншій структурі:

type MyStruct struct {
    MyField MyEnum `json:"myField"`
}

Логіка валідації забезпечить те, що MyField є одним з визначених значень enum (перерахування) ("A" або "B").

+k8s:forbidden

Опис:

Вказує, що поле не може бути вказане.

Рівень стабільності: Alpha

Приклад використання:

type MyStruct struct {
    // +k8s:forbidden
    MyField string `json:"myField"`
}

У цьому прикладі MyField не може бути надане (воно заборонене) під час створення або оновлення MyStruct.

+k8s:format

Опис:

Вказує, що рядкове поле має певний формат.

Рівень стабільності: Stable

Корисне навантаження:

• k8s-ip: Це поле містить значення IPv4 або IPv6 адреси. Октети IPv4 можуть мати нулі на початку.
• k8s-long-name: Це поле містить "довгу назву" Kubernetes, також відому як значення "DNS піддомену".
• k8s-short-name: Це поле містить "коротку назву" Kubernetes, також відому як значення "DNS мітки".

Приклад використання:

type MyStruct struct {
    // +k8s:format=k8s-ip
    IPAddress string `json:"ipAddress"`

    // +k8s:format=k8s-long-name
    Subdomain string `json:"subdomain"`

    // +k8s:format=k8s-short-name
    Label string `json:"label"`
}

У цьому прикладі:

• IPAddress повинен бути дійсною IP-адресою.
• Subdomain повинен бути дійсним піддоменом DNS.
• Label повинен бути дійсною міткою DNS.

+k8s:ifDisabled

Опис:

Оголошує валідацію, яка застосовується, коли опцію вимкнено.

Рівень стабільності: Alpha

Аргументи:

• <option> (рядок, обовʼязково): Імʼя опції.

Корисне навантаження:

• <validation-tag>: Цей теґ валідації буде оцінюватися лише тоді, коли опцію вимкнено.

Приклад використання:

type MyStruct struct {
    // +k8s:ifDisabled("my-feature")=+k8s:required
    MyField string `json:"myField"`
}

У цьому прикладі MyField є обовʼязковим лише тоді, коли опція "my-feature" вимкнена.

+k8s:ifEnabled

Опис:

Оголошує валідацію, яка застосовується, коли опцію увімкнено.

Рівень стабільності: Alpha

Аргументи:

• <option> (рядок, обовʼязково): Імʼя опції.

Корисне навантаження:

• <validation-tag>: Цей теґ валідації буде оцінюватися лише тоді, коли опцію увімкнено.

Приклад використання:

type MyStruct struct {
    // +k8s:ifEnabled("my-feature")=+k8s:required
    MyField string `json:"myField"`
}

У цьому прикладі MyField є обовʼязковим лише тоді, коли опція "my-feature" увімкнена.

+k8s:isSubresource

Рівень стабільності: Stable (не вимагає теґа +k8s:declarativeValidationNative)

Опис:

Теґ +k8s:isSubresource є коментарем на рівні пакета, який обмежує правила валідації в межах цього пакета до конкретного субресурсу. Він по суті говорить генератору коду: "Логіка валідації, визначена тут, є специфічною реалізацією для цього субресурсу і не повинна застосовуватися до кореневого обʼєкта або будь-якого іншого субресурсу."

КРИТИЧНА ЗАЛЕЖНІСТЬ:

Цей теґ є залежним від відповідного теґа +k8s:supportsSubresource, який повинен бути присутній у пакеті, де визначено основний тип API.

• +k8s:supportsSubresource відкриває двері, кажучи диспетчеру, що субресурс є дійсним.
• +k8s:isSubresource надає спеціалізовану логіку валідації, яка виконується, коли запит проходить через ці двері.

Якщо ви використовуєте +k8s:isSubresource без відповідного оголошення +k8s:supportsSubresource для основного типу, спеціалізований код валідації буде згенеровано, але він буде недоступний. Основний диспетчер не розпізнає шлях субресурсу і відхилить запит, перш ніж він зможе бути надісланий до вашої специфічної логіки валідації.

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

Область дії: Пакет

Корисне навантаження:

• <subresource-path>: Шлях субресурсу, до якого повинні застосовуватися валідації в цьому пакеті (наприклад, "/status", "/scale").

Приклад використання:

Цей приклад з двох частин демонструє передбачуваний випадок використання розділення обовʼязків.

1. Оголосити підтримку в основному пакеті API: Спочатку оголосіть, що тип Deployment підтримує валідацію /scale у своєму основному пакеті.

Файл: staging/src/k8s.io/api/apps/v1/doc.go

// Це дозволяє диспетчеру валідації обробляти запити для "/scale".
// +k8s:supportsSubresource="/scale"
package v1

// ... включає визначення типу Deployment

2. Обмежити логіку валідації в окремому пакеті: Далі створіть окремий пакет для правил валідації, які специфічні тільки для субресурсу /scale.

Файл: staging/src/k8s.io/api/apps/v1/validations/scale/doc.go

// Це забезпечує те, що правила в цьому пакеті виконуються ТІЛЬКИ для субресурсу "/scale".
// +k8s:isSubresource="/scale"
package scale

import "k8s.io/api/apps/v1"

// Код валідації в цьому пакеті буде посилатися на типи з пакета v1 (наприклад, v1.Scale).
// Згенерована функція валідації буде викликатися лише для запитів до субресурсу "/scale"
// обʼєкта типу, визначеного в пакеті, який підтримує це.

+k8s:item

Опис:

Оголошує валідацію для елемента зрізу, оголошеного як +k8s:listType=map. Елемент, що має збіг, оголошується шляхом надання аргументів парою поле-значення, де поле є listMapKey. Усі поля ключів listMapKey повинні бути вказані.

Рівень стабільності: Stable

Використання:

+k8s:item(<listMapKey-JSON-field-name>: <value>,...)=<validation-tag>

+k8s:item(stringKey: "value", intKey: 42, boolKey: true)=<validation-tag>

Аргументи повинні бути іменовані за допомогою JSON-імен полів ключів списку-мапи. Значення можуть бути рядками, цілими числами або булевими значеннями.

Корисне навантаження:

• <validation-tag>: Теґ для оцінки для елемента списку, що має збіг.

Приклад використання:

type MyStruct struct {
	// +k8s:listType=map
	// +k8s:listMapKey=type
	// +k8s:item(type: "Approved")=+k8s:zeroOrOneOfMember
	// +k8s:item(type: "Denied")=+k8s:zeroOrOneOfMember
	MyConditions []MyCondition `json:"conditions"`
}

type MyCondition struct {
    Type string `json:"type"`
    Status string `json:"status"`
}

У цьому прикладі:

• Умова з type "Approved" є частиною групи нуль-або-один-з.
• Умова з type "Denied" є частиною групи нуль-або-один-з.

+k8s:listMapKey

Опис:

Оголошує іменоване підполе типу значення списку як частину ключа list-map. Цей теґ є обовʼязковим, коли використовується +k8s:listType=map. Кілька теґів +k8s:listMapKey можуть використовуватися на list-map, щоб вказати, що він є ключем з кількох полів.

Рівень стабільності: Stable

Корисне навантаження:

• <field-json-name>: Імʼя JSON поля, яке буде використовуватися як ключ.

Приклад використання:

// +k8s:listType=map
// +k8s:listMapKey=keyFieldOne
// +k8s:listMapKey=keyFieldTwo
type MyList []MyStruct

type MyStruct struct {
    keyFieldOne string `json:"keyFieldOne"`
    keyFieldTwo string `json:"keyFieldTwo"`
    valueField string `json:"valueField"`
}

У цьому прикладі listMapKey використовується для вказівки, що keyField типу MyStruct повинен використовуватися як ключ для list-map.

+k8s:listType

Опис:

Оголошує семантичний тип поля списку. Цей теґ використовується для вказівки того, як список повинен оброблятися, наприклад, як map або set (набір).

Рівень стабільності: Stable

Корисне навантаження:

• atomic: Список обробляється як одне атомарне значення.
• map: Список обробляється як map, де кожен елемент має унікальний ключ. Вимагає використання +k8s:listMapKey.
• set: Список обробляється як set (набір), де кожен елемент є унікальним.

Приклад використання:

// +k8s:listType=map
// +k8s:listMapKey=keyField
type MyList []MyStruct

type MyStruct struct {
    keyField string `json:"keyField"`
    valueField string `json:"valueField"`
}

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

+k8s:maxItems

Опис:

Вказує, що поле списку має обмеження на розмір.

Рівень стабільності: Stable

Корисне навантаження:

• <негативне число>: Це поле не повинно містити більше X елементів.

Приклад використання:

type MyStruct struct {
    // +k8s:maxItems=5
    MyList []string `json:"myList"`
}

У цьому прикладі MyList не може містити більше 5 елементів.

+k8s:maxLength

Опис:

Вказує, що рядкове поле має обмеження на довжину.

Рівень стабільності: Stable

Корисне навантаження:

• <негативне число>: Це поле не повинно містити більше X символів.

Приклад використання:

type MyStruct struct {
    // +k8s:maxLength=10
    MyString string `json:"myString"`
}

У цьому прикладі MyString не може бути довшим за 10 символів.

+k8s:minimum

Опис:

Вказує, що числове поле має мінімальне значення.

Рівень стабільності: Stable

Корисне навантаження:

• <ціле число>: Це поле повинно бути більшим або рівним x.

Приклад використання:

type MyStruct struct {
    // +k8s:minimum=0
    MyInt int `json:"myInt"`
}

У цьому прикладі MyInt повинен бути більшим або рівним 0.

+k8s:neq

Опис:

Перевіряє, що значення поля не дорівнює конкретному забороненому значенню. Підтримує рядкові, цілі та булеві типи.

Рівень стабільності: Alpha

Корисне навантаження:

• <значення>: Заборонене значення. Парсер вгадає тип (рядок, int, bool).

Приклад використання:

type MyStruct struct {
    // +k8s:neq="disallowed"
    MyString string `json:"myString"`

    // +k8s:neq=0
    MyInt int `json:"myInt"`

    // +k8s:neq=true
    MyBool bool `json:"myBool"`
}

У цьому прикладі:

• MyString не може дорівнювати "disallowed".
• MyInt не може дорівнювати 0.
• MyBool не може дорівнювати true.

+k8s:opaqueType

Опис:

Вказує, що будь-які валідації, оголошені для вказаного типу, будуть проігноровані. Якщо пакет вказаного типу не включено в поточні прапорці генератора, цей теґ повинен бути встановлений, інакше генерація коду завершиться невдачею (запобігаючи тихим помилкам). Якщо валідації не повинні ігноруватися, додайте пакет типу до генератора за допомогою прапорця --readonly-pkg.

Рівень стабільності: Alpha

Приклад використання:

import "some/external/package"

type MyStruct struct {
    // +k8s:opaqueType
    ExternalField package.ExternalType `json:"externalField"`
}

У цьому прикладі будь-які теґи валідації на package.ExternalType будуть проігноровані.

+k8s:optional

Опис:

Вказує, що поле є необовʼязковим для клієнтів.

Рівень стабільності: Stable

Приклад використання:

type MyStruct struct {
    // +k8s:optional
    MyField string `json:"myField"`
}

У цьому прикладі MyField не є обовʼязковим для надання під час створення або оновлення MyStruct.

+k8s:required

Опис:

Вказує, що поле має бути вказане клієнтами.

Рівень стабільності: Stable

Приклад використання:

type MyStruct struct {
    // +k8s:required
    MyField string `json:"myField"`
}

У цьому прикладі MyField повинно бути надане під час створення або оновлення MyStruct.

+k8s:subfield

Опис:

Оголошує валідацію для підполя структури.

Рівень стабільності: Beta

Аргументи:

• <field-json-name> (рядок, обовʼязково): Імʼя JSON підполя.

Корисне навантаження:

• <validation-tag>: Теґ для оцінки для підполя.

Приклад використання:

type MyStruct struct {
    // +k8s:subfield("mySubfield")=+k8s:required
    MyStruct MyStruct `json:"MyStruct"`
}

type MyStruct struct {
    MySubfield string `json:"mySubfield"`
}

У цьому прикладі MySubfield всередині MyStruct є обовʼязковим.

+k8s:supportsSubresource

Рівень стабільності: Stable (не вимагає теґа +k8s:declarativeValidationNative)

Опис:

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

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

Кілька теґів можуть використовуватися для оголошення підтримки кількох субресурсів. Якщо в пакеті немає жодного теґа +k8s:supportsSubresource, валідація увімкнена лише для кореневого ресурсу (наприклад, .../myresources/myobject), і будь-які запити до субресурсів будуть відхилені з помилкою "валідація не знайдена".

Окрема використання:

Якщо ви використовуєте +k8s:supportsSubresource без відповідного теґа +k8s:isSubresource для конкретної валідації, стандартно правила валідації для кореневого обʼєкта будуть застосовані до субресурсу.

Область дії: Пакет

Корисне навантаження:

• <subresource-path>: Шлях субресурсу, який потрібно підтримувати (наприклад, "/status", "/scale").

Приклад використання:

Додавши ці теґи, ви дозволяєте системі валідації обробляти запити для /status та /scale субресурсів для типів, визначених у пакеті v1.

Файл: staging/src/k8s.io/api/core/v1/doc.go

// +k8s:supportsSubresource="/status"
// +k8s:supportsSubresource="/scale"
package v1

+k8s:unionDiscriminator

Опис:

Вказує, що це поле є дискримінатором для обʼєднання.

Рівень стабільності: Stable

Аргументи:

• union (рядок, необовʼязково): Імʼя обʼєднання, якщо їх кілька.

Приклад використання:

type MyStruct struct {
	TypeMeta int

	// +k8s:unionDiscriminator
	D D `json:"d"`

	// +k8s:unionMember
	// +k8s:optional
	M1 *M1 `json:"m1"`

	// +k8s:unionMember
	// +k8s:optional
	M2 *M2 `json:"m2"`
}

type D string

const (
	DM1 D = "M1"
	DM2 D = "M2"
)

type M1 struct{}

type M2 struct{}

У цьому прикладі поле Type є дискримінатором для обʼєднання. Значення Type визначить, який з членів обʼєднання (M1 або M2) очікується наявним.

+k8s:unionMember

Опис:

Вказує, що це поле є членом обʼєднання.

Рівень стабільності: Stable

Аргументи:

• union (рядок, необовʼязково): Імʼя обʼєднання, якщо їх кілька.
• memberName (рядок, необовʼязково): Значення дискримінатора для цього члена. Стандартно використовується імʼя поля.

Приклад використання:

type MyStruct struct {
	// +k8s:unionMember(union: "union1")
	// +k8s:optional
	M1 *M1 `json:"u1m1"`

	// +k8s:unionMember(union: "union1")
	// +k8s:optional
	M2 *M2 `json:"u1m2"`
}

type M1 struct{}

type M2 struct{}

У цьому прикладі M1 і M2 є членами названого обʼєднання union1.

+k8s:zeroOrOneOfMember

Опис:

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

Рівень стабільності: Stable

Аргументи:

• union (рядок, необовʼязково): Імʼя обʼєднання, якщо їх кілька.
• memberName (рядок, необовʼязково): Користувацьке імʼя члена для цього члена. Стандартно використовується імʼя поля.

Приклад використання:

type MyStruct struct {
	// +k8s:zeroOrOneOfMember
	// +k8s:optional
	M1 *M1 `json:"m1"`

	// +k8s:zeroOrOneOfMember
	// +k8s:optional
	M2 *M2 `json:"m2"`
}

type M1 struct{}

type M2 struct{}

У цьому прикладі не більше ніж один з A або B може бути встановлений. Також дійсно, що жоден з них не встановлений.

2.2 - Концепції API Kubernetes

API Kubernetes — це програмний інтерфейс на основі ресурсів (RESTful), який надається через HTTP. Він підтримує отримання, створення, оновлення та видалення основних ресурсів за допомогою стандартних HTTP-дієслів (POST, PUT, PATCH, DELETE, GET).

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

Kubernetes підтримує ефективні сповіщення про зміни ресурсів за допомогою watches.

В API Kubernetes, watch це дієслово, яке використовується для відстеження змін обʼєкта в Kubernetes у вигляді потоку. Використовується для ефективного виявлення змін.

Ви можете переглянути Довідник API онлайн або прочитати далі, щоб дізнатися про API загалом.

Терміни API Kubernetes

Kubernetes зазвичай використовує загальноприйняту термінологію RESTful для опису концепцій API:

• Тип ресурсу — це назва, що використовується в URL (pods, namespaces, services)
• Усі типи ресурсів мають конкретне представлення (їх схему обʼєкта), яке називається kind
• Список екземплярів типу ресурсу називається колекцією
• Окремий екземпляр типу ресурсу називається ресурсом і зазвичай представляє обʼєкт
• Для деяких типів ресурсів API включає один або більше субресурсів, які представлені як URI-шляхи після назви ресурсу

Більшість типів ресурсів API Kubernetes є обʼєктами — вони представляють конкретний екземпляр концепції у кластері, як-от pod або namespace. Невелика кількість типів ресурсів API є віртуальними, оскільки вони часто представляють операції над обʼєктами, а не самі обʼєкти, такі як перевірка дозволів (використання POST із JSON-кодованим тілом SubjectAccessReview для ресурсу subjectaccessreviews), або субресурс eviction у Pod (використовується для запуску виселення, ініційованого API).

Імена обʼєктів

Усі обʼєкти, які ви можете створити через API, мають унікальне імʼя, що дозволяє ідемпотентне¹ створення та отримання, за винятком віртуальних типів ресурсів, які можуть не мати унікальних імен, якщо вони не можуть бути отримані або не залежать від ідемпотентності. У межах простору імен може бути лише один обʼєкт з вказаним іменем для даного виду. Однак, якщо ви видалите обʼєкт, ви можете створити новий обʼєкт з тим самим іменем. Деякі обʼєкти не мають простору імен (наприклад: Nodes), тому їх імена повинні бути унікальними у всьому кластері.

Дієслова API

Майже всі типи ресурсів підтримують стандартні HTTP-дієслова — GET, POST, PUT, PATCH, та DELETE. Kubernetes також використовує власні дієслова, які часто пишуться малими літерами, щоб відрізняти їх від HTTP-дієслів.

Kubernetes використовує термін list для опису дії отримання колекції ресурсів, щоб відрізняти її від дії отримання одного ресурсу, яка зазвичай називається get. Якщо ви надішлете HTTP-запит GET із параметром ?watch, Kubernetes називає це watch, а не get (див. Ефективне виявлення змін для деталей).

Для запитів PUT Kubernetes внутрішньо класифікує їх як create або update залежно від стану наявного обʼєкта. Update відрізняється від patch; HTTP-дієслово для patch - PATCH.

URI ресурсів

Усі типи ресурсів або належать кластеру (/apis/GROUP/VERSION/*), або простору імен (/apis/GROUP/VERSION/namespaces/NAMESPACE/*). Тип ресурсу, що належить простору імен, буде видалений при видаленні простору імен, і доступ до цього типу ресурсу контролюється перевірками авторизації в межах простору імен.

Примітка: основні ресурси використовують /api замість /apis і пропускають сегмент GROUP.

Приклади:

• /api/v1/namespaces
• /api/v1/pods
• /api/v1/namespaces/my-namespace/pods
• /apis/apps/v1/deployments
• /apis/apps/v1/namespaces/my-namespace/deployments
• /apis/apps/v1/namespaces/my-namespace/deployments/my-deployment

Ви також можете отримати доступ до колекцій ресурсів (наприклад, переліку усіх Nodes). Наступні шляхи використовуються для отримання колекцій та ресурсів:

• Ресурси кластерного рівня:

  • GET /apis/GROUP/VERSION/RESOURCETYPE — повертає колекцію ресурсів вказаного типу ресурсу
  • GET /apis/GROUP/VERSION/RESOURCETYPE/NAME — повертає ресурс з імʼям NAME вказаного типу ресурсу

• Ресурси рівня простору імен:

  • GET /apis/GROUP/VERSION/RESOURCETYPE — повертає колекцію всіх екземплярів вказаного типу ресурсу в усіх просторах імен
  • GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE — повертає колекцію всіх екземплярів вказаного типу ресурсу в просторі імен NAMESPACE
  • GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME — повертає екземпляр вказаного типу ресурсу з імʼям NAME в просторі імен NAMESPACE

Оскільки простір імен є ресурсом кластерного рівня, ви можете отримати перелік ("колекцію") всіх просторів імен за допомогою GET /api/v1/namespaces та деталі про конкретний простір імен за допомогою GET /api/v1/namespaces/NAME.

• Субресурс кластерного рівня: GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCE
• Субресурс рівня простору імен: GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCE

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

HTTP медіа-типи

Kubernetes підтримує кодування JSON, YAML, CBOR та Protobuf для передачі даних по HTTP.

Стандартно, Kubernetes повертає серіалізовані об’єкти JSON, використовуючи медіа-тип application/json. Хоча JSON є стандартним типом, клієнти можуть запитувати відповідь у форматі YAML, або більш ефективне двійкове подання у вигляді Protobuf для кращої продуктивності.

Kubernetes API реалізує стандартне узгодження типів вмісту HTTP: передача заголовка Accept у запиті GET вказує серверу спробувати повернути відповідь у бажаному медіа-типі. Якщо ви хочете надіслати об’єкт у форматі Protobuf на сервер для запиту PUT або POST, вам необхідно відповідно встановити заголовок запиту Content-Type.

Якщо ви запитуєте доступні медіа-типи, API-сервер повертає відповідь з відповідним заголовком Content-Type; якщо жоден із запитаних медіа-типів не підтримується, API-сервер поверне повідомлення про помилку 406 Not acceptable. Усі вбудовані типи ресурсів підтримують медіа-тип application/json.

Часткове кодування колекцій

Для кодування JSON та Protobuf Kubernetes реалізує власні кодувальники, які записують елементи по одному. Ця функція не змінює вихідні дані, але дозволяє API-серверу уникати завантаження всієї відповіді LIST в памʼять. Використання інших типів кодування (включаючи форматоване представлення JSON) слід уникати для великих колекцій ресурсів (>100MB), оскільки це може негативно вплинути на продуктивність.

Кодування ресурсів у форматі JSON

API Kubernetes стандартно використовує JSON для кодування тіла HTTP повідомлень.

Наприклад:

1. Вивести список усіх Podʼів в кластері без вказування бажаного формату

   GET /api/v1/pods
   

   200 OK
   Content-Type: application/json
   
   … Колекція Pod, закодована у форматі JSON (обʼєкт PodList)
   

2. Створити Pod, відправивши JSON на сервер та запросивши відповідь у форматі JSON.

   POST /api/v1/namespaces/test/pods
   Content-Type: application/json
   Accept: application/json
   … Обʼєкт Pod, закодований у форматі JSON
   

   200 OK
   Content-Type: application/json
   
   {
     "kind": "Pod",
     "apiVersion": "v1",
     …
   }
   

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

Кодування ресурсів у YAML

Kubernetes також підтримує медіатип application/yaml для запитів та відповідей. YAML може використовуватись для визначення маніфестів Kubernetes та взаємодії з API.

Наприклад:

1. Отримати список усіх podʼів у кластері у форматі YAML

   GET /api/v1/pods
   Accept: application/yaml
   

   200 OK
   Content-Type: application/yaml
   
   … YAML-кодована колекція Podʼів (обʼєкт PodList)
   

2. Створити pod, надіславши дані у форматі YAML на сервер і запросивши відповідь у форматі YAML:

   POST /api/v1/namespaces/test/pods
   Content-Type: application/yaml
   Accept: application/yaml
   … YAML-кодований об'єкт Pod
   

   200 OK
   Content-Type: application/yaml
   
   apiVersion: v1
   kind: Pod
   metadata:
     name: my-pod
     …
   

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

Кодування Kubernetes Protobuf

Kubernetes використовує обгортку-конверт для кодування відповідей у форматі Protobuf. Ця обгортка починається з 4 байтів магічного числа, щоб допомогти ідентифікувати вміст на диску або в etcd як Protobuf (на відміну від JSON). Дані з магічним числом (4 байти) слідують за повідомленням, закодованим у форматі Protobuf, яке описує кодування та тип основного об’єкта. Усередині повідомлення Protobuf дані внутрішнього об’єкта записуються за допомогою поля raw Unknown (дивіться IDL для докладної інформації).

Наприклад:

1. Вивести список усіх Pod в кластері у форматі Protobuf.

   GET /api/v1/pods
   Accept: application/vnd.kubernetes.protobuf
   

   200 OK
   Content-Type: application/vnd.kubernetes.protobuf
   
   … Колекція Pod, закодована у двійковому форматі (обʼєкт PodList)
   

2. Створити Pod, відправивши дані, закодовані у форматі Protobuf на сервер, але запросити відповідь у форматі JSON.

   POST /api/v1/namespaces/test/pods
   Content-Type: application/vnd.kubernetes.protobuf
   Accept: application/json
   … двійково закодований обʼєкт Pod
   ---
   200 OK
   Content-Type: application/json
   
   {
     "kind": "Pod",
     "apiVersion": "v1",
     ...
   }
   

Ви можете використовувати обидві техніки разом і взаємодіяти з API Kubernetes, яке підтримує кодування Protobuf, для читання та запису даних. Лише деякі типи ресурсів API є сумісними з Protobuf.

Чотирибайтовий префікс магічного числа:
  Байти 0-3: "k8s\x00" [0x6b, 0x38, 0x73, 0x00]

Закодоване повідомлення Protobuf з наступним IDL:
  message Unknown {
    // typeMeta повинне містити значення рядків для "kind" та "apiVersion", як встановлено в обʼєкті
    JSON optional TypeMeta typeMeta = 1;

    // raw містить повний серіалізований обʼєкт у форматі protobuf.
    // Дивіться визначення protobuf у клієнтських бібліотеках для конкретного виду.
    optional bytes raw = 2;

    // contentEncoding — це кодування, яке використовується для raw даних.
    // Якщо не вказано, кодування відсутнє.
    optional string contentEncoding = 3;

    // contentType — це метод серіалізації, який використовується для серіалізації 'raw'.
    // Якщо не вказано, використовується application/vnd.kubernetes.protobuf, і зазвичай
    // цей параметр не вказується.
    optional string contentType = 4;
  }

  message TypeMeta {
    // apiVersion — це група/версія для цього типу
    optional string apiVersion = 1;
    // kind — це назва схеми обʼєкта. Має існувати визначення protobuf для цього обʼєкта.
    optional string kind = 2;
  }

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

Сумісність із Kubernetes Protobuf

Не всі типи ресурсів API підтримують кодування Kubernetes у форматі Protobuf; зокрема, Protobuf не доступний для ресурсів, які визначені як CustomResourceDefinitions або надаються через шар агрегації.

Як клієнт, якщо вам може знадобитися працювати з розширеними типами, слід вказати кілька типів контенту в заголовку Accept запиту для підтримки резервного переходу на JSON. Наприклад:

Accept: application/vnd.kubernetes.protobuf, application/json

Кодування ресурсів CBOR

З увімкненою функціональною можливістю CBORServingAndStorage тіла запитів і відповідей для всіх вбудованих типів ресурсів і всіх ресурсів, визначених CustomResourceDefinition, можуть бути закодовані у двійковий формат даних CBOR. CBOR також підтримується на рівні aggregation layer, якщо він увімкнений на окремих агрегованих серверах API.

Клієнти повинні вказувати медіа-тип IANA application/cbor в заголовку HTTP-запиту Content-Type, коли тіло запиту містить один CBOR закодований елемент даних, і в заголовку HTTP-запиту Accept, коли вони готові прийняти CBOR-кодований елемент даних у відповіді. Сервери API будуть використовувати application/cbor в заголовку Content-Type HTTP-відповіді, коли тіло відповіді містить об'єкт, закодований CBOR.

Якщо сервер API кодує свою відповідь на watch request за допомогою CBOR, тіло відповіді буде CBOR Sequence, а в заголовку Content-Type HTTP-відповіді буде використано медіа-тип IANA application/cbor-seq. Кожен елемент послідовності (якщо такий є) є окремою подією спостереження, закодованою CBOR.

На додаток до існуючого типу даних application/apply-patch+yaml для YAML-кодованих конфігурацій додатків на стороні сервера, сервери API, які підтримують CBOR, прийматимуть тип даних application/apply-patch+cbor для конфігурацій додатків на стороні сервера, закодованих CBOR. Для application/json-patch+json або application/merge-patch+json, або application/strategic-merge-patch+json не підтримується еквівалент CBOR.

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

Ефективне виявлення змін

API Kubernetes дозволяє клієнтам зробити початковий запит на обʼєкт або колекцію, а потім відстежувати зміни з моменту цього запиту: це watch. Клієнти можуть відправити list або get і потім зробити наступний запит watch.

Для реалізації цього відстеження змін кожен обʼєкт Kubernetes має поле resourceVersion, яке представляє версію цього ресурсу, що зберігається в постійному шарі збереження. При отриманні колекції ресурсів (як простору імен, так і кластерного рівня), відповідь від сервера API містить значення resourceVersion. Клієнт може використовувати це значення resourceVersion для ініціювання watch проти сервера API.

Коли ви надсилаєте запит watch, сервер API відповідає потоком змін. Ці зміни перераховують результати операцій (таких як create, delete, та update), що відбулись після resourceVersion, значення якого було вказане як параметр до запиту watch. Загальний механізм watch дозволяє клієнту отримати поточний стан і потім підписатися на подальші зміни, не пропускаючи жодної події.

Якщо клієнт watch відʼєднується, тоді цей клієнт може розпочати новий сеанс watch з останнього повернутого resourceVersion; клієнт також може виконати новий запити get/list і розпочати знову. Див. Семантика версій ресурсів для отримання детальнішої інформації.

Наприклад:

1. Отримання списку всіх Podʼів у вказаному просторі імен.

   GET /api/v1/namespaces/test/pods
   ---
   200 OK
   Content-Type: application/json
   
   {
     "kind": "PodList",
     "apiVersion": "v1",
     "metadata": {"resourceVersion":"10245"},
     "items": [...]
   }
   

2. Починаючи з версії ресурсу 10245, отримуйте сповіщення про будь-які операції API (такі як create, delete, patch або update), що впливають на Podʼи у просторі імен test. Кожне сповіщення про зміну — це документ JSON. Тіло відповіді HTTP (надається як application/json) складається із серії документів JSON.

   GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
   ---
   200 OK
   Transfer-Encoding: chunked
   Content-Type: application/json
   
   {
     "type": "ADDED",
     "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
   }
   {
     "type": "MODIFIED",
     "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "11020", ...}, ...}
   }
   ...
   

Сервер Kubernetes буде зберігати історичний запис змін лише протягом обмеженого часу. Кластери, що використовують etcd 3, стандартно зберігають зміни за останні 5 хвилин. Коли запитувані операції watch не вдаються через недоступність історичної версії цього ресурсу, клієнти повинні обробляти цей випадок, розпізнаючи код статусу 410 Gone, очищаючи свій локальний кеш, виконуючи новий get або list запит, і починаючи watch з resourceVersion, яке було повернуто.

Для підписки на колекції бібліотеки клієнтів Kubernetes зазвичай пропонують певну форму стандартного інструменту для логіки list-потім-watch. (У бібліотеці клієнтів Go це називається Reflector і знаходиться в пакеті k8s.io/client-go/tools/cache).

Закладки для Watch

Щоб зменшити вплив короткого вікна історії, API Kubernetes надає подію спостереження під назвою BOOKMARK. Це особливий вид події, що позначає, що всі зміни до вказаної клієнтом resourceVersion вже були надіслані. Документ, що представляє подію BOOKMARK, має тип який отримується запитом, але включає лише поле .metadata.resourceVersion. Наприклад:

GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
  "type": "ADDED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
}
...
{
  "type": "BOOKMARK",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
}

Як клієнт, ви можете запитувати події BOOKMARK, встановлюючи параметр запиту allowWatchBookmarks=true у запиті watch, але не слід припускати, що закладки будуть повертатися з певним інтервалом, і клієнти не можуть очікувати, що сервер API надішле будь-яку подію BOOKMARK, навіть якщо її було запитано.

Потокові списки

У великих кластерах отримання колекції деяких типів ресурсів може призвести до значного збільшення використання ресурсів (переважно RAM) панелі управління. Щоб зменшити вплив та спростити користування шаблоном list + watch у Kubernetes v1.32 переведено у бета-версію функцію, яка дозволяє запитувати початковий стан (який раніше запитувався за допомогою запиту list) як частину запиту watch.

На стороні клієнта початковий стан можна запросити, вказавши sendInitialEvents=true як параметр рядка запиту у запиті типу watch. Якщо встановлено, сервер API починає потік спостереження з синтетичних початкових подій (типу ADDED) для побудови всього стану всіх наявних обʼєктів, після чого йде подія BOOKMARK (якщо запитано через параметр allowWatchBookmarks=true). Подія закладки включає версію ресурсу, до якої його було синхронізовано. Після надсилання події закладки сервер API продовжує роботу як для будь-якого іншого запиту watch.

Коли ви встановлюєте sendInitialEvents=true у рядку запиту, Kubernetes також вимагає, щоб ви встановили resourceVersionMatch до значення NotOlderThan. Якщо ви вказали resourceVersion у рядку запиту без значення або не вказали його взагалі, це інтерпретується як запит на узгоджене читання (consistent read); подія закладки надсилається, коли стан синхронізовано щонайменше до моменту узгодженого читання з моменту, коли запит почав оброблятися. Якщо ви вказуєте resourceVersion (у рядку запиту), подія закладки надсилається, коли стан синхронізовано щонайменше до вказаної версії ресурсу.

Приклад

Приклад: ви хочете спостерігати за колекцією Podʼів. Для цієї колекції поточна версія ресурсу становить 10245, і є два Podʼи: foo та bar. Надсилання наступного запиту (який явно запитує узгоджене читання, встановлюючи порожню версію ресурсу за допомогою resourceVersion=) може призвести до наступної послідовності подій:

GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
  "type": "ADDED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "8467", "name": "foo"}, ...}
}
{
  "type": "ADDED",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "5726", "name": "bar"}, ...}
}
{
  "type": "BOOKMARK",
  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10245"} }
}
...
<далі йде звичайний потік спостереження, починаючи з resourceVersion="10245">

Стиснення відповідей

Опція APIResponseCompression дозволяє серверу API стискати відповіді на запити get та list, зменшуючи використання мережевої пропускної здатності та покращуючи продуктивність у великих кластерах. Її стандартно увімкнено з Kubernetes 1.16 і її можна вимкнути додаванням APIResponseCompression=false у прапорець --feature-gates на сервері API.

Стиснення відповідей API може значно зменшити розмір відповіді, особливо для великих ресурсів або колекцій. Наприклад, запит list для Podʼів може повернути сотні кілобайт або навіть мегабайти даних, залежно від кількості Podʼів та їх атрибутів. Стиснення відповіді дозволяє зберегти мережеву пропускну здатність та зменшити затримки.

Щоб перевірити, чи працює APIResponseCompression, ви можете надіслати запит get або list на сервер API з заголовком Accept-Encoding та перевірити розмір відповіді та заголовки. Наприклад:

GET /api/v1/pods
Accept-Encoding: gzip
---
200 OK
Content-Type: application/json
content-encoding: gzip
...

Заголовок content-encoding вказує, що відповідь стиснута за допомогою gzip.

Отримання великих наборів результатів частинами

У великих кластерах отримання колекції деяких типів ресурсів може призвести до дуже великих відповідей, що може вплинути на сервер та клієнта. Наприклад, у кластері може бути десятки тисяч Podʼів, кожен з яких еквівалентний приблизно 2 КіБ у форматі JSON. Отримання всіх Podʼів через всі простори імен може призвести до дуже великої відповіді (10-20 МБ) та спожити багато ресурсів сервера.

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

Ви можете запитувати сервер API для обробки list запиту, використовуючи сторінки (які Kubernetes називає chunks). Щоб отримати одну колекцію частинами, підтримуються два параметри запиту limit та continue у запитах до колекцій, і поле відповіді continue повертається з усіх операцій list у полі metadata колекції. Клієнт повинен вказати максимальну кількість результатів, яку він бажає отримати у кожній частині за допомогою limit, і сервер поверне кількість ресурсів у результаті не більше limit та включить значення continue, якщо у колекції є більше ресурсів.

Як клієнт API, ви можете передати це значення continue серверу API у наступному запиті, щоб вказати серверу повернути наступну сторінку (chunk) результатів. Продовжуючи до тих пір, поки сервер не поверне порожнє значення continue, ви можете отримати всю колекцію.

Як і у випадку з операцією watch, токен continue закінчується через короткий проміжок часу (стандартно 5 хвилин) і повертає 410 Gone, якщо більше результатів не може бути повернуто. У цьому випадку клієнт повинен буде почати з початку або опустити параметр limit.

Наприклад, якщо у кластері є 1,253 Podʼів і ви хочете отримувати частини по 500 Podʼів за раз, запитуйте ці частини наступним чином:

1. Отримати всі Podʼи в кластері, отримуючи до 500 Podʼів за раз.

   GET /api/v1/pods?limit=500
   ---
   200 OK
   Content-Type: application/json
   
   {
     "kind": "PodList",
     "apiVersion": "v1",
     "metadata": {
       "resourceVersion":"10245",
       "continue": "ENCODED_CONTINUE_TOKEN",
       "remainingItemCount": 753,
       ...
     },
     "items": [...] // повертає Podʼи 1-500
   }
   

2. Продовжити попередній запит, отримуючи наступний набір з 500 Podʼів.

   GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
   ---
   200 OK
   Content-Type: application/json
   
   {
     "kind": "PodList",
     "apiVersion": "v1",
     "metadata": {
       "resourceVersion":"10245",
       "continue": "ENCODED_CONTINUE_TOKEN_2",
       "remainingItemCount": 253,
       ...
     },
     "items": [...] // повертає Podʼи 501-1000
   }
   

3. Продовжити попередній запит, отримуючи останні 253 Podʼів.

   GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
   ---
   200 OK
   Content-Type: application/json
   
   {
     "kind": "PodList",
     "apiVersion": "v1",
     "metadata": {
       "resourceVersion":"10245",
       "continue": "", // токен continue порожній, тому що ми досягли кінця списку
       ...
     },
     "items": [...] // повертає Podʼи 1001-1253
   }
   

Зверніть увагу, що resourceVersion колекції залишається постійним в кожному запиті, що вказує на те, що сервер показує вам узгоджену копію Podʼів. Podʼи, що створюються, оновлюються або видаляються після версії 10245, не будуть показані, якщо ви не зробите окремий запит list без токена continue. Це дозволяє вам розбивати великі запити на менші частини, а потім виконувати операцію watch на повному наборі, не пропускаючи жодного оновлення.

Поле remainingItemCount вказує кількість наступних елементів у колекції, які не включені у цю відповідь. Якщо запит list містив мітки або поля селектори, тоді кількість залишкових елементів невідома, і сервер API не включає поле remainingItemCount у свою відповідь. Якщо list запит завершено (або тому, що він не розбивається на частини, або тому, що це остання частина), то більше немає залишкових елементів, і сервер API не включає поле remainingItemCount у свою відповідь. Очікуване використання `remainingItemCount — оцінка розміру колекції.

Колекції

У термінології Kubernetes відповідь, яку ви отримуєте за допомогою list, є колекцією. Однак Kubernetes визначає конкретні види для колекцій різних типів ресурсів. Колекції мають вид, названий на честь виду ресурсу, з доданим List.

Коли ви надсилаєте запит API для певного типу, всі елементи, повернуті цим запитом, є цього типу. Наприклад, коли ви надсилаєте list Services, відповідь колекції має kind, встановлений на ServiceList; кожен елемент у цій колекції представляє один Service. Наприклад:

GET /api/v1/services

{
  "kind": "ServiceList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "2947301"
  },
  "items": [
    {
      "metadata": {
        "name": "kubernetes",
        "namespace": "default",
...
      "metadata": {
        "name": "kube-dns",
        "namespace": "kube-system",
...

Є десятки типів колекцій (таких як PodList, ServiceList та NodeList), визначених в API Kubernetes. Ви можете отримати більше інформації про кожен тип колекції з довідника Kubernetes API.

Деякі інструменти, такі як kubectl, представляють механізм колекцій Kubernetes трохи інакше, ніж сам API Kubernetes. Оскільки вихідні дані kubectl можуть включати відповідь з декількох операцій list на рівні API, kubectl представляє список елементів, використовуючи kind: List. Наприклад:

kubectl get services -A -o yaml

apiVersion: v1
kind: List
metadata:
  resourceVersion: ""
  selfLink: ""
items:
- apiVersion: v1
  kind: Service
  metadata:
    creationTimestamp: "2021-06-03T14:54:12Z"
    labels:
      component: apiserver
      provider: kubernetes
    name: kubernetes
    namespace: default
...
- apiVersion: v1
  kind: Service
  metadata:
    annotations:
      prometheus.io/port: "9153"
      prometheus.io/scrape: "true"
    creationTimestamp: "2021-06-03T14:54:14Z"
    labels:
      k8s-app: kube-dns
      kubernetes.io/cluster-service: "true"
      kubernetes.io/name: CoreDNS
    name: kube-dns
    namespace: kube-system

Отримання ресурсів у вигляді таблиць

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

Щоб уникнути можливих обмежень, описаних вище, клієнти можуть запитувати табличну репрезентацію обʼєктів, делегуючи серверу специфічні деталі виводу. API Kubernetes реалізує стандартні HTTP-узгодження щодо типу контенту: передача заголовка Accept, що містить значення application/json;as=Table;g=meta.k8s.io;v=v1 з запитом GET попросить сервер повернути обʼєкти у форматі таблиці.

Наприклад, список усіх Podʼів у кластері у форматі таблиці.

GET /api/v1/pods
Accept: application/json;as=Table;g=meta.k8s.io;v=v1
---
200 OK
Content-Type: application/json

{
    "kind": "Table",
    "apiVersion": "meta.k8s.io/v1",
    ...
    "columnDefinitions": [
        ...
    ]
}

Для типів ресурсів API, які не мають табличного визначення, відомого панелі управління, сервер API повертає стандартну таблицю, яка складається з полів name та creationTimestamp ресурсу.

GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
---
200 OK
Content-Type: application/json
...

{
    "kind": "Table",
    "apiVersion": "meta.k8s.io/v1",
    ...
    "columnDefinitions": [
        {
            "name": "Name",
            "type": "string",
            ...
        },
        {
            "name": "Created At",
            "type": "date",
            ...
        }
    ]
}

Не всі типи ресурсів API підтримують табличну відповідь; наприклад, CustomResourceDefinitions можуть не визначати відповідність полів таблиці, а APIService, що розширює основний API Kubernetes може взагалі не обслуговувати табличні відповіді. Якщо ви створюєте клієнта, що використовує інформацію з таблиці та який повинен працювати з усіма типами ресурсів, включаючи розширення, ви повинні робити запити, які вказують кілька типів контенту у заголовку Accept. Наприклад:

Accept: application/json;as=Table;g=meta.k8s.io;v=v1, application/json

Якщо клієнт вказує, що приймає тільки ...;as=Table;g=meta.k8s.io;v=v1, сервери, які не підтримують табличні відповіді, повернуть код помилки 406.

Якщо в цьому випадку бажано повернутися до повних обʼєктів, клієнти можуть додати ,application/json (або будь-яке інше підтримуване кодування) до свого заголовка Accept і обробляти таблиці або повні обʼєкти у відповіді:

Accept: application/json;as=Table;g=meta.k8s.io;v=v1,application/json`

Для отримання додаткової інформації про узгодження типу вмісту див. MDN Content Negotiation.

Отримання лише метаданих

Щоб отримати часткові метадані обʼєкта, ви можете запросити відповіді тільки з метаданими в заголовку Accept. API Kubernetes реалізує варіант узгодження типу вмісту HTTP. Як клієнт, ви можете надати заголовок Accept з бажаним типом медіа, а також параметрами, які вказують, що ви хочете отримати тільки метадані. Наприклад: Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1 для JSON для конкретного обʼєкта та: Accept: application/json;as=PartialObjectMetadataList;g=meta.k8s.io;v=v1 для списку.

Наприклад, щоб отримати перелік усіх подів у кластері, у всіх просторах імен, але повернути тільки метадані для кожного пода:

GET /api/v1/pods
Accept: application/json;as=PartialObjectMetadataList;g=meta.k8s.io;v=v1
---
200 OK
Content-Type: application/json

{
    "kind": "PartialObjectMetadataList",
    "apiVersion": "meta.k8s.io/v1",
    "metadata": {
        "resourceVersion": "...",
    },
    "items": [
        {
            "apiVersion": "meta.k8s.io/v1",
            "kind": "PartialObjectMetadata",
            "metadata": {
                "name": "pod-1",
                ...
            }
        },
        {
            "apiVersion": "meta.k8s.io/v1",
            "kind": "PartialObjectMetadata",
            "metadata": {
                "name": "pod-2",
                ...
            }
        }
    ]
}

На запит про колекцію сервер API повертає PartialObjectMetadataList. На запит про окремий обʼєкт сервер API повертає представлення PartialObjectMetadata цього обʼєкта. В обох випадках обʼєкти, що повертаються, містять лише поле metadata. Поля spec та status опускаються.

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

Ви можете запросити отримання тільки метаданих для всіх доступних типів медіа (JSON, YAML, CBOR і Kubernetes Protobuf). Для Protobuf заголовок Accept буде таким: application/vnd.kubernetes.protobuf;as=PartialObjectMetadata;g=meta.k8s.io;v=v1.

Сервер API Kubernetes підтримує часткове отримання даних для майже всіх своїх вбудованих API. Однак ви можете використовувати Kubernetes для доступу до інших серверів API через aggregation layer, і ці API можуть не підтримувати часткове отримання даних.

Якщо клієнт використовує заголовок Accept, щоб запросити відповідь тільки ...;as=PartialObjectMetadata;g=meta.k8s.io;v=v1, і звертається до API, який не підтримує часткові відповіді, Kubernetes відповість помилкою HTTP 406.

Якщо в цьому випадку бажано повернутися до повних обʼєктів, клієнти можуть додати ,application/json (або будь-яке інше підтримуване кодування) до свого заголовка Accept і обробляти або PartialObjectMetadata, або повні обʼєкти у відповіді. Рекомендується вказати, що перевага надається частковій відповіді, використовуючи параметр q (quality). Наприклад:

Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1, application/json;q=0.9

Для отримання додаткової інформації про узгодження типу вмісту див. MDN Content Negotiation.

Видалення ресурсів

Коли ви видаляєте ресурс, цей процес проходить у два етапи:

1. Завершення (finalization)
2. Видалення (removal)

{
  "kind": "ConfigMap",
  "apiVersion": "v1",
  "metadata": {
    "finalizers": ["url.io/neat-finalization", "other-url.io/my-finalizer"],
    "deletionTimestamp": null,
  }
}

Коли клієнт вперше надсилає запит на видалення ресурсу, .metadata.deletionTimestamp встановлюється на поточний час. Після встановлення .metadata.deletionTimestamp, зовнішні контролери, які працюють з завершувачами (finalizers), можуть почати виконувати свою очистку в будь-який час, у будь-якому порядку.

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

Поле .metadata.finalizers є спільним: будь-який áктор з дозволом може змінювати його порядок. Якби список завершувачів оброблявся по порядку, це могло б призвести до ситуації, коли компонент, відповідальний за перший завершувач у списку, чекає на якийсь сигнал (значення поля, зовнішню систему або інше), що створюється компонентом, відповідальним за завершувач пізніше у списку, що призводить до застярягання всього списку.

Без примусового впорядкування завершувачі можуть вільно визначати свій власний порядок і не є вразливими до змін у списку.

Після видалення останнього завершувача ресурс фактично видаляється з etcd.

Примусове видалення

Увімкнувши опцію видалення ignoreStoreReadErrorWithClusterBreakingPotential, користувач може виконати небезпечну операцію примусового видалення нерозшифрованого/пошкодженого ресурсу. Ця опція знаходиться за функціональною можоивістю ALPHA, і стандартно вона вимкнена. Щоб скористатися цією опцією, оператор кластера повинен увімкнути її за допомогою параметра командного рядка --feature-gates=AllowUnsafeMalformedObjectDeletion=true.

Ресурс вважається пошкодженим, якщо він не може бути успішно вилучений зі сховища через а) помилку перетворення (наприклад, помилку розшифрування), або б) обʼєкт не вдалося декодувати. Сервер API спочатку намагається виконати звичайне видалення, і якщо це не вдається з помилкою corrupt resource, він запускає операцію примусового видалення. Операція примусового видалення є небезпечною, оскільки вона ігнорує обмеження фіналізатора і пропускає перевірку передумов.

Стандартне значення для цієї опції — false, це забезпечує зворотну сумісність. Для запиту delete з параметром ignoreStoreReadErrorWithClusterBreakingPotential, встановленим у значення true, поля dryRun, gracePeriodSeconds, orphanDependents, preconditions і propagationPolicy слід залишити не встановленими.

API для одного ресурсу

API Kubernetes з дієсловами get, create, update, patch, delete та proxy підтримують тільки одиничні ресурси. Ці дієслова з підтримкою одиничного ресурсу не підтримують надсилання кількох ресурсів разом в упорядкованому або неупорядкованому списку чи транзакції.

Коли клієнти (включаючи kubectl) виконують дії з набором ресурсів, клієнт робить серію одиничних API запитів до ресурсу, а потім, за потреби, агрегує відповіді.

На відміну від цього, API Kubernetes з дієсловами list і watch дозволяють отримувати кілька ресурсів, а deletecollection дозволяє видаляти кілька ресурсів.

Валідація полів

Kubernetes завжди перевіряє тип полів. Наприклад, якщо поле в API визначене як число, ви не можете встановити це поле в текстове значення. Якщо поле визначене як масив рядків, ви можете надати тільки масив. Деякі поля можна пропустити, інші поля є обовʼязковими. Пропуск обовʼязкового поля у запиті API є помилкою.

Якщо ви зробите запит з додатковим полем, яке не розпізнається панеллю управління кластера, тоді поведінка сервера API є складнішою.

Типово, сервер API видаляє поля, які він не розпізнає, з вхідних даних, які він отримує (наприклад, тіло JSON запиту PUT).

Є дві ситуації, коли сервер API видаляє поля, які ви надали у HTTP-запиті.

Ці ситуації такі:

1. Поле не розпізнається, оскільки воно не входить до схеми OpenAPI ресурсу. (Одним винятком є CRDs, які явно обирають не обрізати невідомі поля через x-kubernetes-preserve-unknown-fields).
2. Поле дублюється в обʼєкті.

Валідація для нерозпізнаних або дубльованих полів

З версії 1.25 і далі, нерозпізнані або дубльовані поля в обʼєкті виявляються через валідацію на сервері при використанні HTTP-дієслів, які можуть надсилати дані (POST, PUT та PATCH). Можливі рівні валідації: Ignore, Warn (стандартно) та Strict.

Ignore

Сервер API успішно обробляє запит так, ніби у ньому немає неправильних полів, відкидаючи всі невідомі та дубльовані поля та не повідомляючи про це.

Warn

(Стандартно) Сервер API успішно обробляє запит і надсилає клієнту попередження. Попередження надсилається за допомогою заголовка відповіді Warning:, додаючи один елемент попередження для кожного невідомого або дубльованого поля. Для отримання додаткової інформації про попередження та API Kubernetes дивіться статтю блогу Warning: Helpful Warnings Ahead.

Strict

Сервер API відхиляє запит з помилкою 400 Bad Request, коли виявляє будь-які невідомі або дубльовані поля. Повідомлення відповіді від сервера API вказує всі невідомі або дубльовані поля, які сервер API виявив.

Рівень валідації полів встановлюється параметром запиту fieldValidation.

Інструменти, які надсилають запити на сервер (такі як kubectl), можуть встановлювати свої власні типові значення, які відрізняються від рівня валідації Warn, що стандартно використовується сервером API.

Інструмент kubectl використовує прапорець --validate для встановлення рівня валідації полів. Він приймає значення ignore, warn та strict, а також приймає значення true (еквівалентно strict) і false (еквівалентно ignore). Станадртне налаштування валідації для kubectl — це --validate=true, що означає сувору валідацію полів на стороні сервера.

Коли kubectl не може підключитися до сервера API з валідацією полів (сервери API до Kubernetes 1.27), він повернеться до використання валідації на стороні клієнта. Валідація на стороні клієнта буде повністю видалена у майбутній версії kubectl.

Починаючи з версії 1.33, Kubernetes (включно з версією 1.35) пропонує спосіб визначення перевірки полів за допомогою декларативних теґів. Це корисно для тих, хто бере участь у розробці самого Kubernetes, а також для тих, хто пише власний API з використанням бібліотек Kubernetes. Щоб дізнатися більше, див. Декларативна перевірка API.

Dry-run

При використанні HTTP-дієслів, які можуть змінювати ресурси (POST, PUT, PATCH і DELETE), ви можете надіслати свій запит у режимі dry run. Режим dry run допомагає оцінити запит через типові етапи обробки запиту (ланцюг допумків, валідацію, конфлікти злиття) аж до збереження обʼєктів у сховищі. Тіло відповіді на запит є максимально наближеним до відповіді у режимі non-dry-run. Kubernetes гарантує, що dry-run запити не будуть збережені в сховищі і не матимуть жодних інших побічних ефектів.

Виконання dry-run запиту

Dry-run активується встановленням параметра запиту dryRun. Цей параметр є рядковим, діє як перерахування, і єдині прийнятні значення:

[без значення]

Дозволити побічні ефекти. Ви запитуєте це за допомогою рядка запиту типу ?dryRun або ?dryRun&pretty=true. Відповідь є остаточним обʼєктом, який був би збережений, або помилкою, якщо запит не може бути виконаний.

All

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

Коли ви встановлюєте ?dryRun=All, усі відповідні контролерів допуску виконуються, перевіряючи запит після зміни, злиття виконується для PATCH, поля заповнюються станадартними значеннями, і проводиться валідація схеми. Зміни не зберігаються в базовому сховищі, але остаточний обʼєкт, який був би збережений, все ще повертається користувачеві разом із звичайним кодом статусу.

Якщо версія запиту без dry-run викликала б контролер доступу, який має побічні ефекти, запит буде відхилений, щоб уникнути небажаних побічних ефектів. Усі вбудовані втулки контролю доступу підтримують dry-run. Додатково, admission webhooks можуть оголосити у своїй конфігураційній моделі, що вони не мають побічних ефектів, встановивши поле sideEffects на None.

Приклад dry-run запиту, який використовує ?dryRun=All:

POST /api/v1/namespaces/test/pods?dryRun=All
Content-Type: application/json
Accept: application/json

Відповідь буде виглядати так само, як для запиту без dry-run, але значення деяких згенерованих полів можуть відрізнятися.

Згенеровані значення

Деякі значення обʼєкта зазвичай генеруються перед його збереженням. Важливо не покладатися на значення цих полів, встановлених dry-run запитом, оскільки ці значення, ймовірно, будуть відрізнятися в dry-run режимі від реального запиту. Деякі з цих полів:

• name: якщо встановлено generateName, name матиме унікальне випадкове імʼя
• creationTimestamp / deletionTimestamp: фіксує час створення/видалення
• UID: унікально ідентифікує обʼєкт і генерується випадково (недетерміновано)
• resourceVersion: відстежує збережену версію обʼєкта
• Будь-яке поле, встановлене мутаційним контролером допуску
• Для ресурсу Service: Порти або IP-адреси, які kube-apiserver надає обʼєктам Service

Авторизація dry-run

Авторизація для dry-run і non-dry-run запитів ідентична. Таким чином, щоб виконати dry-run запит, ви повинні мати дозвіл на виконання non-dry-run запиту.

Наприклад, щоб виконати dry-run patch для Deployment, ви повинні мати дозвіл на виконання цього patch. Ось приклад правила для Kubernetes RBAC, що дозволяє робити patch для Deployment:

rules:
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["patch"]

Дивіться Огляд авторизації.

Оновлення наявних ресурсів

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

Ви можете перезаписати (оновити) наявний ресурс, наприклад, ConfigMap, використовуючи HTTP PUT. Для запиту PUT відповідальність за вказання resourceVersion (отриманого з обʼєкта, що оновлюється) лежить на клієнті. Kubernetes використовує інформацію resourceVersion, щоб сервер API міг виявити втрачені оновлення і відхилити запити від клієнта, який не актуальний для кластера. У разі зміни ресурсу (коли resourceVersion, надана клієнтом, застаріла), сервер API повертає відповідь з помилкою 409 Conflict.

Замість надсилання запиту PUT клієнт може надіслати інструкцію серверу API для накладання патчу до наявного ресурсу. Патч зазвичай підходить, якщо зміна, яку клієнт хоче внести, не залежить від наявних даних. Клієнти, яким потрібне ефективне виявлення втрачених оновлень, повинні розглянути можливість зробити свій запит умовним до існуючого resourceVersion (або HTTP PUT, або HTTP PATCH), а потім обробити будь-які повтори, які можуть знадобитися у разі конфлікту.

API Kubernetes підтримує чотири різні операції PATCH, які визначаються відповідним заголовком HTTP Content-Type:

application/apply-patch+yaml

Серверне застосування YAML (специфічне розширення Kubernetes, засноване на YAML). Всі документи JSON є дійсними в YAML, тому ви також можете надавати JSON, використовуючи цей тип медіа. Дивіться серіалізація для серверного застосування для отримання додаткової інформації. Для Kubernetes це операція створення, якщо обʼєкт не існує, або операція накладання патчу, якщо обʼєкт вже існує.

application/json-patch+json

JSON Patch, як визначено в RFC6902. JSON патч — це послідовність операцій, які виконуються з ресурсом; наприклад, {"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}. Для Kubernetes це операція накладання патчу. Патч з використанням application/json-patch+json може включати умови для перевірки консистентності, дозволяючи операції зазнати невдачі, якщо ці умови не виконуються (наприклад, щоб уникнути втрати оновлення).

application/merge-patch+json

JSON Merge Patch, як визначено в RFC7386. JSON Merge Patch фактично є частковим представленням ресурсу. Поданий JSON комбінується з поточним ресурсом для створення нового, а потім новий зберігається. Для Kubernetes це операція накладання патчу.

application/strategic-merge-patch+json

Strategic Merge Patch (специфічне розширення Kubernetes на основі JSON). Strategic Merge Patch — це власна реалізація JSON Merge Patch. Ви можете використовувати Strategic Merge Patch лише з вбудованими API або з агрегованими серверами API, які мають спеціальну підтримку для цього. Ви не можете використовувати application/strategic-merge-patch+json з будь-яким API, визначеним за допомогою CustomResourceDefinition.

Примітка:

Механізм серверного застосування Kubernetes замінив Strategic Merge Patch.

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

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

Дивіться Серверне застосування для отримання додаткової інформації.

Вибір механізму оновлення

HTTP PUT для заміни наявного ресурсу

Операція оновлення (HTTP PUT) проста у виконанні та гнучка, але має недоліки:

• Потрібно вирішувати конфлікти, де resourceVersion обʼєкта змінюється між моментом його читання клієнтом і спробою записувати назад. Kubernetes завжди виявляє конфлікт, але вам як авторові клієнта потрібно реалізувати повторні спроби.
• Ви можете випадково видаляти поля, якщо декодуєте обʼєкт локально (наприклад, використовуючи client-go, ви можете отримати поля, які ваш клієнт не вміє обробляти, і потім видаляти їх під час оновлення).
• Якщо на обʼєкт накладається багато конкурентних операцій (навіть на поле або набір полів, які ви не намагаєтеся редагувати), ви можете мати проблеми з надсиланням оновлення. Проблема гостріша для великих обʼєктів та для обʼєктів з багатьма полями.

HTTP PATCH з використанням JSON Patch

Оновлення патчем корисне через такі причини:

• Оскільки ви надсилаєте лише різницю, ви маєте менше даних для надсилання у запиті PATCH.
• Ви можете робити зміни, які ґрунтуються на наявних значеннях, наприклад, копіювати значення певного поля в анотацію.
• На відміну від оновлення (HTTP PUT), ваші зміни можуть відбуватися відразу навіть при частих змінах не повʼязаних полів: зазвичай вам не потрібно повторювати спроби.
  • Вам все ще може знадобитися вказати resourceVersion (щоб відповідати існуючому обʼєкту), якщо ви хочете бути особливо обережними, щоб уникнути втрати оновлень.
  • Все ж це хороша практика написати деяку логіку повторної спроби у випадку помилок.
• Ви можете використовувати тестові умови для обережного створення конкретних умов оновлення. Наприклад, ви можете збільшити лічильник без його читання, якщо існуюче значення відповідає вашим очікуванням. Ви можете це зробити без ризику втрати оновлення, навіть якщо обʼєкт змінився іншим чином з моменту вашого останнього запису до нього. (Якщо тестова умова не виконається, ви можете використовувати поточне значення і потім записати змінене число).

Проте:

• Вам потрібна більша локальна (клієнтська) логіка для створення патчу; дуже корисно мати реалізацію бібліотеки JSON Patch або навіть створення JSON Patch специально для Kubernetes.
• Як автору клієнтського програмного забезпечення, вам потрібно бути обережним при створенні патчу (тіла запиту HTTP), щоб не видаляти поля (порядок операцій має значення).

HTTP PATCH з використанням Server-Side Apply

Серверне застосування має чіткі переваги:

• Одноразовий прохід веред-назад: зазвичай спочатку не потребує виконання GET запиту.
  • і ви все ще можете виявляти конфлікти для неочікуваних змін
  • у вас є можливість примусово перезаписати конфлікт, якщо це доцільно
• Реалізація клієнта легка для створення.
• Ви отримуєте атомарну операцію створення або оновлення без додаткових зусиль (аналогічно UPSERT у деяких діалектах SQL).

Проте:

• Серверне застосування зовсім не працює для змін полів, які залежать від поточного значення обʼєкта.
• Ви можете застосовувати оновлення лише до обʼєктів. Деякі ресурси в HTTP API Kubernetes не є обʼєктами (вони не мають поля .metadata), а серверне застосування стосується лише обʼєктів Kubernetes.

Версії ресурсів

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

Рядки версій ресурсів можна впорядкувати як монотонно зростаючі цілі числа в межах одного типу ресурсів для всіх типів, що обслуговуються kube-apiserver. Сюди входять вбудовані типи API та типи, що підтримуються визначеннями власних ресурсів. Обидві версії ресурсів повинні бути з обʼєктів однієї групи API та одного типу ресурсів. Наприклад, можна порівняти версії ресурсів двох розгортань з групи API застосунків, але не можна порівняти версії ресурсів Pod і Deployment. За умови, що два об’єкти отримано з одного типу ресурсів API, їх можна порівняти, навіть якщо вони знаходяться в різних просторах імен.

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

Починаючи з Kubernetes 1.35, можливість впорядкування версій ресурсів для всіх типів Kubernetes включена до вимог Certified Kubernetes. Базові обʼєкти API та власні ресурси користувача повинні бути упорядкованими як монотонно зростаюче ціле число для будь-якої реалізації APIServer 1.35+, щоб пройти тести на відповідність.

Щоб порівняти два рядки версій ресурсів:

Переконайтеся, що вони відповідають таким вимогам:

• Обидві версії ресурсів повинні бути одного типу, як описано вище
• Обидві повинні починатися з цифри 1-9 і містити тільки цифри 0-9
• Версії ресурсів порівнюються як довільні десяткові цілі числа з бітовим розміром

Щоб порівняти їх, не покладаючись на фіксований бітовий розмір, можна порівняти їх як рядки. Бітовий розмір не повинен вважатися фіксованою величиною.

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

• Якщо вони не мають однакової довжини, більшою вважається довша (наприклад, "123" > "23")
• Якщо вони мають однакову довжину, більшою вважається лексикографічно більша (наприклад, "234" > "123")

Деякі приклади порівнянь версій ресурсів, які повинні працювати:

• "2345678901234567890123456789012345678901" > "345678901234567890123456789012345678901"
• "345678901234567890123456789012345678901" == "345678901234567890123456789012345678901"
• "345678901234567890123456789012345678900" < "345678901234567890123456789012345678901"

Для виконання цього порівняння доступний допоміжний метод для client-go.

Поля resourceVersion в метаданих

Клієнти знаходять версії ресурсів в ресурсах, включаючи ресурси з потоку відповіді під час спостереження (watch) або при отримані переліку (list) ресурсів.

v1.meta/ObjectMeta — metadata.resourceVersion екземпляра ресурсу ідентифікує версію ресурсу, на якій останній раз він був змінений.

v1.meta/ListMeta — metadata.resourceVersion колекції ресурсів (відповідь на перелік (list)) ідентифікує версію ресурсу, на якій була створена колекція.

Параметри resourceVersion у рядках запитів

Операції отримання (get), переліку (list) та спостереження (watch) підтримують параметр resourceVersion. Починаючи з версії v1.19, сервери API Kubernetes також підтримують параметр resourceVersionMatch у запитах list.

Сервер API інтерпретує параметр resourceVersion по-різному, залежно від операції, яку ви запитуєте, та від значення resourceVersion. Якщо ви встановлюєте resourceVersionMatch, то це також впливає на спосіб порівняння.

Семантика для операцій get та list

Для операцій get та list, семантика параметра resourceVersion така:

get:

list:

Починаючи з версії v1.19, сервери API Kubernetes підтримують параметр resourceVersionMatch у запитах list. Якщо ви встановлюєте як resourceVersion, так і resourceVersionMatch, то параметр resourceVersionMatch визначає, як сервер API інтерпретує resourceVersion.

Вам завжди слід встановлювати параметр resourceVersionMatch, коли ви встановлюєте resourceVersion у запиті list. Однак будьте готові обробляти випадок, де сервер API, що відповідає, не підтримує resourceVersionMatch та ігнорує його.

Крім випадків сильних вимог до консистентності, використання resourceVersionMatch=NotOlderThan та відомої resourceVersion є бажаним, оскільки це може забезпечити кращу продуктивність та масштабованість вашого кластеру, ніж залишати resourceVersion і resourceVersionMatch невстановленими, що вимагає отримання кворуму для обслуговування.

Встановлення параметра resourceVersionMatch без встановлення resourceVersion є недійсним.

Ця таблиця пояснює поведінку запитів list з різними комбінаціями resourceVersion та resourceVersionMatch:

Сенс семантики операцій get та list такий:

Any

Повернути дані на будь-якій версії ресурсу. Вибирається найновіша доступна версія ресурсу, але не потрібна сильна консистентність; дані на будь-якій версії ресурсу можуть бути обслуговані. Є можливість отримати дані на значно старішій версії ресурсу, яку клієнт раніше спостерігав, особливо в конфігураціях високої доступності через розділи або застарілі кеші. Клієнти, які не можуть терпіти це, не повинні використовувати цю семантику. Завжди обслуговується з кешу спостереження, покращуючи продуктивність та зменшуючи навантаження на etcd.

Most recent

Повернути дані на найновішій версії ресурсу. Повернені дані повинні бути консистентними (детально: обслуговуються з etcd за допомогою кворумного читання). Для etcd версій v3.4.31+ та v3.5.13+ Kubernetes 1.35 обслуговує "найсвіжіші" читання з watch cache: внутрішнього, вбудованого в памʼять сховища всередині API сервера, що кешує та відображає стан даних, збережених у etcd. Kubernetes запитує сповіщення про прогрес, щоб підтримувати консистентність кешу з шаром збереження даних (persistence layer) у etcd. Версії Kubernetes з v1.28 до v1.30 також підтримували цю функцію, але як Alpha, вона не рекомендувалася для використання в операційному середовищі і не була стандартно увімкненою до випуску v1.31.

NotOlderThan

Повернути дані, які є принаймні так новими, як наданий resourceVersion. Вибирається найновіша доступна інформація, але будь-яка інформація, яка не старше наданої resourceVersion, може бути обслугована. Для запитів list до серверів, які підтримують параметр resourceVersionMatch, це гарантує, що .metadata.resourceVersion колекції не старше вказаної resourceVersion, але не надає гарантії щодо .metadata.resourceVersion будь-яких елементів у цій колекції. Завжди обслуговується з кешу спостереження, покращуючи продуктивність та зменшуючи навантаження на etcd.

Exact

Повернути дані на точній версії ресурсу, яка надана. Якщо надана resourceVersion недоступна, сервер відповідає HTTP 410 Gone. Для запитів list до серверів, які підтримують параметр resourceVersionMatch, це гарантує, що .metadata.resourceVersion колекції співпадає з resourceVersion, яку ви запросили у рядку запиту. Ця гарантія не поширюється на .metadata.resourceVersion будь-яких елементів у цій колекції.

Зі стандартно увімкненою функціональною можливістю ListFromCacheSnapshot сервер API намагатиметься надіслати відповідь зі знімка кешу, якщо він доступний з версією resourceVersion, старішою за запитувану. Це покращує продуктивність і зменшує навантаження на etcd. Сервер API починає без знімків, створює новий знімок на кожну подію спостереження і зберігає їх, поки не виявить, що etcd був стиснутий, або якщо кеш заповнений подіями старшими за 75 секунд. Якщо надана resourceVersion недоступна, сервер повернеться до etcd.

Continuation

Повертає наступну сторінку даних для запиту посторінкового списку, забезпечуючи узгодженість з точним значенням resourceVersion, встановленим початковим запитом у послідовності. Відповідь на list запити з обмеженням включає continue token, який кодує resourceVersion і останню спостережувану позицію, з якої можна продовжити список. Якщо resourceVersion у наданому continue token недоступний, сервер відповідає HTTP 410 Gone. Зі стандартно увімкненою функціональною можливістю ListFromCacheSnapshot сервер API намагатиметься надіслати відповідь зі знімка кешу, якщо він доступний з версією resourceVersion, старішою за запитувану. Це покращує продуктивність і зменшує навантаження на etcd. Сервер API починає без знімків, створює новий знімок на кожну подію спостереження і зберігає їх, поки не виявить, що etcd був стиснутий, або якщо кеш заповнений подіями старшими за 75 секунд. Якщо надана resourceVersion недоступна, сервер повернеться до etcd.

При використанні resourceVersionMatch=Не старше та встановленому ліміті клієнти мають обробляти відповіді HTTP 410 Gone. Наприклад, клієнт може повторно спробувати з новішою resourceVersion або використовувати resourceVersion="".

При використанні resourceVersionMatch=Точно та не встановленому ліміті, клієнти мають перевірити, що .metadata.resourceVersion колекції співпадає з запитаною resourceVersion, і обробити випадок, коли це не так. Наприклад, клієнт може використовувати запит з встановленим лімітом.

Семантика для операції watch

Для операцій watch, семантика параметра resourceVersion така:

watch:

Сенс цієї семантики для watch такий:

Отримати стан і почати з будь-якого

Почати watch на будь-якій версії ресурсу; найбільш нова доступна версія є переважною, але не обовʼязковою. Дозволено будь-яку початкову версію ресурсу. Можливо, що watch почнеться на набагато старішій версії ресурсу, яку клієнт раніше спостерігав, особливо в конфігураціях високої доступності через розділи або застарілі кеші. Клієнти, які не можуть терпіти таке відмотування назад, не повинні починати watch з цією семантикою. Для встановлення початкового стану, watch починається з синтетичних подій "Added" для всіх екземплярів ресурсів, які існують на початковій версії ресурсу. Усі наступні події watch стосуються всіх змін, що сталися після початкової версії ресурсу, з якої почався watch.

Увага:

Ініціалізовані таким чином watch можуть повертати довільно застарілі дані. Будь ласка, перевірте цю семантику перед використанням і надайте перевагу іншій семантиці, де це можливо.

Отримати стан і почати з найновішого

Почати watch на найбільш новій версії ресурсу, яка повинна бути консистентною (детально: обслуговується з etcd за допомогою отримання кворуму). Для встановлення початкового стану watch починається з синтетичних подій "Added" для всіх екземплярів ресурсів, які існують на початковій версії ресурсу. Усі наступні події watch стосуються всіх змін, що сталися після початкової версії ресурсу, з якої почався watch.

Почати точно з

Почати watch на точній версії ресурсу. Події watch стосуються всіх змін після наданої версії ресурсу. На відміну від "Отримати стан і почати з найновішого" та "Отримати стан і почати з будь-якого", watch не починається з синтетичних подій "Added" для наданої версії ресурсу. Вважається, що клієнт вже має початковий стан на стартовій версії ресурсу, оскільки клієнт надав цю версію ресурсу.

Відповіді "410 Gone"

Сервери не зобовʼязані зберігати всі старі версії ресурсів і можуть повернути код HTTP 410 (Gone), якщо клієнт запитує resourceVersion, який старіший, ніж версія, збережена сервером. Клієнти повинні бути готові обробляти відповіді 410 (Gone). Дивіться розділ Ефективне виявлення змін для отримання додаткової інформації про те, як обробляти відповіді 410 (Gone) при спостереженні за ресурсами.

Якщо ви запитуєте resourceVersion, який знаходиться за межами допустимого діапазону, то, залежно від того, чи обслуговується запит з кешу чи ні, API-сервер може відповісти HTTP-відповіддю 410 Gone.

Недоступні версії ресурсів

Сервери не зобовʼязані обслуговувати нерозпізнані версії ресурсів. Якщо ви запитуєте list або get для версії ресурсу, яку API-сервер не розпізнає, то API-сервер може або:

• почекати трохи, поки версія ресурсу не стане доступною, а потім завершити з тайм-аутом і відповіддю 504 (Gateway Timeout), якщо надана версія ресурсу не стане доступною в розумний термін;
• відповісти заголовком Retry-After, вказуючи, через скільки секунд клієнт повинен повторити запит.

Якщо ви запитуєте версію ресурсу, яку API-сервер не розпізнає, kube-apiserver додатково ідентифікує свої відповіді на помилки повідомленням Too large resource version.

Якщо ви робите запит watch для нерозпізнаної версії ресурсу, API-сервер може чекати невизначений час (до тайм-ауту запиту), поки версія ресурсу не стане доступною.

2.3 - Server-Side Apply

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

Server-Side Apply (Серверне застосування) надає необовʼязковий механізм для контролера вашого кластера, щоб відстежувати зміни в полях обʼєкта. На рівні конкретного ресурсу, Server-Side Apply записує та відстежує інформацію про контроль над полями цього обʼєкта.

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

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

Порівняння з Client-Side Apply пояснює, як Server-Side Apply відрізняється від початкової реалізації kubectl apply на стороні клієнта.

Управління полями

Kubernetes API сервер відстежує керовані поля для всіх новостворених обʼєктів.

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

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

Для того, щоб користувач міг керувати полем в контексті Server-Side Apply, він повинен покладатися на те, що значення поля не зміниться. Користувач, який останнім висловив свою думку щодо значення поля, буде записаний як поточний менеджер поля. Це можна зробити, змінивши дані менеджера поля явним чином за допомогою HTTP POST (створення), PUT (оновлення), або не-застосувального PATCH (патч). Ви також можете оголосити та записати менеджера поля, включивши значення для цього поля в операції Server-Side Apply.

Запит на патч в контексті Server-Side Apply вимагає від клієнта вказати свою ідентичність як менеджера поля. При використанні Server-Side Apply спроба змінити поле, що контролюється іншим менеджером, призведе до відхилення запиту, якщо клієнт не виконає примусове перевизначення. Для деталей щодо примусових перевизначень дивіться Конфлікти.

Коли два або більше аплікатора встановлюють поле на однакове значення, вони спільно володіють цим полем. Будь-яка спроба змінити значення спільного поля будь-ким з аплікаторів призведе до конфлікту. Спільні власники поля можуть відмовитися від права власності на поле, здійснивши запит на патч в контексті Server-Side Apply, який не включає це поле.

Деталі управління полями зберігаються в полі managedFields, яке є частиною metadata обʼєкта.

Якщо ви видалите поле з маніфесту і застосуєте цей маніфест, Server-Side Apply перевірить, чи є інші менеджери полів, які також володіють цим полем. Якщо поле не належить жодному іншому менеджеру полів, воно буде або видалене з поточного обʼєкта, або скинуте до стандартного значення, якщо таке є. Те саме правило застосовується до елементів асоціативного списку або map.

У порівнянні з (застарілою) kubectl.kubernetes.io/last-applied-configuration анотацією, яка управляється kubectl, Server-Side Apply використовує більш декларативний підхід, який відстежує управління полями користувача (або клієнта), а не останній застосований стан користувача. Побічним ефектом використання Server-Side Apply є також доступність інформації про те, який менеджер поля управляє кожним полем в обʼєкті.

Приклад

Простий приклад обʼєкта, створеного за допомогою Server-Side Apply, може виглядати так:

---
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.

Конфлікти

Конфлікт — це спеціальна помилка статусу, яка виникає, коли операція Apply намагається змінити поле, на яке інший менеджер також заявляє права на керування. Це запобігає ненавмисному перезапису значення, встановленого іншим користувачем. У разі конфлікту аплікатор має 3 варіанти для вирішення конфліктів:

• Перезаписати значення, стати єдиним менеджером: Якщо перезапис значення був навмисним (або якщо аплікатор є автоматичним процесом, таким як контролер), аплікатор повинен встановити параметр запиту force в true (для kubectl apply використовується параметр командного рядка --force-conflicts) і повторити запит. Це змусить операцію завершитись успішно, змінить значення поля та видалить це поле з усіх інших записів менеджерів у managedFields.

• Не перезаписувати значення, відмовитися від права управління: Якщо аплікатор більше не піклується про значення поля, він може видалити його зі своєї локальної моделі ресурсу і зробити новий запит, виключивши це конкретне поле. Це залишить значення незмінним і видалить поле із запису аплікатора у managedFields.

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

Менеджери полів

Менеджери визначають окремі робочі процеси, які змінюють обʼєкт (особливо корисно при конфліктах!), і можуть бути вказані через параметр запиту fieldManager як частина запиту на зміни. Коли ви застосовуєте зміни до ресурсу, параметр fieldManager є обовʼязковим. Для інших оновлень сервер API визначає ідентифікатор менеджера поля з заголовка HTTP "User-Agent:" (якщо він присутній).

Коли ви використовуєте інструмент kubectl для виконання операції Server-Side Apply, kubectl типово встановлює ідентифікатор менеджера в "kubectl".

Серіалізація

На рівні протоколу Kubernetes представляє тіла повідомлень Server-Side Apply у форматі YAML, з медіа типом application/apply-patch+yaml.

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

Ось приклад тіла повідомлення Server-Side Apply (повністю специфікований намір):

{
  "apiVersion": "v1",
  "kind": "ConfigMap"
}

(це зробить оновлення без змін, за умови, що це було надіслано як тіло patch запиту до дійсного ресурсу v1/configmaps, з відповідним заголовком запиту Content-Type).

Операції з області управління полями

Операції API Kubernetes, де враховується управління полями, включають:

1. Server-Side Apply (HTTP PATCH, з типом контенту application/apply-patch+yaml)
2. Заміна наявного обʼєкта (update для Kubernetes; PUT на рівні HTTP)

Обидві операції оновлюють .metadata.managedFields, але поводяться трохи по-різному.

Якщо не вказано примусове перезаписування, операція apply, що зустрічає конфлікти на рівні полів, завжди зазнає невдачі; у противагу, якщо зміну здійснено за допомогою update, що впливає на кероване поле, конфлікт ніколи не призводить до невдачі операції.

Усі запити Server-Side Apply patch повинні ідентифікувати себе, надаючи параметр запиту fieldManager, тоді як цей параметр запиту є необовʼязковим для операцій update. Нарешті, при використанні операції Apply ви не можете визначати managedFields у тілі запиту, який ви надсилаєте.

Приклад обʼєкта з декількома менеджерами може виглядати так:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: test-cm
  namespace: default
  labels:
    test-label: test
  managedFields:
  - manager: kubectl
    operation: Apply
    time: '2019-03-30T15:00:00.000Z'
    apiVersion: v1
    fieldsType: FieldsV1
    fieldsV1:
      f:metadata:
        f:labels:
          f:test-label: {}
  - manager: kube-controller-manager
    operation: Update
    apiVersion: v1
    time: '2019-03-30T16:00:00.000Z'
    fieldsType: FieldsV1
    fieldsV1:
      f:data:
        f:key: {}
data:
  key: new value

У цьому прикладі друга операція була виконана як update менеджером з назвою kube-controller-manager. Запит на оновлення був успішним і змінив значення в полі даних, що призвело до зміни управління цим полем на kube-controller-manager.

Якби була спроба застосувати це оновлення за допомогою Server-Side Apply, запит зазнав би невдачі через конфлікт управління.

Стратегія злиття

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

Коли користувач надсилає обʼєкт із повністю специфікованим наміром на точку доступу Server-Side Apply, сервер зʼєднує його з поточним обʼєктом, надаючи перевагу значенню з тіла запиту, якщо воно вказане в обох місцях. Якщо набір елементів, присутніх у застосованій конфігурації, не є надмножиною елементів, застосованих тим самим користувачем минулого разу, кожен відсутній елемент, яким не керують інші аплікатори, видаляється. Для отримання додаткової інформації про те, як схема обʼєкта використовується для прийняття рішень під час злиття, дивіться sigs.k8s.io/structured-merge-diff.

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

Якщо listType відсутній, сервер API інтерпретує patchStrategy=merge як listType=map і відповідний маркер patchMergeKey як listMapKey.

Тип списку atomic є рекурсивним.

(У коді Go для Kubernetes, ці маркери вказуються як коментарі, і авторам коду не потрібно повторювати їх як теґи полів).

Власні ресурси та Серверне застосування

Стандартно, Server-Side Apply обробляє власні ресурси користувачів як неструктуровані дані. Усі ключі розглядаються як поля структури, а всі списки вважаються атомарними.

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

Сумісність при зміні топології

У рідкісних випадках автор CustomResourceDefinition (CRD) або вбудованого ресурсу може захотіти змінити специфічну топологію поля у своєму ресурсі, не збільшуючи його версію API. Зміна топології типів шляхом оновлення кластера або CRD має різні наслідки при оновленні наявних обʼєктів. Є дві категорії змін: коли поле переходить від map/set/granular до atomic і навпаки.

Коли listType, mapType або structType змінюються з map/set/granular на atomic, весь список, map або структура наявних обʼєктів будуть в підсумку належати акторам, які володіли елементом цих типів. Це означає, що будь-яка подальша зміна цих обʼєктів призведе до конфлікту.

Коли listType, mapType або structType змінюються з atomic на map/set/granular, сервер API не може визначити нову власність цих полів. Через це конфлікти не виникатимуть під час оновлення обʼєктів із цими полями. Тому не рекомендується змінювати тип із atomic на map/set/granular.

Візьмемо, наприклад, власний ресурс користувача ресурс:

---
apiVersion: example.com/v1
kind: Foo
metadata:
  name: foo-sample
  managedFields:
  - manager: "manager-one"
    operation: Apply
    apiVersion: example.com/v1
    fieldsType: FieldsV1
    fieldsV1:
      f:spec:
        f:data: {}
spec:
  data:
    key1: val1
    key2: val2

До того, як spec.data зміниться з atomic на granular, manager-one володіє полем spec.data і всіма полями в ньому (key1 та key2). Коли CRD змінюється, щоб зробити spec.data granular, manager-one продовжує володіти полем верхнього рівня spec.data (що означає, що жоден інший менеджер не може видалити map data без конфлікту), але він більше не володіє key1 та key2, тому інший менеджер може змінити або видалити ці поля без конфлікту.

Використання Server-Side Apply в контролер

Як розробник контролера, ви можете використовувати Server-Side Apply як спосіб спростити логіку оновлення вашого контролера. Основні відмінності від кead-modify-write та/або patch наступні:

• застосований обʼєкт повинен містити всі поля, які цікавлять контролер.
• немає способу видалити поля, які не були застосовані контролером раніше (контролер все ще може надіслати patch або update для цих випадків використання).
• обʼєкт не обовʼязково має бути прочитаним перед тим; resourceVersion не потрібно вказувати.

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

Передача власності

Окрім контролю конкурентності, забезпеченого вирішенням конфліктів, Server-Side Apply надає можливості для виконання координованих переходів власності полів від користувачів до контролерів.

Це найкраще пояснюється на прикладі. Розглянемо, як безпечно перевести власність поля replicas від користувача до контролера, дозволяючи автоматичне горизонтальне масштабування для Deployment, використовуючи ресурс HorizontalPodAutoscaler та його супровідний контролер.

Скажімо, користувач визначив Deployment з replicas, встановленим на бажане значення:

application/ssa/nginx-deployment.yaml

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, наступним чином:

kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment.yaml --server-side

Пізніше автоматичне масштабування увімкнено для Deployment; наприклад:

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:

# Збережіть цей файл як 'nginx-deployment-replicas-only.yaml'.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3

Користувач застосовує цей маніфест, використовуючи приватне імʼя менеджера полів. У цьому прикладі користувач вибрав handover-to-hpa:

kubectl apply -f nginx-deployment-replicas-only.yaml \
  --server-side --field-manager=handover-to-hpa \
  --validate=false

Якщо застосування призводить до конфлікту з контролером HPA, тоді нічого не робіть. Конфлікт вказує на те, що контролер вже вимагає поле на цьому етапі.

На цьому етапі користувач може видалити поле replicas з маніфесту:

application/ssa/nginx-deployment-no-replicas.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:1.14.2

Зауважте, що кожного разу, коли контролер HPA встановлює значення поля replicas на нове значення, тимчасовий менеджер полів більше не володіє жодними полями й буде автоматично видалений. Додаткового прибирання не потрібно.

Передача власності між менеджерами

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

Порівняння з 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

Перехід з client-side apply на server-side apply

Користувачі client-side apply, які керують ресурсом за допомогою kubectl apply, можуть почати використовувати server-side apply з наступним прапорцем.

kubectl apply --server-side [--dry-run=server]

Стандартно, управління полями обʼєкта переходить з client-side apply на kubectl server-side apply без виникнення конфліктів.

Ця поведінка стосується server-side apply з менеджером полів kubectl. Як виняток, ви можете відмовитися від цієї поведінки, вказавши іншого, не стандартного менеджера полів, як показано в наступному прикладі. Стандартним менеджером полів для kubectl server-side apply є kubectl.

kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

Повернення з server-side apply на client-side apply

Якщо ви керуєте ресурсом за допомогою kubectl apply --server-side, ви можете перейти на client-side apply безпосередньо за допомогою kubectl apply.

Повернення працює тому, що kubectl Server-Side Apply тримає анотацію last-applied-configuration в актуальному стані, якщо ви використовуєте kubectl apply.

Ця поведінка стосується Server-Side Apply з менеджером полів kubectl. Як виняток, ви можете відмовитися від цієї поведінки, вказавши іншого, не стандартного менеджера полів, як показано в наступному прикладі. Стандартним менеджером полів для kubectl server-side apply є kubectl.

kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

Реалізація API

Дієслово PATCH (для обʼєкту, який підтримує Server-Side Apply) може приймати неофіційний тип контенту application/apply-patch+yaml. Користувачі Server-Side Apply можуть надіслати частково специфіковані обʼєкти у вигляді YAML як тіло запиту PATCH до URI ресурсу. При застосуванні конфігурації слід завжди включати всі поля, які є важливими для результату (наприклад, бажаний стан), який ви хочете визначити.

Всі JSON-повідомлення є дійсними YAML-повідомленнями. Тому, на додачу до використання тіл запитів YAML для запитів Server-Side Apply, ви також можете використовувати тіла запитів JSON, оскільки вони також є дійсними YAML. У будь-якому випадку, використовуйте тип медіа application/apply-patch+yaml для HTTP-запиту.

Контроль доступу і дозволи

Оскільки Server-Side Apply є типом PATCH, субʼєкт (такий як Роль для Kubernetes RBAC) потребує дозволу patch для редагування наявних ресурсів, а також дозволу на дієслово create для створення нових ресурсів за допомогою Server-Side Apply.

Очищення managedFields

Можливо видалити всі managedFields з обʼєкта, переписавши їх за допомогою patch (JSON Merge Patch, Strategic Merge Patch, JSON Patch) або через update (HTTP PUT); іншими словами, через будь-яку операцію запису, окрім apply. Це можна зробити, переписавши поле managedFields порожнім записом. Два приклади:

PATCH /api/v1/namespaces/default/configmaps/example-cm
Accept: application/json
Content-Type: application/merge-patch+json

{
  "metadata": {
    "managedFields": [
      {}
    ]
  }
}

PATCH /api/v1/namespaces/default/configmaps/example-cm
Accept: application/json
Content-Type: application/json-patch+json
If-Match: 1234567890123456789

[{"op": "replace", "path": "/metadata/managedFields", "value": [{}]}]

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

У випадках, коли операція скидання комбінується зі змінами інших полів, крім managedFields, це призведе до того, що спочатку managedFields буде скинуто, а інші зміни будуть оброблені пізніше. У результаті аплікатор бере на себе відповідальність за будь-які поля, оновлені в тому ж запиті.

Що далі

Ви можете прочитати про managedFields у довіднику API Kubernetes для верхнього рівня поля metadata.

2.4 - Бібліотеки клієнтів

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

Для написання застосунків, що використовують Kubernetes REST API, вам не потрібно самостійно реалізовувати виклики API та типи запитів/відповідей. Ви можете використовувати бібліотеку клієнтів для мови програмування, яку ви використовуєте.

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

Офіційно підтримувані бібліотеки клієнтів Kubernetes

Наступні бібліотеки клієнтів офіційно підтримуються Kubernetes SIG API Machinery.

Бібліотеки клієнтів, що підтримуються спільнотою

Наступні бібліотеки клієнтів Kubernetes надаються і підтримуються їх авторами, а не командою Kubernetes.

2.5 - Загальна мова виразів у Kubernetes

Загальна мова виразів (Common Expression Language, CEL) використовується в API Kubernetes для оголошення правил валідації, політик та інших обмежень чи умов.

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

Огляд мови

Мова CEL має простий синтаксис, який схожий на вирази в C, C++, Java, JavaScript і Go.

CEL була розроблена для вбудовування в застосунки. Кожна "програма" CEL — це один вираз, який обраховується до одного значення. Вирази CEL зазвичай короткі "одноразові", що добре вбудовуються в строкові поля ресурсів API Kubernetes.

Вхідні дані для програми CEL — це "змінні". Кожне поле API Kubernetes, яке містить CEL, декларує в документації API, які змінні доступні для використання для цього поля. Наприклад, у полі x-kubernetes-validations[i].rules у CustomResourceDefinitions доступні змінні self і oldSelf, що відносяться до попереднього та поточного стану даних власного ресурсу користувача, які потрібно перевірити за допомогою виразу CEL. Інші поля API Kubernetes можуть оголошувати різні змінні. Дивіться документацію API для полів API, щоб дізнатися, які змінні доступні для цього поля.

Приклади виразів CEL:

Опції CEL, особливості мови та бібліотеки

CEL налаштовується з наступними опціями, бібліотеками та особливостями мови, введеними у зазначених версіях Kubernetes:

Функції CEL, особливості та налаштування мови підтримують відкат панелі управління Kubernetes. Наприклад, опційні значення CEL були введені у Kubernetes 1.29, і лише сервери API цієї версії або новіші прийматимуть запити на запис виразів CEL, які використовують опційні значення CEL. Однак, коли кластер відкочується до версії Kubernetes 1.28, вирази CEL, що використовують "опційні значення CEL", які вже збережені в ресурсах API, продовжуватимуть правильно оцінюватись.

Бібліотеки CEL Kubernetes

Крім спільнотних бібліотек CEL, Kubernetes включає бібліотеки CEL, які доступні у всіх місцях використання CEL в Kubernetes.

Бібліотека списків Kubernetes

Бібліотека списків включає indexOf та lastIndexOf, які працюють аналогічно функціям рядків з такими самими назвами. Ці функції повертають перший або останній індекс елемента у списку.

Бібліотека списків також включає min, max та sum. Сума підтримується для всіх типів чисел, а також для типу тривалості. Мінімум та максимум підтримуються для всіх типів, що можна порівняти.

Також надається функція isSorted для зручності та підтримується для всіх типів, які можна порівняти.

Приклади:

Для отримання додаткової інформації дивіться бібліотеку списків Kubernetes godoc.

Бібліотека регулярних виразів Kubernetes

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

Приклади:

Для отримання додаткової інформації дивіться бібліотеку регулярних виразів Kubernetes godoc.

Бібліотека URL Kubernetes

Для спрощення та безпечної обробки URL надані наступні функції:

• isURL(string) перевіряє, чи є рядок рядком дійсним URL з пакетом Go net/url. Рядок повинен бути абсолютним URL.
• url(string) URL конвертує рядок в URL або викликає помилку, якщо рядок не є дійсним URL.

Після розбору за допомогою функції url, отриманий обʼєкт URL має наступні методи доступу: getScheme, getHost, getHostname, getPort, getEscapedPath та getQuery.

Приклади:

Для отримання додаткової інформації дивіться бібліотеку URL Kubernetes godoc.

Бібліотека IP адрес Kubernetes

Щоб зробити обробку IP-адрес простішою і безпечнішою, були додані наступні функції:

• isIP(string) перевіряє, чи є рядок дійсною IP-адресою.
• ip(string) IP конвертує рядок в обʼєкт IP-адреси або викликає помилку, якщо рядок не є дійсною IP-адресою.

Для обох функцій IP-адреса повинна бути адресою IPv4 або IPv6. Зіставлені з IPv4 IPv6-адреси (наприклад, ::ffff:1.2.3.4) не допускаються. IP-адреси з зонами (наприклад, fe80::1%eth0) не допускаються. Початкові нулі в октетах IPv4-адрес не допускаються.

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

Доступні функції-члени обʼєкта IP-адреси

Приклади:

Приклади виразів CEL з використанням функцій бібліотеки IP-адрес

Докладнішу інформацію наведено у Бібліотеці IP-адрес Kubernetes godoc.

Бібліотека CIDR Kubernetes

CIDR надає розширення бібліотеки функцій CEL для розбору нотації CIDR.

cidr

Конвертує рядок у нотації CIDR в представлення мережевої адреси або викликає помилку, якщо рядок не є дійсною нотацією CIDR. CIDR повинен бути підмережею IPv4 або IPv6 з маскою. Ведучі нулі в октетах IPv4-адреси не дозволяються. IPv4-адреси, що відображаються в IPv6 (наприклад, ::ffff:1.2.3.4/24), не дозволяються.

cidr(<рядок>) <CIDR>

Приклади:

cidr('192.168.0.0/16') // повертає IPv4-адресу з маскою CIDR
cidr('::1/128')        // повертає IPv6-адресу з маскою CIDR
cidr('192.168.0.0/33') // помилка
cidr('::1/129')        // помилка
cidr('192.168.0.1/16') // помилка, тому що є ненульові біти після префікса

isCIDR

Повертає true, якщо рядок є дійсним представленням підмережі з маскою в нотації CIDR. CIDR повинен бути підмережею IPv4 або IPv6 з маскою. Ведучі нулі в октетах IPv4-адреси не дозволяються. IPv4-адреси, що відображаються в IPv6 (наприклад, ::ffff:1.2.3.4/24), не дозволяються.

isCIDR(<string>) <bool>

Приклади:

isCIDR('192.168.0.0/16')    // повертає true
isCIDR('::1/128')           // повертає true
isCIDR('192.168.0.0/33')    // повертає false
isCIDR('::1/129')           // повертає false

containsIP / containsCIDR / ip / masked / prefixLength

• containsIP: Повертає true, якщо CIDR містить задану IP-адресу. IP-адреса має бути IPv4 або IPv6. Може приймати як аргумент рядок або IP-адресу.

• containsCIDR: Повертає true, якщо CIDR містить заданий CIDR. CIDR повинен бути підмережею IPv4 або IPv6 з маскою. Може приймати як аргумент рядок або CIDR.

• ip: Повертає представлення IP-адреси CIDR.

• masked: Повертає представлення CIDR мережевої адреси з маскованим префіксом. Це можна використовувати для повернення канонічної форми мережі CIDR.

• prefixLength: Повертає довжину префікса CIDR в бітах. Це кількість бітів у масці.

Приклади:

Приклади виразів CEL з використанням функцій бібліотеки CIDR

Докладнішу інформацію можна знайти у Бібліотеці Kubernetes CIDR godoc.

Бібліотека авторизатора Kubernetes

Для виразів CEL в API, де доступна змінна типу Authorizer, авторизатор може використовуватися для виконання перевірок авторизації для принципала (автентифікованого користувача) запиту.

Перевірки ресурсів API виконуються наступним чином:

1. Вкажіть групу та ресурс для перевірки: Authorizer.group(string).resource(string) ResourceCheck.

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

   • ResourceCheck.subresource(string) ResourceCheck
   • ResourceCheck.namespace(string) ResourceCheck
   • ResourceCheck.name(string) ResourceCheck

3. Викличте ResourceCheck.check(verb string) Decision, щоб виконати перевірку авторизації.

4. Викличте allowed() bool або reason() string, щоб переглянути результат перевірки авторизації.

Не-ресурсна авторизація виконується так:

1. Вкажіть лише шлях: Authorizer.path(string) PathCheck.
2. Викличте PathCheck.check(httpVerb string) Decision, щоб виконати перевірку авторизації.
3. Викличте allowed() bool або reason() string, щоб переглянути результат перевірки авторизації.

Для виконання перевірки авторизації для службового облікового запису:

• Authorizer.serviceAccount(namespace string, name string) Authorizer

Для виразів CEL в API, де доступна змінна типу Authorizer, селектори полів і міток можуть бути включені в перевірки авторизації.

Для отримання додаткової інформації дивіться бібліотеку Kubernetes Authz та бібліотеку Kubernetes AuthzSelectors godoc.

Бібліотека форматів Kubernetes

Бібліотека format надає функції для перевірки поширених форматів рядків у Kubernetes. Це корисно у messageExpression правил валідації для надання більш конкретних повідомлень про помилки.

Бібліотека надає функції format() для кожного іменованого формату, а також загальну функцію format.named().

• format.named(string) → ?Format: Повертає обʼєкт Format для заданого імені формату, якщо він існує. Інакше повертає optional.none.
• format.<formatName>() -> Format: Доступні зручні функції для всіх іменованих форматів. Наприклад, format.dns1123Label() повертає обʼєкт Format для DNS-1123 label.
• <Format>.validate(string) -> list<string>?: Перевіряє рядок на відповідність формату. Повертає optional.none, якщо рядок валідний, інакше — список рядків з помилками.

Доступні формати:

Підтримуються наступні назви форматів:

Доступні формати для бібліотеки форматів

Приклади:

Приклади CEL-виразів з використанням функцій бібліотеки форматів

Докладніше: Бібліотека форматів Kubernetes godoc.

Бібліотека кількості Kubernetes

У Kubernetes 1.28 додана підтримка обробки рядків кількості (наприклад, 1,5G, 512k, 20Mi).

• isQuantity(string) перевіряє, чи є рядок дійсною кількістю відповідно до Кількості ресурсів Kubernetes.
• quantity(string) Quantity конвертує рядок у кількість або викликає помилку, якщо рядок не є дійсною кількістю.

Після розбору за допомогою функції quantity, отриманий обʼєкт кількості має наступний набір методів:

Приклади:

Бібліотека semver Kubernetes

У Kubernetes v1.34 додано підтримку розбору та порівняння рядків, що відповідають специфікації Semantic Versioning 2.0.0. Докладніше про прийняті патерни дивіться semver.org.

• isSemver(string) перевіряє, чи є рядок валідною семантичною версією.
• semver(string) конвертує рядок у обʼєкт Semver або повертає помилку.

Додатковий булевий аргумент normalize можна передати у isSemver та semver. Якщо true, нормалізація прибирає префікс "v", додає 0 для minor та patch, якщо вказано лише major або major.minor, і прибирає ведучі нулі.

Після розбору через функцію semver отриманий обʼєкт Semver має такі функції-члени:

Доступні функції-члени обʼєкту Semver

Приклади:

Приклади CEL-виразів з використанням функцій бібліотеки semver

Докладніше: Бібліотека semver Kubernetes godoc.

Перевірка типів

CEL — це поступово типізована мова.

Деякі поля API Kubernetes містять повністю перевірені типи CEL-виразів. Наприклад, Правила валідації власних ресурсів повністю перевірені за типом.

Деякі поля API Kubernetes містять частково перевірені типи CEL-виразів. Частково перевірений вираз — це вираз, в якому деякі змінні статично типізовані, а інші — динамічно типізовані. Наприклад, в CEL-виразах ValidatingAdmissionPolicies, змінна request має тип, але змінна object динамічно типізована. У звʼязку з цим вираз, що містить request.namex, не пройде перевірку типів, оскільки поле namex не визначене. Однак object.namex пройде перевірку типів навіть тоді, коли поле namex не визначене для типів ресурсів, на які посилається object, оскільки object динамічно типізований.

Макрос has() в CEL можна використовувати у виразах CEL для перевірки доступності поля динамічно типізованої змінної перед спробою доступу до значення поля. Наприклад:

has(object.namex) ? object.namex == 'special' : request.name == 'special'

Інтеграція системи типів

Також дивіться: Типи CEL, Типи OpenAPI, Структурні схеми Kubernetes.

Порівняння рівності для масивів з x-kubernetes-list-type типу set або map ігнорує порядок елементів. Наприклад, [1, 2] == [2, 1] якщо масиви представляють значення Kubernetes set.

Конкатенація для масивів з x-kubernetes-list-type використовує семантику типу списку:

set

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

map

X + Y виконує обʼєднання, де позиції ключів у X зберігаються, але значення перезаписуються значеннями у Y, коли ключові множини X і Y перетинаються. Елементи у Y з неперетинаючими ключами додаються, зберігаючи їх частковий порядок.

Екранування

Тільки імена властивостей ресурсів Kubernetes форми [a-zA-Z_.-/][a-zA-Z0-9_.-/]* доступні з CEL. Доступні імена властивостей екрануються згідно з наступними правилами при доступі у виразі:

Коли ви екрануєте будь-яке з ЗАРЕЗЕРВОВАНИХ ключових слів CEL, збіг повинен точно відповідати імені властивості та використовувати екранування з підкресленням (наприклад, int у слові sprint не буде екрановано, і це не буде необхідно).

Приклади екранування:

Обмеження ресурсів

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

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

Багато з основних операцій CEL мають фіксовані витрати. Найпростіші операції, такі як порівняння (наприклад, <), мають вартість 1. Деякі мають вищу фіксовану вартість, наприклад, оголошення літералів списку мають фіксовану базову вартість 40 одиниць вартості.

Виклики функцій, реалізованих у рідному коді, оцінюються на основі часової складності операції. Наприклад, операції, що використовують регулярні вирази, такі як match та find, оцінюються з використанням приблизної вартості length(regexString)*length(inputString). Приблизна вартість відображає найгірший випадок часової складності реалізації RE2 в Go.

Бюджет вартості під час виконання

Усі вирази CEL, які оцінюються Kubernetes, обмежені бюджетом вартості під час виконання. Бюджет вартості під час виконання — це оцінка фактичного використання ЦП, що обчислюється шляхом інкрементування лічильника одиниць вартості під час інтерпретації виразу CEL. Якщо інтерпретатор CEL виконає занадто багато інструкцій, бюджет вартості під час виконання буде перевищено, виконання виразу буде зупинено і результатом стане помилка.

Деякі ресурси Kubernetes визначають додатковий бюджет вартості під час виконання, який обмежує виконання декількох виразів. Якщо загальна вартість виразів перевищує бюджет, виконання виразів буде зупинено і результатом стане помилка. Наприклад, валідація власного ресурсу користувача має бюджет вартості під час виконання за одну валідацію для всіх Правил Валідації, які оцінюються для валідації власного ресурсу.

Оцінювані обмеження вартості

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

2.6 - Політика застарівання Kubernetes

Цей документ описує політику застарівання для різних аспектів системи.

Kubernetes — це велика система з багатьма компонентами та багатьма учасниками. Як і в будь-якому такому програмному забезпеченні, набір функцій природно розвивається з часом, і іноді функцію може знадобитися видалити. Це може включати API, прапорець або навіть всю функцію. Щоб уникнути порушення роботи наявних користувачів, Kubernetes дотримується політики застарівання для аспектів системи, які підлягають видаленню.

Застарівання частин API

Оскільки Kubernetes є системою, що керується API, API еволюціонував з часом, віддзеркалюючи постійно змінюване розуміння проблемної області. API Kubernetes фактично є набором API, які називаються "групами API", і кожна група API має свою незалежну версію. Версії API поділяються на 3 основні треки, кожен з яких має різні політики застарівання:

Конкретний випуск Kubernetes може підтримувати будь-яку кількість груп API та будь-яку кількість версій кожного з них.

Наступні правила регулюють застарівання елементів API. Це включає:

• Ресурси REST (також відомі як обʼєкти API)
• Поля ресурсів REST
• Анотації на ресурсах REST, включаючи "бета" анотації, але не включаючи "альфа" анотації
• Перелічувані або постійні значення
• Структури конфігурації компонентів

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

Правило №1: Елементи API можуть бути видалені лише шляхом інкрементування версії групи API.

Після того, як елемент API був доданий до групи API у певній версії, він не може бути видалений з цієї версії або суттєво змінений, незалежно від треку.

Правило №2: Обʼєкти API повинні мати можливість переходу між версіями API в даному випуску без втрати інформації, за винятком випадків, коли цілі ресурси REST не існують у деяких версіях.

Наприклад, обʼєкт може бути записаний як v1, потім прочитаний як v2 і перетворений на v1, і отриманий ресурс v1 буде ідентичний оригіналу. Представлення у v2 може відрізнятися від v1, але система повинна вміти конвертувати між ними в обидва боки. Крім того, будь-яке нове поле, додане у v2, повинно мати можливість обміну на v1 і назад, що означає, що v1 можливо доведеться додати еквівалентне поле або представити його як анотацію.

Правило №3: Версія API в даному треку не може бути застарілою на користь менш стабільної версії API.

• GA версії API можуть замінювати бета та альфа версії API.
• Бета версії API можуть замінювати попередні бета та альфа версії API, але не можуть замінювати GA версії API.
• Альфа версії API можуть замінювати попередні альфа версії API, але не можуть замінювати GA або бета версії API.

Правило №4а: Тривалість життя API визначається рівнем стабільності API

• GA версії API можуть бути позначені як застарілі, але не можуть бути видалені в межах основної версії Kubernetes
• Бета версії API застарівають не раніше ніж через 9 місяців або 3 мінорних випуски після впровадження (що довше), і більше не обслуговуються через 9 місяців або 3 мінорних випуски після застарівання (що довше)
• Альфа версії API можуть бути видалені в будь-якому випуску без попереднього повідомлення про застарівання

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

Правило №4б: "Бажана" версія API та "версія зберігання" для даної групи можуть не просуватися до того, як буде зроблено випуск, що підтримує як нову версію, так і попередню версію.

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

Все це найкраще ілюструється прикладами. Уявіть собі випуск Kubernetes, версія X, який вводить нову групу API. Новий випуск Kubernetes виходить приблизно кожні 4 місяці (3 на рік). Наступна таблиця описує, які версії API підтримуються в ряді наступних випусків.

REST ресурси (або обʼєкти API)

Розглянемо гіпотетичний REST ресурс з назвою Widget, який був присутній у версії API v1 у наведеній вище хронології і який потрібно визнати застарілим. Ми документуємо та оголошуємо про його застарівання синхронно з випуском X+1. Ресурс Widget все ще існує у версії API v1 (застарілий), але не у v2alpha1. Ресурс Widget продовжує існувати та функціонувати у випусках до, та включно з, X+8. Лише у випуску X+9, коли API v1 виходить з використання, ресурс Widget перестає існувати та його віповідна поведінка видаляється.

Починаючи з Kubernetes v1.19, виконання запиту до застарілої точки доступу REST API:

1. Повертає заголовок Warning (як визначено у RFC7234, Розділ 5.5) у відповіді API.

2. Додає "k8s.io/deprecated":"true" анотацію до події аудиту, зареєстрованої для запиту.

3. Встановлює метрику apiserver_requested_deprecated_apis gauge у значення 1 у процесі kube-apiserver. Метрика має мітки group, version, resource, subresource, які можна поєднати з метрикою apiserver_request_total, і мітку removed_release, яка вказує випуск Kubernetes, в якому API більше не буде обслуговуватися. Наступний запит Prometheus повертає інформацію про запити, зроблені до застарілих API, які будуть видалені у версії v1.22:

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

Поля REST ресурсів

Як і REST ресурси в цілому, так і окреме поле, яке було присутнє у версії API v1, має існувати та функціонувати до видалення API v1. На відміну від ресурсів в цілому, API v2 можуть вибрати інше представлення для поля, допоки є можливість виконувати перехід між версіями в обидва боки. Наприклад, поле v1 з назвою "magnitude", яке було застарілим, може називатися "deprecatedMagnitude" в API v2. Коли v1 врешті буде видалено, застаріле поле може бути видалене з v2.

Перераховані або константні значення

Як і для REST ресурсу в цілому, так і його полів, константне значення, яке підтримувалося в API v1, має існувати та функціонувати до видалення API v1.

Структури конфігурацій компонентів

Конфігурації компонентів версіонуються та керуються аналогічно до REST ресурсів.

Майбутні роботи

З часом Kubernetes запровадить більш детальні версії API, і тоді ці правила будуть скориговані за потреби.

Застарівання прапорця або CLI

Система Kubernetes складається з кількох різних програм, які співпрацюють між собою. Іноді випуск Kubernetes може видаляти прапорці або команди CLI (загалом "елементи CLI") у цих програмах. Програми природно діляться на дві основні групи — програми для користувачів і програми для адміністраторів, які трохи відрізняються своїми політиками застарівання. Якщо прапорець явно не позначено або задокументовано як "alpha" або "beta", він вважається стабільним (GA).

Елементи CLI фактично є частиною API до системи, але оскільки вони не версіонуються так само, як REST API, правила застарівання наступні:

Правило №5а: Елементи CLI компонентів для користувачів (наприклад, kubectl) повинні функціонувати після оголошення їх застарівання не менше ніж:

• GA: 12 місяців або 2 випуски (залежно від того, що довше)
• Beta: 3 місяці або 1 випуск (залежно від того, що довше)
• Alpha: 0 випусків

Правило №5б: Елементи CLI компонентів для адміністраторів (наприклад, kubelet) повинні функціонувати після оголошення їх застарівання не менше ніж:

• GA: 6 місяців або 1 випуск (залежно від того, що довше)
• Beta: 3 місяці або 1 випуск (залежно від того, що довше)
• Alpha: 0 випусків

Правило №5в: Елементи командного інтерфейсу (CLI) не можуть бути застарілими на користь менш стабільних елементів CLI.

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

Правило №6: Застарілі елементи CLI повинні видавати попередження (можливо, такі, що відключаються) при використанні.

Застарівання функціонала або поведінки

Час від часу випуск Kubernetes потребує визнання застарілим певного функціонала або поведінки системи, яка не контролюється API або CLI. У цьому випадку правила застарівання такі:

Правило №7: Застарілі функції повинні функціонувати не менше 1 року після оголошеного застарівання.

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

Правило №8: Функцію або поведінку не можна визнати застарілою на користь альтернативної реалізації, яка менш стабільна.

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

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

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

Виняток з вищезазначеного правила  — це функціональні можливості. Функціональні можливості — це пари ключ=значення, які дозволяють користувачам увімкнути/вимкнути експериментальні функції.

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

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

• Alpha: функціональні можливості стандартно вимкнені та можуть бути увімкнені користувачем.
• Beta: функціональні можливості стандартно увімкнені та можуть бути вимкнені користувачем.
• GA: функціональні можливості застарілі (див. "Застарівання") і стають нечинними.
• GA, вікно застарівання завершено: функціональні можливості видаляються, і виклики до них більше не приймаються.

Застарівання

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

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

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

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

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

Версіонування для функціональних можливостей відрізняється від раніше обговорених компонентів, тому правила застарівання такі:

Правило №9: Функціональні можливості повинні бути визнані застарілими, коли відповідна функція, якою вони керують, переходить на етап життєвого циклу наступним чином. Функціональні можливості повинні функціонувати не менше ніж:

• Від бета-функції до GA: 6 місяців або 2 випуски (залежно від того, що довше)
• Від бета-функції до EOL: 3 місяці або 1 випуск (залежно від того, що довше)
• Від альфа-функції до EOL: 0 випусків

Правило №10: Застарілі функціональні можливості повинні відповідати попередженням при використанні. Коли функціональні можливості застарівають, вони повинні бути задокументовані як в примітках про випуски, так і в відповідній довідці CLI. Як попередження, так і документація повинні вказувати, чи є функціональні можливості нечинними.

Застарівання метрики

Кожен компонент панелі управління Kubernetes використовує метрики (зазвичай за допомогою точки доступу /metrics), які зазвичай обробляються адміністраторами кластера. Не всі метрики однакові: деякі метрики широко використовуються як показники рівня сервісу (SLI) або для визначення SLO, тому вони мають більшу важливість. Інші метрики мають більш експериментальний характер або використовуються переважно у процесі розробки Kubernetes.

Відповідно, метрики поділяються на три класи стабільності (ALPHA, BETA, STABLE); це впливає на видалення метрики під час випуску Kubernetes. Ці класи визначаються важливістю метрики. Правила для застарівання та видалення метрики такі:

Правило №11а: Метрики для відповідного класу стабільності повинні функціонувати не менше ніж:

• STABLE: 4 випуски або 12 місяців (що довше)
• BETA: 2 випуски або 8 місяців (що довше)
• ALPHA: 0 випусків

Правило №11б: Метрики, після їх оголошеного застарівання, повинні функціонувати не менше ніж:

• STABLE: 3 випуски або 9 місяців (що довше)
• BETA: 1 випуск або 4 місяці (що довше)
• ALPHA: 0 випусків

Застарілі метрики будуть мати текст опису, у якому буде префікс з повідомленням про застарівання '(Застаріло з x.y)', і під час реєстрації метрики буде запис в лог з попередженням. Подібно до їх стабільних незастарілих аналогів, застарілі метрики будуть автоматично зареєстровані в точці доступу метрик і, отже, будуть видимими.

У наступному випуску (коли deprecatedVersion метрики дорівнює current_kubernetes_version - 3), застаріла метрика стане прихованою метрикою. На відміну від їх застарілих аналогів, приховані метрики більше не будуть автоматично реєструватися в точці доступу метрик (таким чином, вони будуть приховані). Однак їх можна буде явно увімкнути через прапорець командного рядка (--show-hidden-metrics-for-version=). Це надає адміністраторам кластера можливість виходу зі складностей з міграцією від застарілої метрики, якщо вони не змогли відреагувати на раніше надані попередження щодо застарівання. Приховані метрики повинні бути видалені після одного випуску.

Винятки

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

2.7 - Посібник з міграції від застарілих API

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

Вилучені API в розрізі версій

v1.32

У випуску v1.32 перестали обслуговуватися наступні застарілі версії API:

Ресурси контролю потоку

Версія API flowcontrol.apiserver.k8s.io/v1beta3 FlowSchema та PriorityLevelConfiguration більше не обслуговуються починаючи з v1.32.

• Перенесіть маніфести та клієнти API на використання версії API flowcontrol.apiserver.k8s.io/v1, доступної з версії v1.29.
• Усі наявні збережені обʼєкти доступні через новий API
• Значні зміни у flowcontrol.apiserver.k8s.io/v1:
  • Поле spec.limited.nominalConcurrencyShares PriorityLevelConfiguration має стандартне значення 30, коли не вказане, і явне значення 0 не змінюється на 30.

v1.29

У випуску v1.29 перестали обслуговуватися наступні застарілі версії API:

Ресурси контролю потоку

Версія API flowcontrol.apiserver.k8s.io/v1beta2 FlowSchema та PriorityLevelConfiguration більше не обслуговується з версії v1.29.

• Перенесіть маніфести та клієнти API на використання версії API flowcontrol.apiserver.k8s.io/v1, доступної з версії v1.29, або версії API flowcontrol.apiserver.k8s.io/v1beta3, доступної з версії v1.26.
• Усі наявні збережені обʼєкти доступні через новий API
• Значні зміни в flowcontrol.apiserver.k8s.io/v1:
  • Поле spec.limited.assuredConcurrencyShares PriorityLevelConfiguration перейменоване на spec.limited.nominalConcurrencyShares і має стандартне значення 30, коли не вказане, і явне значення 0 не змінюється на 30.
• Значні зміни в flowcontrol.apiserver.k8s.io/v1beta3:
  • Поле spec.limited.assuredConcurrencyShares PriorityLevelConfiguration перейменоване на spec.limited.nominalConcurrencyShares

v1.27

Випуск v1.27 припинив обслуговування наступних застарілих версій API:

CSIStorageCapacity

Версія API CSIStorageCapacity storage.k8s.io/v1beta1 більше не обслуговується з версії v1.27.

• Перенесіть маніфести та клієнти API на версію API storage.k8s.io/v1, доступну з версії v1.24.
• Усі наявні обʼєкти, які зберігаються, доступні через новий API
• Немає помітних змін

v1.26

Випуск v1.26 припинив обслуговування наступних застарілих версій API:

Ресурси керування потоком

Версія API FlowSchema та PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1beta1 більше не обслуговується з версії v1.26.

• Перенесіть маніфести та клієнти API на версію API flowcontrol.apiserver.k8s.io/v1beta2.
• Усі наявні обʼєкти, які зберігаються, доступні через новий API
• Немає помітних змін

HorizontalPodAutoscaler

Версія API HorizontalPodAutoscaler autoscaling/v2beta2 більше не обслуговується з версії v1.26.

• Перенесіть маніфести та клієнти API на версію API autoscaling/v2, доступну з версії v1.23.
• Усі наявні обʼєкти, які зберігаються, доступні через новий API
• Помітні зміни:
  • targetAverageUtilization замінено на target.averageUtilization та target.type: Utilization. Див. Автомасштабування за декількома метриками та власними метриками.