Довідник

• 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: Контроль допуску на основі маніфестів
• 3.18: Правила перевірки допуску
• 4: Відомі мітки, анотації та позначення
• 4.1: Анотації аудиту
• 5: API Kubernetes
• 5.1: Групи API
• 5.2: Admissionregistration
• 5.2.1: MutatingAdmissionPolicy
• 5.2.2: MutatingAdmissionPolicyBinding
• 5.2.3: MutatingWebhookConfiguration
• 5.2.4: ValidatingAdmissionPolicy
• 5.2.5: ValidatingAdmissionPolicyBinding
• 5.2.6: ValidatingWebhookConfiguration
• 5.3: Apiextensions
• 5.3.1: CustomResourceDefinition
• 5.4: Apiregistration
• 5.4.1: APIService
• 5.5: Apiserverinternal
• 5.5.1: StorageVersion
• 5.6: Apps
• 5.6.1: ControllerRevision
• 5.6.2: DaemonSet
• 5.6.3: Deployment
• 5.6.4: ReplicaSet
• 5.6.5: StatefulSet
• 5.7: Autoscaling
• 5.7.1: HorizontalPodAutoscaler
• 5.8: Batch
• 5.8.1: CronJob
• 5.8.2: Job
• 5.9: Certificates
• 5.9.1: CertificateSigningRequest
• 5.9.2: ClusterTrustBundle
• 5.9.3: PodCertificateRequest
• 5.10: Coordination
• 5.10.1: Lease
• 5.10.2: LeaseCandidate
• 5.11: Events
• 5.11.1: Event
• 5.12: Core
• 5.12.1: ComponentStatus
• 5.12.2: ConfigMap
• 5.12.3: Endpoints
• 5.12.4: Event
• 5.12.5: LimitRange
• 5.12.6: Namespace
• 5.12.7: Node
• 5.12.8: PersistentVolume
• 5.12.9: PersistentVolumeClaim
• 5.12.10: Pod
• 5.12.11: PodTemplate
• 5.12.12: ReplicationController
• 5.12.13: ResourceQuota
• 5.12.14: Secret
• 5.12.15: Service
• 5.12.16: ServiceAccount
• 5.13: Discovery
• 5.13.1: EndpointSlice
• 5.14: Flowcontrol
• 5.14.1: FlowSchema
• 5.14.2: PriorityLevelConfiguration
• 5.15: Networking
• 5.15.1: IPAddress
• 5.15.2: Ingress
• 5.15.3: IngressClass
• 5.15.4: NetworkPolicy
• 5.15.5: ServiceCIDR
• 5.16: Node
• 5.16.1: RuntimeClass
• 5.17: Policy
• 5.17.1: PodDisruptionBudget
• 5.18: Rbac
• 5.18.1: ClusterRole
• 5.18.2: ClusterRoleBinding
• 5.18.3: Role
• 5.18.4: RoleBinding
• 5.19: Resource
• 5.19.1: DeviceClass
• 5.19.2: DeviceTaintRule
• 5.19.3: ResourceClaim
• 5.19.4: ResourceClaimTemplate
• 5.19.5: ResourcePoolStatusRequest
• 5.19.6: ResourceSlice
• 5.20: Scheduling
• 5.20.1: PodGroup
• 5.20.2: PriorityClass
• 5.20.3: Workload
• 5.21: Storage
• 5.21.1: CSIDriver
• 5.21.2: CSINode
• 5.21.3: CSIStorageCapacity
• 5.21.4: StorageClass
• 5.21.5: VolumeAttachment
• 5.21.6: VolumeAttributesClass
• 5.22: Storagemigration
• 5.22.1: StorageVersionMigration
• 6: Інструментування
• 6.1: Метрики SLI компонентів Kubernetes
• 6.2: Дані метрик вузла
• 6.3: Метрики Pod та Контейнерів CRI
• 6.4: Підтримка нативних гістограм для метрик Kubernetes
• 6.5: Розуміння метрик Pressure Stall Information (PSI)
• 6.6: Kubernetes z-pages
• 6.7: Довідник Метрик Kubernetes
• 7: Безпека та проблеми Kubernetes
• 7.1: Трекер проблем Kubernetes
• 7.2: Процес розкриття інформації про безпеку в Kubernetes
• 7.3: Офіційний список CVE
• 8: Довідкова інформація про вузли
• 8.1: Kubelet Checkpoint API
• 8.2: Вимоги до версії ядра Linux
• 8.3: Kubelet Pod Info gRPC API
• 8.4: Статті про видалення dockershim та використання сумісних з CRI середовищ виконання
• 8.5: Мітки вузлів, які заповнює kubelet
• 8.6: Локальні файли та шляхи, які використовує Kubelet
• 8.7: Цикл синхронізації Kubelet
• 8.8: Версії API Kubelet Device Manager
• 8.9: Обʼєднання конфігураційних тек Kubelet
• 8.10: Kubelet Systemd Watchdog
• 8.11: Seccomp та Kubernetes
• 8.12: Стан вузла
• 8.13: Поведінка свопу на вузлах 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.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 annotate
• 11.2.3: kubectl api-resources
• 11.2.4: kubectl api-versions
• 11.2.5: kubectl apply
• 11.2.5.1: kubectl apply edit-last-applied
• 11.2.5.2: kubectl apply set-last-applied
• 11.2.5.3: kubectl apply view-last-applied
• 11.2.6: kubectl attach
• 11.2.7: kubectl auth
• 11.2.7.1: kubectl auth can-i
• 11.2.7.2: kubectl auth reconcile
• 11.2.7.3: kubectl auth whoami
• 11.2.8: kubectl autoscale
• 11.2.9: kubectl certificate
• 11.2.9.1: kubectl certificate approve
• 11.2.9.2: kubectl certificate deny
• 11.2.10: kubectl cluster-info
• 11.2.10.1: kubectl cluster-info dump
• 11.2.11: kubectl completion
• 11.2.12: kubectl config
• 11.2.12.1: kubectl config current-context
• 11.2.12.2: kubectl config delete-cluster
• 11.2.12.3: kubectl config delete-context
• 11.2.12.4: kubectl config delete-user
• 11.2.12.5: kubectl config get-clusters
• 11.2.12.6: kubectl config get-contexts
• 11.2.12.7: kubectl config get-users
• 11.2.12.8: kubectl config rename-context
• 11.2.12.9: kubectl config set
• 11.2.12.10: kubectl config set-cluster
• 11.2.12.11: kubectl config set-context
• 11.2.12.12: kubectl config set-credentials
• 11.2.12.13: kubectl config unset
• 11.2.12.14: kubectl config use-context
• 11.2.12.15: kubectl config view
• 11.2.13: kubectl cordon
• 11.2.14: kubectl cp
• 11.2.15: kubectl create
• 11.2.15.1: kubectl create clusterrole
• 11.2.15.2: kubectl create clusterrolebinding
• 11.2.15.3: kubectl create configmap
• 11.2.15.4: kubectl create cronjob
• 11.2.15.5: kubectl create deployment
• 11.2.15.6: kubectl create ingress
• 11.2.15.7: kubectl create job
• 11.2.15.8: kubectl create namespace
• 11.2.15.9: kubectl create poddisruptionbudget
• 11.2.15.10: kubectl create priorityclass
• 11.2.15.11: kubectl create quota
• 11.2.15.12: kubectl create role
• 11.2.15.13: kubectl create rolebinding
• 11.2.15.14: kubectl create secret
• 11.2.15.15: kubectl create secret docker-registry
• 11.2.15.16: kubectl create secret generic
• 11.2.15.17: kubectl create secret tls
• 11.2.15.18: kubectl create service
• 11.2.15.19: kubectl create service clusterip
• 11.2.15.20: kubectl create service externalname
• 11.2.15.21: kubectl create service loadbalancer
• 11.2.15.22: kubectl create service nodeport
• 11.2.15.23: kubectl create serviceaccount
• 11.2.15.24: kubectl create token
• 11.2.16: kubectl debug
• 11.2.17: kubectl delete
• 11.2.18: kubectl describe
• 11.2.19: kubectl diff
• 11.2.20: kubectl drain
• 11.2.21: kubectl edit
• 11.2.22: kubectl events
• 11.2.23: kubectl exec
• 11.2.24: kubectl explain
• 11.2.25: kubectl expose
• 11.2.26: kubectl get
• 11.2.27: kubectl kuberc
• 11.2.27.1: kubectl kuberc set
• 11.2.27.2: kubectl kuberc view
• 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.36.

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

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

Теги декларативної перевірки можуть застосовуватися безпосередньо до нових полів API без необхідності будь-якого механізму життєвого циклу (наприклад, можливо використовувати +k8s:minimum=1). Для міграції наявних рукописних перевірок, де декларативна перевірка заміщає поточну логіку рукописної перевірки, впровадження контролюється тегами життєвого циклу перевірки (+k8s:alpha та +k8s:beta) разом із функціональним прапорцем DeclarativeValidationBeta:

• DeclarativeValidation: (GA у v1.36, Стандартно: true, LockToDefault: true) Сервер API виконує обидві системи перевірки — нову декларативну та стару рукописну для перенесених типів/полів у режимі "тіньової перевірки" (Alpha). Результати порівнюються внутрішньо.
• DeclarativeValidationBeta: (Beta, Стандартно: true) Введено у v1.36. Цей прапорець контролює застосування правил перевірки на етапі бета-версії. Якщо увімкнено, правила, позначені як +k8s:beta, є авторитетними; якщо вимкнено, вони повертаються до режиму тіньової перевірки.
• DeclarativeValidationTakeover: (Визнано застарілим у v1.36). Раніше використовувався для визначення, чи є результати декларативної перевірки авторитетними. Тепер не враховується, але його можна встановити, щоб уникнути помилок "gate not recognized".

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

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

Адміністратори можуть явно вимкнути функціональну можливість DeclarativeValidationBeta, щоб повернути правила перевірки +k8s:beta у режим тіньової перевірки, якщо спостерігається неочікувана поведінка перевірки або регресії.

Вимкнення DeclarativeValidationBeta

Як адміністратор кластера, ви можете розглянути можливість вимкнення DeclarativeValidationBeta=false за певних обставин:

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

Щоб повернути правила перевірки +k8s:beta у режим тіньової перевірки, вимкніть функціональну можливість DeclarativeValidationBeta, наприклад, за допомогою аргументів командного рядка: (--feature-gates=DeclarativeValidationBeta=false).

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

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

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

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

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

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

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

+k8s:alpha

Опис:

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

Коли валідація позначена як +k8s:alpha, виконувана логіка валідації включає оригінальну ручну логіку валідації, як зазвичай, але додатково запускає тіньову декларативну валідацію в неблокуючому режимі, а потім перевіряє, чи результати збігаються. Будь-які невідповідності або паніки записуються через метрики (наприклад: declarative_validation_mismatch_total та declarative_validation_panic_total). Цей тіньовий механізм дозволяє учасникам та адміністраторам оцінювати правила декларативної валідації в реальному середовищі без впливу на поведінку кластера. Моніторинг метрик невідповідностей дозволяє перевірити, що декларативні правила поводяться ідентично до наявної ручної логіки перед підвищенням валідації до бета-версії.

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

Аргументи:

• since (string, обов'язково): Версія Kubernetes, в якій валідація вперше була позначена як тіньова.

Payload:

• <validation-tag>: Стандартний декларативний теґ валідації, який буде позначений як тіньовий (наприклад, +k8s:minimum=1).

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

type MyStruct struct {
    // +k8s:alpha(since:"1.36")=+k8s:minimum=1
    MyField int `json:"myField"`
}

+k8s:beta

Опис:

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

Після того, як правило валідації було оцінене в тіньовому режимі (через +k8s:alpha), воно підвищується до бета-версії. Коли DeclarativeValidationBeta увімкнено (стандартно), правила +k8s:beta застосовуються примусово і є авторитетними. Вимкнення функціональної можливості повертає правила +k8s:beta до тіньового режиму, забезпечуючи механізм відкату у разі виникнення регресій.

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

Аргументи:

• since (string, обовʼязково): Версія Kubernetes, в якій валідація була підвищена до бета-версії.

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

• <validation-tag>: Стандартний декларативний теґ валідації, який буде застосовуватися примусово (наприклад, +k8s:minimum=1).

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

type MyStruct struct {
    // +k8s:beta(since:"1.37")=+k8s:minimum=1
    MyField int `json:"myField"`
}

+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: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: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, мають унікальне імʼя, що дозволяє ідемпотентне¹ створення та отримання, за винятком віртуальних типів ресурсів, які можуть не мати унікальних імен, якщо вони не можуть бути отримані або не залежать від ідемпотентності.

У межах простору імен, унікальна ідентичність обʼєкта визначається кортежем його API Group, Resource, Namespace та Name.

• Cross-Group: Ви можете мати два обʼєкти з однаковим іменем, якщо вони належать до різних API Groups (наприклад, apps та example.com).
• Cross-Version: Різні версії API (наприклад, v1 та v1beta1) однієї групи та ресурсу представляють ті самі базові дані. Створення обʼєкта з однаковим іменем у іншій версії тієї ж групи призводить до конфлікту імен, оскільки вони мають однакову ідентичність у сховищі.

Деякі обʼєкти не належать до простору імен (наприклад: 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">

Фрагментований list та watch

На великих кластерах контролери, які спостерігають за ресурсами з високою кардинальністю (наприклад, Podʼи або Endpoints), можуть споживати значну пропускну здатність мережі та CPU, отримуючи та десеріалізуючи повний потік подій, навіть якщо їм потрібна лише підмножина обʼєктів. Фрагментований list та watch дозволяє горизонтально масштабованим контролерам розподіляти навантаження так, щоб кожна репліка отримувала лише ті події, за які вона відповідає.

Kubernetes 1.36 в альфа-версії представляє функцію, яка дозволяє клієнтам запитувати фільтровані фрагменти обʼєктів з API-сервера, використовуючи хешоване розподілення за метаданими. Щоб використовувати цю функцію, увімкніть функціональну можливість ShardedListAndWatch на API-сервері. Коли функція увімкнена, API-сервер фільтрує як відповіді на list, так і потоки подій watch на стороні сервера, доставляючи лише ті обʼєкти та події, хешоване значення метаданих яких потрапляє в запитаний діапазон.

Поле shardSelector

Поле ShardSelector у ListOptions приймає вираз на основі CEL з використанням функції shardRange():

shardRange(<field-path>, '<hex-start>', '<hex-end>')

Де:

• <field-path> — це поле метаданих, яке потрібно хешувати, використовуючи синтаксис CEL, що базується на корені обʼєкта. Підтримувані шляхи:
  • object.metadata.uid
  • object.metadata.namespace
• <hex-start> — включна нижня межа діапазону хешу, у вигляді 16-значного шістнадцяткового рядка з префіксом 0x (наприклад, '0x0000000000000000').
• <hex-end> — виключна верхня межа, у вигляді шістнадцяткового рядка з префіксом 0x. Максимальне значення — '0x10000000000000000' (2^64).

API-сервер обчислює детермінований 64-бітний FNV-1a хеш вказаного значення поля і повертає лише ті обʼєкти, хеш яких потрапляє в діапазон [start, end). Функція хешування дає однаковий результат для одного й того ж вхідного значення на всіх екземплярах API-сервера, тому фрагментовані запити безпечні для використання з кількома репліками API-сервера.

Ви можете комбінувати кілька діапазонів за допомогою || (логічне АБО), щоб охопити неперервні частини простору хешу. Усі діапазони в одному виразі повинні використовувати той самий шлях до поля.

Використання фрагментованого list та watch у контролерах

Контролери зазвичай використовують інформери для list та watch ресурсів. Щоб розподілити навантаження між репліками, кожна репліка вставляє поле ShardSelector у ListOptions, які використовуються її інформерами.

Стандартний спосіб зробити це — використовувати WithTweakListOptions при створенні спільної фабрики інформерів. Функція tweak виконується перед кожним викликом list та watch, який робить інформер, тому селектор фрагментів застосовується послідовно:

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/informers"
)

// shardSelector визначається ідентичністю репліки (наприклад, з порядкового номера StatefulSet або на основі оренди). Кожна репліка претендує на неперетинний діапазон простору хешу.
shardSelector := "shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"

factory := informers.NewSharedInformerFactoryWithOptions(client, resyncPeriod,
    informers.WithTweakListOptions(func(opts *metav1.ListOptions) {
        opts.ShardSelector = shardSelector
    }),
)

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

Для розгортання з 2 репліками селектори будуть такими:

// Репліка 0: нижня половина простору хешу
"shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"

// Репліка 1: верхня половина простору хешу
"shardRange(object.metadata.uid, '0x8000000000000000', '0x10000000000000000')"

Одна репліка також може обробляти неперервні діапазони, використовуючи ||:

"shardRange(object.metadata.uid, '0x0000000000000000', '0x4000000000000000') || " +
    "shardRange(object.metadata.uid, '0x8000000000000000', '0xc000000000000000')"

Інформація про фрагменти у відповідях

Коли сервер API враховує ShardSelector, відповідь на list включає поле shardInfo у метаданих списку. Це відображає селектор, щоб клієнти могли перевірити, який фрагмент вони отримали. Для потоків watch селектор фрагментів застосовується однаково: сервер API надсилає події лише для обʼєктів, хеш яких потрапляє в запитуваний діапазон.

{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "10245",
    "shardInfo": {
      "selector": "shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"
    }
  },
  "items": [...]
}

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

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

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

Опція 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.36) пропонує спосіб визначення перевірки полів за допомогою декларативних теґів. Це корисно для тих, хто бере участь у розробці самого 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.36 обслуговує "найсвіжіші" читання з 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, отриманий обʼєкт кількості має наступний набір методів: