StatefulSet

StatefulSet представляет набор подов с устойчивыми идентификаторами. Идентификаторы определяются следующим образом:

Сеть: единый стабильный DNS-адрес и имя хоста.
Хранилище: столько VolumeClaims, сколько запрошено.

StatefulSet гарантирует, что заданному сетевому идентификатору всегда будет соответствовать один и тот же идентификатор хранилища.

Документация по концепции StatefulSet

StatefulSet

StatefulSet запускает группу подов и поддерживает постоянный идентификатор для каждого из них. Это полезно для управления приложениями, которым требуется постоянное хранилище или стабильный уникальный сетевой идентификатор.

apiVersion: apps/v1

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

StatefulSet

Сеть: единый стабильный DNS-адрес и имя хоста.
Хранилище: столько VolumeClaims, сколько запрошено.

Поле	Описание
`apiVersion` string	APIVersion определяет версионированную схему этого представления объекта. Серверы должны преобразовывать распознанные схемы в последнее внутреннее значение и могут отклонять нераспознанные значения. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`kind` string	Kind — строковое значение, представляющее ресурс REST, который представляет этот объект. Серверы могут определять его по конечной точке, на которую клиент отправляет запросы. Обновление невозможно. В формате CamelCase. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ObjectMeta	Стандартные метаданные объекта. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
`spec` StatefulSetSpec	Spec определяет желаемые идентификаторы подов в этом наборе.
`status` StatefulSetStatus	Status — текущее состояние подов в этом StatefulSet. Эти данные могут быть устаревшими в течение некоторого времени.

StatefulSetSpec

StatefulSetSpec — это спецификация StatefulSet.

Поле	Описание
`minReadySeconds` integer	Минимальное количество секунд, в течение которых вновь созданный под должен оставаться готовым, не допуская сбоев ни одного из своих контейнеров, чтобы считаться доступным. По умолчанию — 0 (под считается доступным сразу после перехода в состояние готовности).
`ordinals` StatefulSetOrdinals	ordinals управляет нумерацией индексов реплик в StatefulSet. По умолчанию первой реплике назначается индекс "0", а индекс каждой последующей запрошенной реплики увеличивается на единицу.
`persistentVolumeClaimRetentionPolicy` StatefulSetPersistentVolumeClaimRetentionPolicy	persistentVolumeClaimRetentionPolicy описывает жизненный цикл постоянных томов, созданных на основе volumeClaimTemplates. По умолчанию все постоянные тома создаются по мере необходимости и сохраняются до ручного удаления. Эта политика позволяет изменить жизненный цикл, например удалять постоянные тома при удалении их StatefulSet или при уменьшении числа его подов.
`podManagementPolicy` string	podManagementPolicy управляет созданием подов при первоначальном масштабировании, замене подов на узлах или уменьшении масштаба. По умолчанию используется политика `OrderedReady`: поды создаются по возрастанию (pod-0, затем pod-1 и т. д.), а контроллер ожидает готовности каждого пода, прежде чем продолжить. При уменьшении масштаба поды удаляются в обратном порядке. Альтернативная политика — `Parallel`: поды создаются параллельно для достижения желаемого масштаба без ожидания, а при уменьшении масштаба удаляются все сразу. Возможные значения перечисления: - `"OrderedReady"` создает поды в строго возрастающем порядке при увеличении масштаба и в строго убывающем порядке при его уменьшении, продолжая работу только после готовности или завершения предыдущего пода. Одновременно изменяется не более одного пода. - `"Parallel"` создает и удаляет поды сразу после изменения количества реплик StatefulSet, не ожидая готовности подов или завершения их удаления.
`replicas` integer	replicas — желаемое количество реплик указанного шаблона. Это реплики в том смысле, что они являются экземплярами одного и того же шаблона, однако каждая отдельная реплика также имеет устойчивый идентификатор. Если значение не указано, по умолчанию используется 1.
`revisionHistoryLimit` integer	revisionHistoryLimit — максимальное количество ревизий, сохраняемых в истории ревизий StatefulSet. История ревизий включает все ревизии, не представленные текущей примененной версией StatefulSetSpec. Значение по умолчанию — 10.
`selector` * LabelSelector	selector — запрос по меткам для подов, которые должны соответствовать количеству реплик. Он должен соответствовать меткам шаблона пода. Подробнее: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
`serviceName` string	serviceName — имя сервиса, управляющего этим StatefulSet. Этот сервис должен существовать до создания StatefulSet и отвечает за сетевой идентификатор набора. DNS-имена и имена хостов подов формируются по шаблону: pod-specific-string.serviceName.default.svc.cluster.local, где "pod-specific-string" управляется контроллером StatefulSet.
`template` * PodTemplateSpec	template — объект, описывающий под, который будет создан при обнаружении недостаточного количества реплик. Каждый под, созданный StatefulSet, соответствует этому шаблону, но имеет уникальный идентификатор, отличающий его от остальных подов StatefulSet. Имя каждого пода формируется по шаблону \-\. Например, под в StatefulSet с именем "web" и индексом "3" будет называться "web-3". Единственное допустимое значение template.spec.restartPolicy — "Always".
`updateStrategy` StatefulSetUpdateStrategy	updateStrategy указывает StatefulSetUpdateStrategy, которая будет использоваться для обновления подов StatefulSet при изменении шаблона.
`volumeClaimTemplates` PersistentVolumeClaim array	volumeClaimTemplates — список запросов, на которые могут ссылаться поды. Контроллер StatefulSet отвечает за сопоставление сетевых идентификаторов с запросами таким образом, чтобы сохранять идентификатор пода. Для каждого запроса из этого списка должен существовать как минимум один соответствующий ему по имени volumeMount в одном из контейнеров шаблона. Запрос из этого списка имеет приоритет перед любыми томами с таким же именем в шаблоне.

StatefulSetStatus

StatefulSetStatus представляет текущее состояние StatefulSet.

Поле	Описание
`availableReplicas` integer	Общее количество доступных подов (готовых не менее minReadySeconds), которыми управляет этот StatefulSet.
`collisionCount` integer	collisionCount — количество коллизий хешей для StatefulSet. Контроллер StatefulSet использует это поле для предотвращения коллизий, когда ему требуется создать имя для новейшего ControllerRevision.
`conditions` StatefulSetCondition array patch strategy: merge on key `type`	Представляет последние доступные наблюдения за текущим состоянием StatefulSet.
`currentReplicas` integer	currentReplicas — количество подов, созданных контроллером StatefulSet на основе версии StatefulSet, указанной в currentRevision.
`currentRevision` string	currentRevision, если поле не пустое, указывает версию StatefulSet, использованную для создания подов в последовательности [0,currentReplicas).
`observedGeneration` integer	observedGeneration — последнее поколение, наблюдавшееся для этого StatefulSet. Оно соответствует поколению StatefulSet, которое обновляется API-сервером при изменении объекта.
`readyReplicas` integer	readyReplicas — количество подов, созданных для этого StatefulSet и имеющих условие Ready.
`replicas` * integer	replicas — количество подов, созданных контроллером StatefulSet.
`updateRevision` string	updateRevision, если поле не пустое, указывает версию StatefulSet, использованную для создания подов в последовательности [replicas-updatedReplicas,replicas).
`updatedReplicas` integer	updatedReplicas — количество подов, созданных контроллером StatefulSet на основе версии StatefulSet, указанной в updateRevision.

StatefulSetList

StatefulSetList — это коллекция объектов StatefulSet.

Поле	Описание
`apiVersion` string	APIVersion определяет версионированную схему этого представления объекта. Серверы должны преобразовывать распознанные схемы в последнее внутреннее значение и могут отклонять нераспознанные значения. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`items` * StatefulSet array	Items — список объектов StatefulSet.
`kind` string	Kind — строковое значение, представляющее ресурс REST, который представляет этот объект. Серверы могут определять его по конечной точке, на которую клиент отправляет запросы. Обновление невозможно. В формате CamelCase. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ListMeta	Стандартные метаданные списка. Подробнее: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

RollingUpdateStatefulSetStrategy

RollingUpdateStatefulSetStrategy используется для передачи параметров типа RollingUpdateStatefulSetStrategyType.

Поле Описание

maxUnavailable Максимальное количество подов, которые могут быть недоступны во время обновления. Значение может быть абсолютным числом (например, 5) или процентом от желаемого количества подов (например, 10%). Абсолютное число рассчитывается из процента округлением вверх. Значение не может быть равно 0. По умолчанию — 1. Это поле уровня beta и включено по умолчанию. Поле применяется ко всем подам в диапазоне от 0 до Replicas-1. Это означает, что любой недоступный под в диапазоне от 0 до Replicas-1 будет учитываться при расчете MaxUnavailable. Эта настройка может не действовать при политике podManagementPolicy OrderedReady. Эта политика обеспечивает создание подов и переход в состояние готовности по одному.

partition
integer Partition указывает порядковый номер, на котором StatefulSet следует разделить при обновлении. Во время постепенного обновления обновляются все поды с порядковыми номерами от Replicas-1 до Partition. Все поды с порядковыми номерами от Partition-1 до 0 остаются без изменений. Это полезно для развертывания с использованием канареечного подхода. Значение по умолчанию — 0.

Поле	Описание
`maxUnavailable`	Максимальное количество подов, которые могут быть недоступны во время обновления. Значение может быть абсолютным числом (например, 5) или процентом от желаемого количества подов (например, 10%). Абсолютное число рассчитывается из процента округлением вверх. Значение не может быть равно 0. По умолчанию — 1. Это поле уровня beta и включено по умолчанию. Поле применяется ко всем подам в диапазоне от 0 до Replicas-1. Это означает, что любой недоступный под в диапазоне от 0 до Replicas-1 будет учитываться при расчете MaxUnavailable. Эта настройка может не действовать при политике podManagementPolicy OrderedReady. Эта политика обеспечивает создание подов и переход в состояние готовности по одному.
`partition` integer	Partition указывает порядковый номер, на котором StatefulSet следует разделить при обновлении. Во время постепенного обновления обновляются все поды с порядковыми номерами от Replicas-1 до Partition. Все поды с порядковыми номерами от Partition-1 до 0 остаются без изменений. Это полезно для развертывания с использованием канареечного подхода. Значение по умолчанию — 0.

StatefulSetCondition

StatefulSetCondition описывает состояние StatefulSet в определенный момент времени.

Поле	Описание
`lastTransitionTime` Time	Время последнего перехода условия из одного состояния в другое.
`message` string	Понятное человеку сообщение с подробностями о переходе.
`reason` string	Причина последнего перехода условия.
`status` * string	Статус условия: True, False или Unknown.
`type` * string	Тип условия StatefulSet.

StatefulSetOrdinals

StatefulSetOrdinals описывает политику назначения порядковых номеров репликам в этом StatefulSet.

Поле Описание

start
integer start — число, обозначающее индекс первой реплики. Его можно использовать для нумерации реплик с альтернативного индекса (например, с 1) вместо стандартных имен с индексом 0 или для постепенного перемещения реплик из одного StatefulSet в другой. Если задано, индексы реплик будут находиться в диапазоне [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas). Если не задано, по умолчанию используется 0. Индексы реплик будут находиться в диапазоне [0, .spec.replicas).

Поле	Описание
`start` integer	start — число, обозначающее индекс первой реплики. Его можно использовать для нумерации реплик с альтернативного индекса (например, с 1) вместо стандартных имен с индексом 0 или для постепенного перемещения реплик из одного StatefulSet в другой. Если задано, индексы реплик будут находиться в диапазоне [.spec.ordinals.start, .spec.ordinals.start + .spec.replicas). Если не задано, по умолчанию используется 0. Индексы реплик будут находиться в диапазоне [0, .spec.replicas).

StatefulSetPersistentVolumeClaimRetentionPolicy

StatefulSetPersistentVolumeClaimRetentionPolicy описывает политику для PVC, создаваемых на основе VolumeClaimTemplates StatefulSet.

Поле Описание

whenDeleted
string WhenDeleted определяет, что происходит с PVC, созданными на основе VolumeClaimTemplates StatefulSet, при удалении StatefulSet. Политика `Retain`, используемая по умолчанию, не затрагивает PVC при удалении StatefulSet. Политика `Delete` приводит к удалению этих PVC.

whenScaled
string WhenScaled определяет, что происходит с PVC, созданными на основе VolumeClaimTemplates StatefulSet, при уменьшении масштаба StatefulSet. Политика `Retain`, используемая по умолчанию, не затрагивает PVC при уменьшении масштаба. Политика `Delete` приводит к удалению связанных PVC для всех лишних подов сверх заданного количества реплик.

Поле	Описание
`whenDeleted` string	WhenDeleted определяет, что происходит с PVC, созданными на основе VolumeClaimTemplates StatefulSet, при удалении StatefulSet. Политика `Retain`, используемая по умолчанию, не затрагивает PVC при удалении StatefulSet. Политика `Delete` приводит к удалению этих PVC.
`whenScaled` string	WhenScaled определяет, что происходит с PVC, созданными на основе VolumeClaimTemplates StatefulSet, при уменьшении масштаба StatefulSet. Политика `Retain`, используемая по умолчанию, не затрагивает PVC при уменьшении масштаба. Политика `Delete` приводит к удалению связанных PVC для всех лишних подов сверх заданного количества реплик.

StatefulSetUpdateStrategy

StatefulSetUpdateStrategy указывает стратегию, которую контроллер StatefulSet будет использовать для выполнения обновлений. Она включает любые дополнительные параметры, необходимые для выполнения обновления с выбранной стратегией.

Поле Описание

rollingUpdate
RollingUpdateStatefulSetStrategy RollingUpdate используется для передачи параметров, когда Type имеет значение RollingUpdateStatefulSetStrategyType.

type
string Type указывает тип StatefulSetUpdateStrategy. По умолчанию используется RollingUpdate.

Возможные значения перечисления:
- `"OnDelete"` включает устаревшее поведение. Отслеживание версий и упорядоченные последовательные перезапуски отключены. Поды пересоздаются из StatefulSetSpec при их ручном удалении. При выполнении операции масштабирования с этой стратегией используется версия спецификации, указанная в currentRevision объекта StatefulSet.
- `"RollingUpdate"` указывает, что обновление будет применено ко всем подам StatefulSet с учетом ограничений на порядок StatefulSet. При выполнении операции масштабирования с этой стратегией новые поды будут создаваться на основе версии спецификации, указанной в updateRevision объекта StatefulSet.

Поле	Описание
`rollingUpdate` RollingUpdateStatefulSetStrategy	RollingUpdate используется для передачи параметров, когда Type имеет значение RollingUpdateStatefulSetStrategyType.
`type` string	Type указывает тип StatefulSetUpdateStrategy. По умолчанию используется RollingUpdate. Возможные значения перечисления: - `"OnDelete"` включает устаревшее поведение. Отслеживание версий и упорядоченные последовательные перезапуски отключены. Поды пересоздаются из StatefulSetSpec при их ручном удалении. При выполнении операции масштабирования с этой стратегией используется версия спецификации, указанная в currentRevision объекта StatefulSet. - `"RollingUpdate"` указывает, что обновление будет применено ко всем подам StatefulSet с учетом ограничений на порядок StatefulSet. При выполнении операции масштабирования с этой стратегией новые поды будут создаваться на основе версии спецификации, указанной в updateRevision объекта StatefulSet.

© 2026 The Kubernetes Authors | Documentation Distributed under CC BY 4.0
Copyright © 2026 The Linux Foundation ®. All rights reserved.
https://kubernetes.io/docs/reference/kubernetes-api/apps/stateful-set-v1/