<a id="globalconfiguration-resource"></a>

# GlobalConfiguration

Ресурс GlobalConfiguration позволяет вам определить глобальные параметры
конфигурации ANIC. Он реализован как [пользовательский ресурс](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

Ресурс поддерживает настройку прослушивателей для балансировки нагрузки TCP и
UDP. Прослушиватели требуются [ресурсам TransportServer](https://angie.software//anic/docs/configuration/transportserver-resource.md#transportserver-resource).

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

При установке ANIC с манифестами
необходимо указать ссылку на ресурс GlobalConfiguration в аргументе командной
строки [-global-configuration](https://angie.software//anic/docs/configuration/command-line-arguments.md#global-configuration-string).
Для ANIC требуется только один ресурс GlobalConfiguration.

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

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

```yaml
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[ ]](#globconf-listener) | Нет           |

<a id="globconf-listener"></a>

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

Прослушиватель определяет комбинацию протокола и порта, которые Angie будет
использовать при приеме трафика для [TransportServer](https://angie.software//anic/docs/configuration/transportserver-resource.md#transportserver-resource):

```yaml
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`:

```default
$ kubectl apply -f global-configuration.yaml

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

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

```default
$ 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`:
  ```default
  $ 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:
  ```default
  $ 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
   начнет его использовать.

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

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

```default
$ 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, вы получите:

```default
   $ 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) включает предупреждающее
событие с указанием причины отклонения.
```