Стадия жизненного цикла модуля: Предварительная версия (preview)

У модуля есть требования для установки

Экземпляр RabbitMQ описывается объектом Rabbit в вашем неймспейсе. Для каждого объекта Rabbit модуль развёртывает один сервер RabbitMQ и создаёт Service и Secret с учётными данными для подключения к нему.

Быстрый старт

Чтобы развернуть экземпляр RabbitMQ с классом default, выполните следующие шаги:

  1. Создайте неймспейс для экземпляра или выберите существующий, например rabbit.

  2. Сохраните следующий манифест в файл rabbit-sample.yaml:

    apiVersion: managed-services.deckhouse.io/v1alpha1
kind: Rabbit
metadata:
  name: rabbit-sample
spec:
  rabbitClassName: default
  configuration:
    maxMessageSize: 16Mi
  instance:
    memory:
      size: 512Mi
    cpu:
      cores: 1
      coreFraction: "50%"
    persistentVolumeClaim:
      size: 1Gi

  3. Примените манифест:

    d8 k -n rabbit apply -f rabbit-sample.yaml

  4. Дождитесь готовности экземпляра:

    d8 k -n rabbit wait rabbit/rabbit-sample --for=condition=LastValidConfigurationApplied --timeout=10m

  5. Подключите приложение к Service d8ms-rmq-rabbit-sample на порту 5672 с учётными данными из Secret d8ms-rmq-rabbit-sample-user-secret. Подробности приведены в разделе «Подключение к RabbitMQ».

Выбор класса

Класс задаёт допустимые размеры экземпляра, настройки RabbitMQ, которые можно менять, и узлы, на которых работает RabbitMQ. Укажите имя класса в параметре spec.rabbitClassName. Если параметр не задан, используется класс default.

Чтобы вывести список доступных классов, выполните команду:

d8 k get rabbitclasses

Чтобы посмотреть ограничения класса, выполните команду:

d8 k get rabbitclass <CLASS_NAME> -o yaml

Ограничения описаны в параметрах класса sizingPolicies, validations и overridableConfiguration. Если класс не существует, модуль принимает объект Rabbit с предупреждением, но не развёртывает RabbitMQ, пока класс не будет создан.

Настройка CPU и памяти

Ресурсы пода RabbitMQ задаются в секции spec.instance:

spec:
  instance:
    cpu:
      cores: 2
      coreFraction: "50%"
    memory:
      size: 2Gi

Модуль задаёт ресурсы пода следующим образом:

Ресурс Limit Request
CPU cores cores, умноженное на coreFraction
Память memory.size memory.size

Класс проверяет значения при создании и изменении объекта:

  • cores должно попадать в диапазон cores одной из политик размеров класса. Для остальных проверок используется первая подходящая политика.
  • memory.size должно попадать в диапазон memory этой политики и быть кратным её step.
  • coreFraction должно совпадать с одним из значений coreFractions этой политики и быть записано в той же форме, например "50%".
  • Значения должны удовлетворять всем правилам CEL из параметра validations класса.

Модуль передаёт RabbitMQ значение memory.size как объём доступной памяти и устанавливает порог памяти, при достижении которого RabbitMQ блокирует публикацию сообщений, равным 60% от этого значения.

Настройка хранилища

RabbitMQ хранит сообщения и метаданные на постоянном томе, который описывается в секции spec.instance.persistentVolumeClaim:

spec:
  instance:
    persistentVolumeClaim:
      size: 10Gi
      storageClassName: <STORAGE_CLASS_NAME>

Замените <STORAGE_CLASS_NAME> на имя StorageClass в кластере. Если storageClassName не задан, используется StorageClass кластера по умолчанию.

Для хранилища действуют следующие правила:

  • Класс хранения фиксируется при создании тома. Последующее изменение storageClassName не применяется.
  • Размер тома можно только увеличить. StorageClass должен поддерживать расширение томов. Меньшее значение игнорируется.
  • Без секции persistentVolumeClaim модуль не создаёт том, и данные теряются при перезапуске пода.

Том принадлежит объекту Rabbit. При удалении объекта Rabbit удаляются том и все данные RabbitMQ.

Изменение настроек RabbitMQ

Настройки RabbitMQ задаются в секции spec.configuration:

spec:
  configuration:
    maxMessageSize: 16Mi

Параметр maxMessageSize задаёт максимальный размер сообщения. Сообщения большего размера RabbitMQ отклоняет. Параметр можно задать, только если класс указывает его в параметре overridableConfiguration; класс default это разрешает. Остальные настройки RabbitMQ администратор задаёт в классе.

Включение TLS

С TLS RabbitMQ принимает только зашифрованные подключения AMQPS на порту 5671, а порт 5672 закрыт. TLS настраивается в секции spec.tls; без этой секции TLS выключен.

Серверный сертификат должен содержать следующие DNS-имена, где <NAME> — имя объекта Rabbit, <NAMESPACE> — его неймспейс:

  • d8ms-rmq-<NAME>;
  • d8ms-rmq-<NAME>.<NAMESPACE>;
  • d8ms-rmq-<NAME>.<NAMESPACE>.svc;
  • d8ms-rmq-<NAME>.<NAMESPACE>.svc.<CLUSTER_DOMAIN>, где <CLUSTER_DOMAIN> — домен кластера, по умолчанию cluster.local.

Клиенты могут подключаться без клиентского сертификата. Если клиент предъявляет сертификат, RabbitMQ проверяет его по сертификату CA из ca.crt.

Сертификат от cert-manager

В режиме CertManager модуль запрашивает сертификат у cert-manager и включает в него перечисленные выше DNS-имена. Для этого режима нужен модуль cert-manager: включите его, если он выключен. Укажите ClusterIssuer или Issuer из неймспейса объекта Rabbit:

spec:
  tls:
    mode: CertManager
    certManager:
      clusterIssuerName: <CLUSTER_ISSUER_NAME>

Чтобы использовать Issuer, замените clusterIssuerName на issuerName. Issuer должен помещать сертификат CA в ключ ca.crt Secret сертификата. Модуль запускает RabbitMQ после того, как cert-manager выпустит сертификат.

Собственный сертификат

В режиме CustomCertificate RabbitMQ использует сертификаты из Secret в неймспейсе объекта Rabbit:

spec:
  tls:
    mode: CustomCertificate
    customCertificate:
      serverTLSSecret: <TLS_SECRET_NAME>
      serverCASecret: <CA_SECRET_NAME>

Замените плейсхолдеры:

  • <TLS_SECRET_NAME> — Secret типа kubernetes.io/tls с серверным сертификатом в tls.crt и его ключом в tls.key;
  • <CA_SECRET_NAME> — Secret с сертификатом CA в ключе ca.crt.

Состояние сертификата

Секция status.certificate.server объекта Rabbit показывает состояние серверного сертификата:

  • ttl — количество дней до истечения срока действия сертификата;
  • failed — true, если сертификат не удаётся прочитать.

Подключение к RabbitMQ

Для подключения к экземпляру модуль создаёт следующие объекты, где <NAME> — имя объекта Rabbit:

  • Service d8ms-rmq-<NAME> с портом 5672 или с портом 5671, если включён TLS;
  • Secret d8ms-rmq-<NAME>-user-secret с ключами username и password.

Пользователь из Secret имеет полные права на виртуальный хост /. Пароль генерируется при создании объекта Rabbit и не меняется.

Чтобы получить пароль, выполните команду:

d8 k -n <NAMESPACE> get secret d8ms-rmq-<NAME>-user-secret -o jsonpath='{.data.password}' | base64 -d

Приложение в кластере подключается по следующему URI:

amqp://<USERNAME>:<PASSWORD>@d8ms-rmq-<NAME>.<NAMESPACE>.svc:5672/

С TLS используйте схему amqps и порт 5671. Пароль может содержать символы !@#$%^&*: закодируйте его в URI (URL-кодирование).

Проверка статуса

Состояние экземпляра отражается в списке status.conditions объекта Rabbit. Чтобы посмотреть conditions, выполните команду:

d8 k -n <NAMESPACE> get rabbit <NAME> -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

Экземпляр готов, когда все conditions имеют значение True:

Condition Значение при True Причины при False
ConfigurationValid Текущая спецификация объекта прошла проверки класса RulesValidationFailed, ValidationFailed
ScaledToLastValidConfiguration Под RabbitMQ готов и работает с последней валидной конфигурацией ScaleError, NotScaled
Available RabbitMQ принимает подключения NotServing
LastValidConfigurationApplied Последняя валидная конфигурация применена, RabbitMQ доступен. Это итоговый condition Syncing, пока применяются изменения, или <OBJECT>ReconciliationFailed, если модулю не удаётся создать объект Kubernetes

У каждого condition со значением False есть поля reason и message с описанием проблемы.

Если изменение объекта не прошло проверки, RabbitMQ продолжает работать с последней валидной конфигурацией. Эта конфигурация отражается в секции status.lastValidConfiguration.

Диагностика проблем

В этом разделе приведены типичные ошибки, их причины и способы устранения.

Объект отклонён из-за размеров

Модуль отклоняет объект Rabbit, ресурсы которого не соответствуют классу. Сообщение об ошибке содержит один из следующих текстов:

Сообщение Причина Решение
cpu does not fit any of Sizing Policies of the chosen Class cores не попадает в диапазоны политик размеров Выберите cores в пределах диапазона из sizingPolicies класса
memory setting does not fit selected ... Class in range memory.size не попадает в диапазон подходящей политики Выберите memory.size в пределах диапазона; границы указаны в байтах
memory setting does not fit Step memory.size не кратно step Округлите memory.size до значения, кратного step
core fraction does not match array in selected ... Class coreFraction нет в coreFractions Укажите одно из значений coreFractions в той же форме, например "50%"

Объект отклонён из-за настройки

Сообщение restricted to override by administrator означает, что класс не разрешает настройку, изменённую в spec.configuration. Удалите настройку или выберите класс, в котором она указана в overridableConfiguration.

Сообщение Message: <TEXT> означает, что объект не удовлетворяет правилу CEL класса. <TEXT> — сообщение этого правила. Измените объект так, чтобы он удовлетворял правилу.

Под не удаётся разместить

Condition ScaledToLastValidConfiguration с причиной ScaleError означает, что под RabbitMQ не удаётся разместить ни на одном узле. Размещение подов задаёт администратор в классе. Проверьте события пода и обратитесь к администратору:

d8 k -n <NAMESPACE> describe pod d8ms-rmq-<NAME>-0

У объекта нет conditions

Если у нового объекта Rabbit нет conditions, вероятно, класс, на который он ссылается, не существует. При создании такого объекта модуль выводит предупреждение RabbitClass <CLASS_NAME> was not found yet, skipping validation. Проверьте значение spec.rabbitClassName или попросите администратора создать класс.