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 не будет его использовать. Рассмотрим следующие два случая:

Если при запуске пода ANIC ресурс GlobalConfiguration недопустим, ANIC не сможет запуститься и завершит работу с ошибкой.
Если ресурс 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) включает предупреждающее
событие с указанием причины отклонения.