# Kubernetes

На [предыдущей странице](/learn/deployment/sizing-and-resources.md) мы рассчитали ресурсы ORDERS: файловый поток R3 в томе 10 Gi, а `order-svc` — примерно в 128 Mi памяти. Теперь развернём кластер в Kubernetes.

Три узла `east` из главы топологий (`n1-east`, `n2-east`, `n3-east`) становятся тремя подами. Kubernetes именует их по порядковым номерам: **`nats-0`, `nats-1`, `nats-2`**. Это те же узлы с тем же потоком R3 `ORDERS`. Дальше используются имена подов, поскольку плавный вывод, бюджет нарушений и последовательные обновления опираются на их номера.

Здесь два новых понятия: чарт NATS Helm, развёртывающий StatefulSet, и контроллер NACK, позволяющий объявить `ORDERS` и его потребителей ресурсами Kubernetes вместо команд CLI.

## Чарт NATS Helm развёртывает StatefulSet

Кластер NATS хранит состояние. Каждый узел держит свою часть реплицированного потока на собственном диске, а идентичность должна переживать перезапуск: `nats-1` обязан вернуться как `nats-1` со своим томом. Для этого нужен **StatefulSet** — нагрузка Kubernetes со стабильными именами подов, сетевыми идентификаторами и томами.

**Чарт NATS Helm** устанавливает StatefulSet за вас. Файл `values.yaml` описывает кластер, а Helm создаёт StatefulSet, headless-сервис, ConfigMap и проверки. Минимальный файл для трёх узлов ORDERS:

```
# values.yaml — the three-node ORDERS cluster

config:

  cluster:

    enabled: true

    replicas: 3          # nats-0, nats-1, nats-2

  jetstream:

    enabled: true

    fileStore:

      pvc:

        size: 10Gi       # the sizing baseline from the previous page
```

Установите релиз под именем `nats`: именно оно задаёт имена подов `nats-N`.

```
helm repo add nats https://nats-io.github.io/k8s/helm/charts/

helm install nats nats/nats -f values.yaml
```

Отметим две детали. Чарт уже задаёт StatefulSet параметр `podManagementPolicy: Parallel`, добавлять его в `values.yaml` не нужно. Все три пода запускаются вместе. Последовательный запуск по умолчанию ждал бы готовности каждого перед следующим, что может заблокировать кластер NATS: одиночный узел ещё не видит соседей. Parallel позволяет им найти друг друга и сформировать кластер.

Вторая деталь — **headless-сервис**. Он даёт каждому поду стабильное DNS-имя вроде `nats-0.nats-headless.default.svc.cluster.local`, используемое для маршрутов между узлами. Клиенты подключаются к обычному ClusterIP-сервису `nats`, который тоже создаёт чарт. Именно из его набора адресов readiness исключает неготовые поды.

У чарта много других параметров с разумными значениями по умолчанию. Все настройки сервера описаны в [Справочнике → Конфигурация](/reference/config/.md); здесь нужны лишь параметры этого развёртывания.

## Три проверки на порту мониторинга

Kubernetes управляет жизненным циклом пода по проверкам. У JetStream есть три состояния, которые важно различать. Чарт направляет все три проверки на порт 8222 и `/healthz`:

```
# rendered into the StatefulSet by the chart — shown for reference

startupProbe:

  httpGet: { path: /healthz, port: 8222 }

  failureThreshold: 90        # ~900s window for the node to boot + sync

readinessProbe:

  httpGet: { path: "/healthz?js-server-only=true", port: 8222 }

livenessProbe:

  httpGet: { path: "/healthz?js-enabled-only=true", port: 8222 }
```

**Startup probe** защищает время запуска. Вернувшийся узел может несколько минут догонять реплики потоков; большой порог ошибок не даёт Kubernetes убить его за нормальную работу запуска. **Readiness probe** определяет готовность обслуживать клиентов и исключает неготовый под из сервиса. **Liveness probe** проверяет лишь включение JetStream и служит последней мерой перезапуска зависшего процесса.

Значение параметров `/healthz` и выбор уведомлений для оповещения рассмотрены в [Мониторинг → Состояние JetStream](/learn/monitoring/jetstream-health.md). Здесь проверки передают состояние подов StatefulSet.

## Объявите потоки через CRD контроллера NACK

Можно открыть оболочку в `nats-box` и вручную выполнить `nats stream add ORDERS`. Но это императивный подход: поток существует благодаря выполненной команде, и после удаления ничто его не вернёт. Для декларативной модели Kubernetes у NATS есть контроллер.

**Контроллер NACK** работает в Kubernetes и согласует ресурсы **CRD** (Custom Resource Definitions) с кластером NATS. Вы описываете нужный `ORDERS` ресурсом `Stream`, применяете его через `kubectl`, а контроллер вызывает API JetStream для приведения кластера к описанию. Контроллер Kubernetes и оператор безопасности `ACME` — разные понятия; последний рассмотрен в [Безопасности](/learn/security/.md).

Тот же файловый поток R3 `ORDERS`, теперь в декларативном виде CRD:

```
# orders-stream.yaml — the ORDERS stream as a declarative resource

apiVersion: jetstream.nats.io/v1beta2

kind: Stream

metadata:

  name: orders

spec:

  name: ORDERS

  subjects: ["orders.>"]

  storage: file

  replicas: 3
```

И два его потребителя: `shipping`, запрашивающий сообщения, и `analytics`, фильтрующий `orders.shipped`.

```
# orders-consumers.yaml — consumers as declarative resources

apiVersion: jetstream.nats.io/v1beta2

kind: Consumer

metadata:

  name: shipping

spec:

  streamName: ORDERS

  durableName: shipping

---

apiVersion: jetstream.nats.io/v1beta2

kind: Consumer

metadata:

  name: analytics

spec:

  streamName: ORDERS

  durableName: analytics

  filterSubject: orders.shipped
```

Примените ресурсы; остальное сделает контроллер:

```
kubectl apply -f orders-stream.yaml -f orders-consumers.yaml
```

Контроллер наблюдает CRD, вызывает API JetStream, создаёт поток R3 на `nats-0..2` и записывает результат в `.status`. Теперь желаемое состояние потока находится в системе контроля версий, а не в истории терминала.

**Движение сообщений — Сверка NACK и самовосстановление (анимация):** Цикл NACK сверяет Stream CRD и автоматически исправляет расхождения. Kubectl apply сохраняет желаемый ORDERS с 3 репликами в Kubernetes API. Контроллер видит ресурс, вызывает JetStream API для создания R3 на nats-0, nats-1 и nats-2, затем записывает результат в .status CRD. Если поток удалён вручную, фактическое состояние расходится с объявленным; следующая сверка обнаруживает удаление и автоматически пересоздаёт поток R3.

* kubectl → K8s API / etcd
* K8s API / etcd → контроллер NACK
* контроллер NACK → nats-1
* контроллер NACK → K8s API / etcd
* контроллер NACK → nats-1 (тема: поток удалён — расхождение!)

Согласование работает циклически. Если удалить поток вручную, контроллер обнаружит расхождение и пересоздаст его по CRD. Объявленное состояние служит источником истины.

У `Stream` есть много других полей: `maxBytes`, `maxAge`, `placement`, `mirror`, `sources` и прочая конфигурация потока. Полный список приведён в [Справочнике → Конфигурация](/reference/config/.md); здесь заданы нужные ORDERS поля.

## Типичные ошибки

При первом запуске NATS в Kubernetes встречаются несколько ловушек, относящихся к StatefulSet и CRD.

**Под в Pending обычно ждёт том.** Под StatefulSet не запустится до привязки постоянного тома. Без класса хранения по умолчанию запрос может ждать бесконечно: `nats-0` остаётся в `Pending`, а с ним и кластер. Чарт создаёт отдельный запрос тома каждому поду через `volumeClaimTemplates`. Проверяйте наличие класса хранения вместо удаления и повторного запуска пода.

**Правка ConfigMap сама не перечитывает конфигурацию сервера.** Файл меняется, но работающий `nats-server` использует старые настройки до SIGHUP. Чарт включает **вспомогательный контейнер перечитывания конфигурации** `nats-server-config-reloader` по умолчанию. Без него изменения применятся лишь при перезапуске. Подробности на странице [Управление конфигурацией](/learn/deployment/config-management.md).

**Догоняющая репликация учитывается startup, а не readiness.** Readiness обращается к `/healthz?js-server-only=true`: проверяется лишь работа сервера и JetStream, без потоков, потребителей и назначений метаданных. Поэтому под, догоняющий реплики R3 после перезапуска, остаётся готовым обслуживать клиентов. Обычный `/healthz` из startup строже: проверяет слой метаданных и все потоки и потребителей. Поэтому `failureThreshold` равен 90, давая время синхронизации. Для увеличения окна переопределите поля проверки через `merge`/`patch` контейнера чарта: отдельного параметра `failureThreshold` в values нет.

**Не смешивайте CLI и CRD для одного потока.** Поведение NACK зависит от режима. По умолчанию он пересоздаёт удалённый поток при повторной сверке примерно каждые 30 секунд, но *не* отменяет ручной `nats stream edit`: изменение остаётся до следующей правки CRD. Режим `--control-loop` также исправляет расхождения конфигурации примерно раз в минуту. В любом случае выберите одного владельца потока: CRD или CLI.

Проверьте, что контроллер действительно создал объявленный поток R3. Откройте оболочку `nats-box` и прочитайте его состояние:

#### CLI

```
#!/bin/bash



# Confirm the stream the NACK controller created from a Stream CRD is

# really the R3 ORDERS stream you declared — not a half-applied or

# single-replica copy. Run this from the nats-box pod that the NATS Helm

# chart deploys alongside the StatefulSet, so it resolves nats-0..2 over

# the headless service.

#

# Open a shell in nats-box first:

#   kubectl exec -it deploy/nats-box -- sh

# then run the commands below against the cluster.



# List every stream the cluster holds. After the Stream CRD reconciles,

# ORDERS appears here even though no human ran `nats stream add` — the

# controller created it from the declarative resource.

nats stream ls



# Read ORDERS back in full. The line that matters for a CRD-created

# stream is Replicas: 3 — proof the controller honoured `replicas: 3`

# from the CRD spec and placed a copy on each of nats-0, nats-1, nats-2.

nats stream info ORDERS



# Publish one order to prove the CRD-created stream actually accepts

# writes across all three replicas. The payload is the canonical Acme

# order shape, unchanged from every other chapter.

nats pub orders.created \

  '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'



# Expected (trimmed): the Configuration block shows

#   Replicas: 3

#   Storage:  File

# and the State block shows the message you just published, with the

# Cluster section listing nats-0 as leader and nats-1/nats-2 as

# replicas. If Replicas reads 1, the CRD spec is missing `replicas: 3`

# or the controller has not finished reconciling yet — re-run after the

# .status block on the CRD reports ready.
```

#### C

```
// List every stream the cluster holds. After the Stream CRD

// reconciles, ORDERS appears here even though no human ran

// `nats stream add` -- the NACK controller created it from the

// declarative resource.

if (s == NATS_OK)

    s = js_Streams(&list, js, NULL, &jerr);

if (s == NATS_OK)

{

    for (i = 0; i < list->Count; i++)

        printf("stream: %s\n", list->List[i]->Config->Name);

}



// Read ORDERS back in full. The number that matters for a

// CRD-created stream is Replicas: 3 -- proof the controller

// honoured `replicas: 3` from the CRD spec and placed a copy on

// each of nats-0, nats-1, nats-2.

if (s == NATS_OK)

    s = js_GetStreamInfo(&si, js, "ORDERS", NULL, &jerr);

if (s == NATS_OK)

{

    printf("ORDERS replicas: %" PRId64 "\n", si->Config->Replicas);

    if (si->Cluster != NULL)

        printf("ORDERS leader:   %s\n", si->Cluster->Leader);

}



// Publish one order to prove the CRD-created stream actually

// accepts writes across all three replicas.

if (s == NATS_OK)

    s = js_Publish(&ack, js, "orders.created",

                   order, (int) strlen(order), NULL, &jerr);

if (s == NATS_OK)

    printf("stored in %s, sequence %" PRIu64 "\n",

           ack->Stream, ack->Sequence);
```

Важна строка `Replicas: 3`. Если указано `1`, в CRD отсутствует `replicas: 3` либо согласование ещё не завершено. Сначала проверьте `.status` ресурса.

## Что уже готово

Кластер ORDERS работает в Kubernetes:

* Три пода `nats-0`, `nats-1`, `nats-2` управляются StatefulSet и имеют стабильные имена, DNS и тома. Это прежние `n1-east`/`n2-east`/`n3-east`.
* Чарт NATS Helm создаёт StatefulSet, headless-сервис, ConfigMap и три проверки `/healthz`.
* Поток `ORDERS` и потребители `shipping`, `analytics` объявлены через CRD и согласуются NACK; желаемое состояние хранится в контроле версий.

## Что дальше

Кластер запущен, но конфигурация пока находится в ConfigMap, который вы ещё не умеете менять без перезапуска. Следующая страница разделяет её на включаемые файлы и применяет ограничения, пути TLS и учётные записи через SIGHUP без простоя.

Перейдите к [управлению конфигурацией](/learn/deployment/config-management.md).

## См. также

* [Справочник → Конфигурация](/reference/config/.md) — настройки сервера и полный набор полей `Stream` CRD.
* [Топологии → Ваш первый кластер](/learn/topologies/your-first-cluster.md) — узлы `n1-east`/`n2-east`/`n3-east`, развёрнутые этими подами.
* [Мониторинг → Состояние JetStream](/learn/monitoring/jetstream-health.md) — смысл проверок `/healthz` и выбор оповещений.
