#Как настроить таймаут Ingress и размер тела Webservice

В этой статье описывается, как настроить три параметра NGINX Ingress, доступные в gitlab.webservice.ingress, когда их следует изменять и как применить тот же подход для других контроллеров Ingress.

Сценарии, в которых это применимо:

• Отправка больших репозиториев, объектов LFS или образов контейнеров завершается ошибкой 413 Request Entity Too Large.
• git clone / git push / импорт проекта для больших репозиториев завершается по таймауту с 502 Bad Gateway примерно через ~10 минут.
• 502 Bad Gateway ненадолго появляется после обновления или перезапуска webservice.

#Общие сведения

GitLab webservice доступен через NGINX Ingress. Встроенная Helm-chart экспонирует три параметра в spec.helmValues.gitlab.webservice.ingress CR GitlabOfficial. Они рендерятся в аннотации NGINX Ingress для объекта Ingress <RELEASE>-webservice-default:

apiVersion: operator.alaudadevops.io/v1alpha1
kind: GitlabOfficial
metadata:
  name: sample
spec:
  helmValues:
    gitlab:
      webservice:
        ingress:
          proxyConnectTimeout: 15    # seconds, -> nginx.ingress.kubernetes.io/proxy-connect-timeout
          proxyReadTimeout: 600      # seconds, -> nginx.ingress.kubernetes.io/proxy-read-timeout
          proxyBodySize: "512m"      # size,    -> nginx.ingress.kubernetes.io/proxy-body-size

Значения по умолчанию подходят для большинства установок. Эти три параметра тесно связаны — для больших репозиториев обычно требуется и больший размер тела, и более длительный таймаут чтения — поэтому их обычно настраивают вместе, а не по одному.

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

• Разрешение на редактирование CR GitlabOfficial (kubectl edit gitlabofficial <NAME> -n <NS>).
• Поля proxyConnectTimeout / proxyReadTimeout / proxyBodySize учитываются только тогда, когда в кластере используется community ingress-nginx controller (kubernetes/ingress-nginx), поскольку chart рендерит их в пространство аннотаций nginx.ingress.kubernetes.io/*. Для любого другого controller см. Настройка других контроллеров Ingress ниже.
• Проверьте каждый участок пути запроса. Если перед собственным Ingress GitLab находится platform-level LB или reverse proxy, те же лимиты нужно увеличить и там — фактический предел определяется минимальным значением во всей цепочке.

#Настройка для больших репозиториев / загрузок (ingress-nginx)

Обычно для установок, которые обслуживают большие репозитории, объекты LFS или трафик container/package registry, одновременно проявляются три симптома, и для них используется одно и то же решение — увеличьте все три параметра вместе:

Рекомендуемая отправная точка для экземпляра GitLab с большими репозиториями / LFS / Registry:

spec:
  helmValues:
    gitlab:
      webservice:
        ingress:
          proxyConnectTimeout: 30      # 15 -> 30; modest bump to absorb pod-restart jitter
          proxyReadTimeout: 1800       # 600 -> 1800; 30 min for large clone/push/import
          proxyBodySize: "5g"          # 512m -> 5g;  fits LFS / registry blobs

Выбирайте значения на основе фактического использования:

proxyConnectTimeout обычно является симптомом, а не настройкой. Кратковременный 502 во время rollout обычно означает, что Pods webservice медленно запускаются или неправильно настроен readiness probe — сначала исправьте это. Увеличивайте значение только до 30–60s, когда в среде действительно медленная TCP-установка, например при сетевом взаимодействии между AZ. Установка больших значений, таких как 600, лишь замаскирует реальные сбои backend и приведет к накоплению worker threads NGINX.

proxyBodySize управляет только уровнем Ingress. Сам GitLab имеет ограничения на уровне приложения, настроенные в Admin Area → Settings → General → Account and limit (max push size, max attachment size, max import size, ...). При необходимости увеличьте и их параллельно.

Совет: Для очень больших операций Git используйте SSH (git@), а не HTTPS. Трафик SSH не проходит через HTTP Ingress и не подпадает под действие этих трех параметров.

#Настройка других контроллеров Ingress

Три верхнеуровневых поля выше только создают аннотации в пространстве имен nginx.ingress.kubernetes.io/* и игнорируются:

• Traefik, HAProxy, Contour, Istio Gateway и другими non-NGINX controller.
• F5 NGINX Inc. nginxinc/kubernetes-ingress — он использует другое пространство аннотаций (nginx.org/*).

Для этих controller задайте эквивалентные аннотации напрямую через gitlab.webservice.ingress.annotations, которые объединяются с отрендеренным объектом Ingress.

Пример для F5 NGINX Inc. (nginx.org/*):

spec:
  helmValues:
    gitlab:
      webservice:
        ingress:
          annotations:
            nginx.org/client-max-body-size: "5g"
            nginx.org/proxy-read-timeout: "1800s"
            nginx.org/proxy-connect-timeout: "30s"

Для Traefik эквивалентом proxyBodySize является ресурс Middleware с buffering.maxRequestBodyBytes, а таймауты настраиваются на уровне IngressRoute / EntryPoint, а не через аннотации на уровне каждого Ingress. Определите эти ресурсы отдельно и при необходимости укажите на них ссылку через traefik.ingress.kubernetes.io/router.middlewares в annotations.

Когда global.ingress.provider установлен в значение, отличное от nginx, аннотации nginx.ingress.kubernetes.io/* не внедряются, но сам ресурс Ingress по-прежнему рендерится — значения из annotations сохраняются. Если выбранный controller вообще не поддерживает аннотации на уровне каждого Ingress для этих ограничений, настройте их на самом controller.

#Проверка примененной конфигурации

После обновления CR и ожидания reconciliation проверьте аннотации на объекте Ingress:

kubectl -n <NAMESPACE> get ingress <RELEASE>-webservice-default \
  -o jsonpath='{.metadata.annotations}' | tr ',' '\n' \
  | grep -E 'body-size|read-timeout|connect-timeout'

Ожидаемый вывод (пример для ingress-nginx):

"nginx.ingress.kubernetes.io/proxy-body-size":"5g"
"nginx.ingress.kubernetes.io/proxy-connect-timeout":"30"
"nginx.ingress.kubernetes.io/proxy-read-timeout":"1800"

Если значения не совпадают:

• Убедитесь, что CR был обновлен в spec.helmValues.gitlab.webservice.ingress (а не в spec.helmValues.nginx-ingress.controller.*, что является другим уровнем).
• Проверьте, что operator успешно выполнил reconciliation: kubectl describe gitlabofficial <NAME> -n <NS>.
• Убедитесь, что upstream Ingress / LB перед собственным Ingress GitLab не применяет более строгий лимит.

#Всегда ли большие значения лучше?

Нет. Каждый параметр имеет свою цену:

• Слишком большой proxyBodySize — NGINX буферизует (или передает потоком) все тело запроса; одна очень большая загрузка может резко увеличить потребление памяти и диска на node Ingress Controller. Устанавливайте значение лишь немного выше реального максимума, а не произвольно большим.
• Слишком большой proxyReadTimeout — медленные или зависшие upstream соединения надолго занимают worker slots NGINX, снижая доступную параллельность для других пользователей. Выбирайте значение, соответствующее вашему крупнейшему допустимому запросу, а не "как можно больше".
• Слишком большой proxyConnectTimeout — скрывает реальные сбои backend (Pods не готовы, проблемы с сетью), ожидая много минут перед возвратом ошибки. Держите его небольшим (15–60s) и устраняйте проблему на стороне backend.

#Справка

• Аннотации NGINX Ingress: https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/
• Аннотации F5 NGINX Inc.: https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/