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

Kubernetes 1.37 використовує декларативну перевірку для дедалі більшого набору API. Замість рукописного коду Go (validation.go) автори API оголошують правила перевірки як теґи коментарів у визначеннях типів (types.go), наприклад +k8s:minimum=0. Генератор коду, validation-gen, перетворює ці теґи на код перевірки.

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

Життєвий цикл перевірки

Для нових полів API використовуйте теґ безпосередньо, наприклад +k8s:minimum=1. Такі теґи завжди застосовуються.

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

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

Функціональні можливості

• DeclarativeValidation: змушує API-сервер порівнювати декларативні та рукописні результати для правил +k8s:alpha і +k8s:beta та звітувати про невідповідності. Декларативна перевірка виконується у будь-якому разі; ця функціональна можливість керує лише звітуванням.

• DeclarativeValidationBeta: глобальний вимикач безпеки для правил +k8s:beta. Якщо увімкнено, вони застосовуються; якщо вимкнено, вони повертаються в тіньовий режим.

• DeclarativeValidationTakeover: замінено на DeclarativeValidationBeta і більше не враховується. Її встановлення все ще приймається.

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

Моніторинг декларативної перевірки

API-сервер надає такі метрики:

Невідповідності також реєструються в журналі. Для правила, що застосовується (+k8s:beta), запис у журналі пропонує вимкнути DeclarativeValidationBeta, щоб зберегти дані в etcd узгодженими з попередніми версіями Kubernetes.

Вимкнення DeclarativeValidationBeta

Розгляньте можливість встановлення DeclarativeValidationBeta=false, якщо ви бачите:

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

• Погіршення продуктивності: збільшення затримок (наприклад, у apiserver_request_duration_seconds), яке корелює з цією функціональною можливістю.

• Високий рівень невідповідностей: часті інкременти declarative_validation_mismatch_total, які впливають на ваші робочі навантаження.

Щоб повернути правила +k8s:beta у тіньовий режим, передайте --feature-gates=DeclarativeValidationBeta=false.

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

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

Теґи декларативної перевірки

Як читати цю довідку

Кожен теґ має рівень стабільності — Alpha, Beta або Stable, — що описує зрілість самого теґа. Це окремо від префіксів життєвого циклу +k8s:alpha та +k8s:beta, які описують зрілість одного застосування теґа.

Лінтер генератора використовує рівень стабільності, щоб вирішити, де теґ дозволений:

• У пакунку GA (наприклад, v1) теґ без префікса має бути Stable.

• У пакунку beta теґи Beta без префікса також дозволені.

• У пакунку alpha теґи Alpha та Beta без префікса також дозволені.

• Усередині +k8s:alpha=... дозволені теґи Alpha; усередині +k8s:beta=... — теґи Beta.

• Усередині +k8s:ifEnabled(...) або +k8s:ifDisabled(...) теґи Beta дозволені навіть у пакунку GA, оскільки опція вже керує перевіркою.

Кожен запис також перелічує області застосування, де теґ може зʼявлятися: поля структур, визначення типів, значення списків, ключі мап, значення мап або значення констант.

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

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

+k8s:alpha

Опис:

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

Рукописна перевірка залишається авторитетною; декларативне правило виконується поряд із нею, а невідповідності та паніки записуються як метрики. Це підтверджує, що обидві поводяться однаково, перш ніж ви підвищите правило до Beta.

API-сервер ніколи не застосовує правила +k8s:alpha, незалежно від функціональних можливостей.

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

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

Аргументи:

• since (string, опціонально): версія Kubernetes, у якій перевірку вперше переведено в тіньовий режим.

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

• <validation-tag> (обовʼязково): теґ декларативної перевірки, який потрібно перевести в тіньовий режим.

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

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

+k8s:beta

Опис:

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

Коли DeclarativeValidationBeta увімкнено (стандартно), правило є авторитетним, і API-сервер відкидає рукописні помилки, які воно покриває. Вимкнення функціональної можливості повертає правило в тіньовий режим.

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

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

Аргументи:

• since (string, опціонально): версія Kubernetes, у якій перевірку підвищено до Beta.

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

• <validation-tag> (обовʼязково): теґ декларативної перевірки, який потрібно застосовувати.

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

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

+k8s:customUnique

Опис:

Вказує, що спеціальна рукописна перевірка реалізує перевірку унікальності для цього списку. Це вимикає генерацію перевірки унікальності для списку, яку в іншому випадку передбачають +k8s:listType=set, +k8s:listType=map та +k8s:unique.

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

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

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

type MyStruct struct {
    // +k8s:listType=map
    // +k8s:listMapKey=key
    // +k8s:customUnique
    MyList []Item `json:"myList"`
}

У цьому прикладі генератор записує, що MyList є list-map, але не видає перевірку унікальності для нього; за цю перевірку відповідає рукописний код.

+k8s:customValidation

Опис:

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

Функція має знаходитися у згенерованому пакунку, з такою сигнатурою:

func(ctx context.Context, op operation.Operation, fldPath *field.Path, value, oldValue <ValueType>) field.ErrorList

<ValueType> — це тип значення, який можна присвоїти значенням nil: вказівник, наприклад *string, або сам тип, якщо він уже допускає значення nil (фрагмент, мапа, вказівник). Кожен згенерований пакунок потребує власного визначення, оскільки кожна копія викликає функцію, розташовану поруч із нею.

У назві функції <Type> і <Field> є ідентифікаторами Go (Replicas, а не replicas):

• Область поля: ValidateCustom_<Type>_<Field> перевіряє одне поле. Під час оновлення вона пропускається, якщо це поле не змінювалося.

• Область типу: ValidateCustom_<Type> перевіряє поля групи. Вона не пропускається під час оновлення, тому дорога перевірка має повертатися рано, коли value та oldValue рівні.

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

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

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

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

// +k8s:customValidation
type MyStruct struct {
    // +k8s:customValidation
    StringField string `json:"stringField"`

    // Обидві перевірки виконуються для цього поля.
    // +k8s:maxLength=3
    // +k8s:customValidation
    MaxLengthField string `json:"maxLengthField"`
}

+k8s:dependentForbidden

Опис:

Вказує, що коли це поле встановлено, іменоване сусіднє поле не повинно бути встановлене. Поле вважається "встановленим", коли воно є ненульовим вказівником, непорожнім зрізом або мапою або ненульовим вбудованим типом. Залежності є односторонніми. Повторіть теґ, щоб заборонити кілька сусідніх полів.

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

Області застосування: поля структур

Аргументи:

• <sibling-field-json-name> (string, обовʼязково): JSON-імʼя сусіднього поля.

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

type MyStruct struct {
    // +k8s:optional
    // +k8s:dependentForbidden("dependentA")
    // +k8s:dependentForbidden("dependentB")
    Trigger *string `json:"trigger"`

    // +k8s:optional
    DependentA *string `json:"dependentA"`

    // +k8s:optional
    DependentB *string `json:"dependentB"`
}

У цьому прикладі, якщо trigger встановлено, ні dependentA, ні dependentB не можуть бути встановлені.

+k8s:dependentRequired

Опис:

Вказує, що коли це поле встановлено, іменоване сусіднє поле також має бути встановлене. Поле вважається "встановленим", коли воно є ненульовим вказівником, непорожнім зрізом або мапою або ненульовим вбудованим типом. Залежності є односторонніми. Повторіть теґ, щоб вимагати кілька сусідніх полів.

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

Області застосування: поля структур

Аргументи:

• <sibling-field-json-name> (string, обовʼязково): JSON-імʼя сусіднього поля.

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

type MyStruct struct {
    // +k8s:optional
    // +k8s:dependentRequired("dependent")
    Trigger *string `json:"trigger"`

    // +k8s:optional
    Dependent *string `json:"dependent"`
}

У цьому прикладі, якщо trigger встановлено, dependent також має бути встановлений. Встановлення самого dependent дозволене.

+k8s:eachKey

Опис:

Оголошує перевірку для кожного ключа в мапі.

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

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

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

• <validation-tag> (обовʼязково): теґ для оцінки кожного ключа.

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

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

+k8s:eachVal

Опис:

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

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

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

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

• <validation-tag> (обовʼязково): теґ для оцінки кожного значення.

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

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

    // +k8s:eachVal=+k8s:maxLength=10
    MyList []string `json:"myList"`
}

+k8s:enum

Опис:

Вказує, що рядковий тип є переліком. Усі константні значення цього типу є значеннями переліку, якщо ви не виключите їх за допомогою +k8s:enumExclude.

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

Області застосування: визначення типів

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

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

// +k8s:enum
type MyEnum string

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

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

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

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

+k8s:enumExclude

Опис:

Вказує, що константне значення не є частиною переліку, навіть якщо тип константи має теґ +k8s:enum. Ви можете зробити виключення умовним, вклавши теґ усередину +k8s:ifEnabled або +k8s:ifDisabled. Якщо ви використовуєте кілька умовних теґів, генератор виключає значення, якщо виконана будь-яка з умов.

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

Області застосування: значення констант

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

// +k8s:enum
type MyEnum string

const (
    MyEnumA MyEnum = "A"

    // Ніколи не є дійсним значенням.
    // +k8s:enumExclude
    MyEnumB MyEnum = "B"

    // Є дійсним значенням лише поки "MyFeature" вимкнено.
    // +k8s:ifEnabled(MyFeature)=+k8s:enumExclude
    MyEnumC MyEnum = "C"
)

+k8s:forbidden

Опис:

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

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

Області застосування: поля структур

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

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

+k8s:format

Опис:

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

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

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

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

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

type MyStruct struct {
    // +k8s:format=k8s-long-name
    Subdomain string `json:"subdomain"`

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

    // +k8s:format=k8s-uuid
    ID string `json:"id"`
}

+k8s:ifDisabled

Опис:

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

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

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

Аргументи:

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

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

• <validation-tag> (обовʼязково): теґ перевірки для оцінки лише тоді, коли опцію вимкнено.

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

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

+k8s:ifEnabled

Опис:

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

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

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

Аргументи:

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

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

• <validation-tag> (обовʼязково): теґ перевірки для оцінки лише тоді, коли опцію увімкнено.

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

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

+k8s:ifMode

Опис:

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

Поле, яке несе щонайменше один теґ +k8s:ifMode, неявно заборонене у кожному режимі, який не називає жоден з його теґів.

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

Області застосування: поля структур

Аргументи:

• <mode> (string, позиційний): значення дискримінатора, для якого ця перевірка застосовується.
• modality (string, опціонально): імʼя групи дискримінаторів, коли структура має більше ніж одну групу.
• mode (string, опціонально): значення дискримінатора, як іменована альтернатива позиційному аргументу.

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

• <validation-tag> (обовʼязково): теґ для оцінки, коли режим збігається.

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

type MyStruct struct {
    // +k8s:modeDiscriminator
    Mode string `json:"mode"`

    // Обовʼязкове в режимі "A", а також з обмеженням довжини.
    // +k8s:ifMode("A")=+k8s:required
    // +k8s:ifMode("A")=+k8s:maxLength=5
    FieldA *string `json:"fieldA,omitempty"`

    // Необовʼязкове в режимі "B", неявно заборонене в усіх інших режимах.
    // +k8s:ifMode("B")=+k8s:optional
    FieldB *string `json:"fieldB,omitempty"`
}

+k8s:immutable

Опис:

Вказує, що поле не може бути оновлене. На відміну від +k8s:update, який пропонує точніші переходи, +k8s:immutable забороняє будь-яку зміну значення після створення.

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

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

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

type MyStruct struct {
    // +k8s:immutable
    StringField string `json:"stringField"`

    // +k8s:immutable
    SliceField []string `json:"sliceField"`
}

// +k8s:immutable
type ImmutableType string

+k8s:isSubresource

Опис:

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

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

Область застосування: пакунок

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

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

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

У файлі staging/src/k8s.io/api/apps/v1/doc.go оголосіть, що тип підтримує /scale:

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

У файлі staging/src/k8s.io/api/apps/v1/validations/scale/doc.go визначте правила, які виконуються лише для /scale:

// +k8s:isSubresource="/scale"
package 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-іменами полів ключів list-map. Значення можуть бути рядками, цілими числами або булевими значеннями.

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

• <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" та "Denied" є членами однієї групи нуль-або-один-з, тому щонайбільше одна з них може бути присутня.

+k8s:listMapKey

Опис:

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

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

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

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

• <field-json-name> (обовʼязково): JSON-імʼя поля для використання як ключа.

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

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

type MyItem struct {
    KeyFieldOne string `json:"keyFieldOne"`
    KeyFieldTwo string `json:"keyFieldTwo"`
    ValueField  string `json:"valueField"`
}

Ключем є комбінація keyFieldOne та keyFieldTwo.

+k8s:listType

Опис:

Оголошує семантичний тип поля списку та поведінку володіння:

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

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

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

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

• atomic | map | set (обовʼязково)

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

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

type MyItem struct {
    KeyField   string `json:"keyField"`
    ValueField string `json:"valueField"`
}

Кожен елемент MyList має мати унікальний keyField.

+k8s:maxBytes

Опис:

Вказує, що рядкове поле має обмеження на довжину в байтах. Це може дозволити щонайменше N/4 багатобайтових символів. Щоб обмежити кількість символів натомість, використовуйте +k8s:maxLength.

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

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

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

• <невідʼємне ціле число> (обовʼязково): це поле не повинно бути довшим за X байтів.

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

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

+k8s:maxItems

Опис:

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

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

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

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

• <невідʼємне ціле число> (обовʼязково): цей список не повинен містити більше X елементів.

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

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

+k8s:maxLength

Опис:

Вказує, що рядкове поле має обмеження на довжину в символах. Це може дозволити до 4*N байтів, якщо значення використовує багатобайтові символи. Щоб обмежити кількість байтів натомість, використовуйте +k8s:maxBytes.

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

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

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

• <невідʼємне ціле число> (обовʼязково): це поле не повинно бути довшим за X символів.

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

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

+k8s:maxProperties

Опис:

Надає обмеження на властивості обʼєкта, як визначено JSON Schema. У Kubernetes ви можете використовувати його лише для обмеження кількості записів у полі, визначеному як мапа Go.

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

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

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

• <невідʼємне ціле число> (обовʼязково): ця мапа не повинна мати більше X властивостей (де X <= 100000).

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

type MyStruct struct {
    // +k8s:maxProperties=32
    MyMap map[string]string `json:"myMap"`
}

+k8s:maximum

Опис:

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

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

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

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

• <ціле число> (обовʼязково): це поле має бути меншим або рівним X.

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

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

+k8s:minItems

Опис:

Вказує, що список має мінімальний розмір.

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

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

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

• <невідʼємне ціле число> (обовʼязково): цей список має містити щонайменше X елементів.

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

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

+k8s:minLength

Опис:

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

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

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

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

• <ціле число> (обовʼязково): це поле має бути щонайменше X символів завдовжки.

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

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

+k8s:minProperties

Опис:

Надає нижнє обмеження на властивості обʼєкта, як визначено JSON Schema. У Kubernetes ви можете використовувати його лише для обмеження кількості записів у полі, визначеному як мапа Go.

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

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

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

• <невідʼємне ціле число> (обовʼязково): ця мапа має містити щонайменше X властивостей (де X <= 100000).

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

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

+k8s:minimum

Опис:

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

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

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

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

• <ціле число> (обовʼязково): це поле має бути більшим або рівним X.

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

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

+k8s:modeDiscriminator

Опис:

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

Дискримінатор має бути не-вказівником string або bool. Структура може мати більше ніж одну групу дискримінаторів; назвіть додаткові групи аргументом modality. Назва групи default зарезервована, а назви груп мають відповідати ^[a-zA-Z][a-zA-Z0-9_]*$.

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

Області застосування: поля структур

Аргументи:

• modality (string, опціонально): назва групи дискримінаторів, якщо така існує більше ніж одна.

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

type MyStruct struct {
    // +k8s:modeDiscriminator
    Mode string `json:"mode"`

    // +k8s:modeDiscriminator(modality:"Legacy")
    Legacy bool `json:"legacy"`

    // +k8s:ifMode("A")=+k8s:required
    FieldA *string `json:"fieldA,omitempty"`

    // +k8s:ifMode(modality:"Legacy", mode:"true")=+k8s:required
    FieldB *string `json:"fieldB,omitempty"`
}

+k8s:monotonic

Опис:

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

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

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

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

type MyStruct struct {
    // +k8s:minimum=0
    // +k8s:monotonic
    Generation int64 `json:"generation"`
}

+k8s:neq

Опис:

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

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

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

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

• <value> (обовʼязково): заборонене значення. Парсер виводить тип (string, 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"`
}

+k8s:opaqueType

Опис:

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

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

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

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

import "some/external/package"

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

+k8s:optional

Опис:

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

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

Області застосування: поля структур

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

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

+k8s:required

Опис:

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

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

Області застосування: поля структур

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

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

+k8s:subfield

Опис:

Оголошує перевірку для підполя структури. Іменоване підполе має бути прямим полем структури або полем вбудованої структури.

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

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

Аргументи:

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

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

• <validation-tag> (обовʼязково): теґ для оцінки для підполя.

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

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

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

+k8s:supportsSubresource

Опис:

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

Без жодного теґа +k8s:supportsSubresource перевіряється лише кореневий ресурс, а запити до субресурсів завершуються помилкою "no validation found". З цим теґом, але без відповідного +k8s:isSubresource, субресурс використовує правила кореневого обʼєкта.

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

Область застосування: пакунок

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

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

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

У файлі staging/src/k8s.io/api/core/v1/doc.go, щоб обробляти /status та /scale для типів у пакунку v1:

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

+k8s:unionDiscriminator

Опис:

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

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

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

Аргументи:

• union (string, опціонально): імʼя обʼєднання, якщо таких більше ніж одне.

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

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{}

Значення D визначає, який член, M1 або M2, має бути присутнім.

+k8s:unionMember

Опис:

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

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

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

Аргументи:

• union (string, опціонально): імʼя обʼєднання, якщо таких більше ніж одне.
• memberName (string, опціонально): значення дискримінатора для цього члена. Стандартно — імʼя поля.

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

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{}

+k8s:unique

Опис:

Оголошує, що елементи поля списку є унікальними. Ви можете використовувати цей теґ разом із +k8s:listType=atomic, щоб додати обмеження унікальності без зміни семантики злиття списку, або незалежно, щоб вказати семантику унікальності.

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

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

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

• map | set (обовʼязково). З map ідентичність елемента походить із полів +k8s:listMapKey; з set — з усього значення елемента.

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

type MyStruct struct {
    // +k8s:listType=atomic
    // +k8s:unique=set
    Names []string `json:"names"`

    // +k8s:listType=atomic
    // +k8s:unique=map
    // +k8s:listMapKey=key
    Items []Item `json:"items"`
}

+k8s:update

Опис:

Надає обмеження на дозволені операції оновлення поля. Ви можете вказати кілька обмежень, використовуючи кілька теґів.

Для не-вказівникових структур NoSet і NoUnset не мають ефекту, оскільки ви не можете зняти ці поля. Для полів зрізів і мап "не встановлено" означає len == 0. Ідентичність елемента зрізу для NoAddItem і NoRemoveItem походить із +k8s:listType, +k8s:listMapKey та +k8s:unique; для мап ідентичністю елемента є ключ.

NoModify не підтримується безпосередньо для зрізів або мап; використовуйте +k8s:eachVal=+k8s:update=NoModify для незмінності окремих елементів. Для списків +k8s:eachVal=+k8s:update=NoModify вимагає listType=map або unique=map, оскільки інакше зміни вмісту неможливо виявити.

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

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

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

• NoSet | NoUnset | NoModify | NoAddItem | NoRemoveItem

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

type MyStruct struct {
    // Встановлюється один раз: може бути встановлене будь-коли, але ніколи не змінюється чи очищується.
    // +k8s:update=NoModify
    // +k8s:update=NoUnset
    SetOnce *string `json:"setOnce,omitempty"`

    // Має бути встановлене під час створення або ніколи.
    // +k8s:update=NoSet
    AtCreationOnly *string `json:"atCreationOnly,omitempty"`

    // Заморозьте форму списку; окремі елементи все ще можуть змінюватися.
    // +k8s:listType=map
    // +k8s:listMapKey=key
    // +k8s:update=NoAddItem
    // +k8s:update=NoRemoveItem
    FrozenShape []Item `json:"frozenShape"`
}

+k8s:zeroOrOneOfMember

Опис:

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

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

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

Аргументи:

• union (string, опціонально): імʼя обʼєднання, якщо таких більше ніж одне.
• memberName (string, опціонально): спеціальне імʼя члена для цього члена. Стандартно — імʼя поля.

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

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

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

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

Що далі

• Дізнайтеся про Функціональні можливості
• Прочитайте KEP-5073: Declarative Validation Of Kubernetes Native Types