GlobalConfiguration#

Ресурс GlobalConfiguration позволяет вам определить глобальные параметры конфигурации ANIC. Он реализован как пользовательский ресурс.

Ресурс поддерживает настройку прослушивателей для балансировки нагрузки TCP и UDP. Прослушиватели требуются ресурсам TransportServer.

Предварительные требования#

При установке ANIC с манифестами необходимо указать ссылку на ресурс GlobalConfiguration в аргументе командной строки -global-configuration. Для ANIC требуется только один ресурс GlobalConfiguration.

Спецификация GlobalConfiguration#

Ресурс GlobalConfiguration определяет глобальные параметры конфигурации ANIC. Ниже приведен пример:

apiVersion: k8s.angie.software/v1alpha1
kind: GlobalConfiguration
metadata:
  name: angie-configuration
  namespace: angie-ingress
spec:
  listeners:
  - name: dns-udp
    port: 5353
    protocol: UDP
  - name: dns-tcp
    port: 5353
    protocol: TCP

Поле

Описание

Тип

Обязательно

listeners

Список прослушивателей.

[]listener

Нет

Прослушиватель#

Прослушиватель определяет комбинацию протокола и порта, которые Angie будет использовать при приеме трафика для TransportServer:

name: dns-tcp
port: 5353
protocol: TCP

Поле

Описание

Тип

Обязательно

name

Имя прослушивателя. Это должна быть допустимая метка DNS, как определено в RFC 1035. Например, допустимы значения hello и listener-123. Имя должно быть уникальным среди всех прослушивателей. Имя tls-passthrough зарезервировано для встроенного прослушивателя TLS Passthrough и не может быть использовано.

string

Да

port

Порт прослушивателя. Порт должен находиться в диапазоне 1..65535 со следующими исключениями: 80, 443, порт [статуса](/angie-ingress-controller/logging-and-monitoring/status-page). Комбинация порта и протокола должна быть уникальна среди всех прослушивателей.

int

Да

protocol

Протокол прослушивателя. Поддерживаемые значения: TCP и UDP.

string

Да

Использование GlobalConfiguration#

Вы можете использовать обычные команды kubectl для работы с ресурсом GlobalConfiguration.

Например, следующая команда создает ресурс GlobalConfiguration, определенный в global-configuration.yaml с именем angie-configuration:

$ kubectl apply -f global-configuration.yaml

    globalconfiguration.k8s.angie.software/angie-configuration created

Предполагая, что пространство имен ресурса называется angie-ingress, вы можете получить ресурс, запустив:

$ kubectl get globalconfiguration angie-configuration -n angie-ingress

    NAME                  AGE
    angie-configuration   13s

В kubectl get и подобных командах также можно использовать короткое имя gc вместо globalconfiguration.

Валидация#

Для ресурса GlobalConfiguration доступны два типа валидации:

  • Структурная валидация с помощью kubectl и сервера Kubernetes API.

  • Всесторонняя валидация с помощью ANIC.

Структурная валидация#

Пользовательское определение ресурса для GlobalConfiguration включает структурную схему OpenAPI, которая описывает тип каждого поля ресурса.

Если вы попытаетесь создать (или обновить) ресурс с нарушением структурной схемы (например, используете строковое значение для поля порта прослушивателя), kubectl и сервер Kubernetes API отклонят такой ресурс:

  • Пример проверки kubectl:

    $ kubectl apply -f global-configuration.yaml
    
        error: error validating "global-configuration.yaml": error validating
        data: ValidationError(GlobalConfiguration.spec.listeners[0].port):
        invalid type for
        software.angie.k8s.v1alpha1.GlobalConfiguration.spec.listeners.port:
        got "string", expected "integer"; if you choose to ignore these
        errors, turn validation off with --validate=false
    
  • Пример проверки сервера API Kubernetes:

    $ kubectl apply -f global-configuration.yaml --validate=false
    
        The GlobalConfiguration "angie-configuration" is invalid: []: Invalid
        value: map[string]interface {}{ ... }: validation failure list:
        spec.listeners.port in body must be of type integer: "string"
    

Если ресурс не отклонен (то есть не нарушает структурную схему), ANIC проверит его дополнительно.

Всесторонняя валидация#

ANIC проверяет поля ресурса GlobalConfiguration. Если ресурс недопустим, ANIC не будет его использовать. Рассмотрим следующие два случая:

  1. Если при запуске пода ANIC ресурс GlobalConfiguration недопустим, ANIC не сможет запуститься и завершит работу с ошибкой.

  2. Если ресурс GlobalConfiguration становится недействительным, когда ANIC запущен, то ANIC проигнорирует новую версию. Он сообщит об ошибке и продолжит использовать предыдущую версию. Когда ресурс снова станет действительным, ANIC начнет его использовать.

Примечание

Если ресурс GlobalConfiguration был удален во время работы ANIC, тот продолжит использовать предыдущую версию ресурса.

Вы можете проверить, успешно ли ANIC применил конфигурацию для GlobalConfiguration. Для нашего ресурса GlobalConfiguration angie-configuration мы можем запустить:

$ kubectl describe gc angie-configuration -n angie-ingress

    . . .
    Events:
      Type     Reason    Age   From                      Message


      Normal   Updated   11s   angie-ingress-controller  GlobalConfiguration
      angie-ingress/angie-configuration was updated

Обратите внимание, что раздел "События" (Events) включает событие Normal с причиной Updated, которое информирует нас о том, что конфигурация была успешно применена.

Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст событие Rejected. Например, если вы создадите ресурс GlobalConfiguration angie-configuration с несколькими прослушивателями, для которых задан один и тот же протокол UDP и порт 53, вы получите:

   $ kubectl describe gc angie-configuration -n angie-ingress

       . . .
       Events:
        Type     Reason    Age   From                      Message


       Normal    Updated   55s   angie-ingress-controller  GlobalConfiguration
       angie-ingress/angie-configuration was updated

       Warning   Rejected  6s    angie-ingress-controller  GlobalConfiguration
       angie-ingress/angie-configuration is invalid and was rejected:
       spec.listeners: Duplicate value: "Duplicated port/protocol combination
       53/UDP"


Обратите внимание, что раздел "События" (Events) включает предупреждающее
событие с указанием причины отклонения.