Расширенные конфигурации контроллера входящего трафика NGINX и входящего трафика с надстройкой маршрутизации приложений для службы Azure Kubernetes (AKS)

Свойства конфигурации для контроллеров входящего трафика NGINX

Надстройка маршрутизации приложений использует пользовательское определение ресурсов Kubernetes (CRD), называемое NginxIngressController, для настройки контроллеров входящего трафика NGINX. Вы можете создать дополнительные контроллеры входящего трафика или изменить существующие конфигурации.

В следующей таблице перечислены свойства, которые можно задать для настройки NginxIngressController:

Управление конфигурацией контроллера входящего трафика NGINX по умолчанию

При включении надстройки маршрутизации приложений NGINX создается контроллер входящего трафика, который называется default в app-routing-namespace, настроенном с общедоступным балансировщиком нагрузки Azure. Этот контроллер входящего трафика использует имя webapprouting.kubernetes.azure.comкласса входящего трафика.

Вы также можете контролировать, получает ли настройка по умолчанию общедоступный или внутренний IP-адрес, либо вовсе не создается при включении надстройки.

Возможные варианты конфигурации:

• None: контроллер входящего трафика NGINX по умолчанию не создается и не удаляется, если он уже существует. При необходимости необходимо вручную удалить настраиваемый ресурс по умолчанию NginxIngressController .
• Internal: контроллер входящего трафика NGINX по умолчанию создается с внутренней подсистемой балансировки нагрузки. Изменения примечаний в пользовательском ресурсе NginxIngressController, которые делают его внешним, перезаписываются.
• External: контроллер входящего трафика NGINX по умолчанию, созданный с внешним балансировщиком нагрузки. Все изменения примечаний в пользовательском NginxIngressController ресурсе, чтобы сделать его внутренним, перезаписываются.
• AnnotationControlled (по умолчанию): контроллер входящего трафика NGINX по умолчанию создается с внешним балансировщиком нагрузки. Вы можете изменить ресурс по умолчанию NginxIngressController, чтобы задать аннотации для балансировщика нагрузки.

Управление конфигурацией контроллера входящего трафика по умолчанию в новом кластере

Обновление конфигурации контроллера входящего трафика по умолчанию в существующем кластере

Создание другого общедоступного контроллера входящего трафика NGINX

1. Скопируйте следующий манифест YAML в новый файл с именем nginx-public-controller.yaml и сохраните его на локальном компьютере.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-public
   spec:
     ingressClassName: nginx-public
     controllerNamePrefix: nginx-public
   

2. Создайте ресурсы контроллера входящего трафика NGINX с помощью kubectl apply команды.

   kubectl apply -f nginx-public-controller.yaml
   

   В следующем примере выходных данных показан созданный ресурс:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
   

Создание внутреннего контроллера входящего трафика NGINX с частным IP-адресом

1. Скопируйте следующий манифест YAML в новый файл с именем nginx-internal-controller.yaml и сохраните его на локальном компьютере.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-internal
   spec:
     ingressClassName: nginx-internal
     controllerNamePrefix: nginx-internal
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-load-balancer-internal: "true"
   

2. Создайте ресурсы контроллера входящего трафика NGINX с помощью kubectl apply команды.

   kubectl apply -f nginx-internal-controller.yaml
   

   В следующем примере выходных данных показан созданный ресурс:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
   

Создание контроллера входящего трафика NGINX со статическим IP-адресом

1. Создайте группу ресурсов Azure с помощью az group create команды.

   az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION
   

2. Создайте статический общедоступный IP-адрес с помощью az network public ip create команды.

   az network public-ip create \
     --resource-group $NETWORK_RESOURCE_GROUP \
     --name $PUBLIC_IP_NAME \
     --sku Standard \
     --allocation-method static
   

   Примечание.

   Если вы используете балансировщик нагрузки SKU уровня "Базовый" в кластере AKS, используйте Basic для параметра --sku, когда определяете общедоступный IP-адрес. Только Basic IP-адреса SKU работают с подсистемой балансировки нагрузки SKU уровня "Базовый ", а только Standard IP-адреса SKU уровня "Стандартный" работают с подсистемами балансировки нагрузки SKU уровня "Стандартный ".

3. Убедитесь, что удостоверение кластера, используемое кластером AKS, имеет делегированные разрешения группе ресурсов общедоступного IP-адреса с помощью команды az role assignment create.

   CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
   RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --query id -o tsv)
   az role assignment create \
     --assignee ${CLIENT_ID} \
     --role "Network Contributor" \
     --scope ${RG_SCOPE}
   

4. Скопируйте следующий манифест YAML в новый файл с именем nginx-staticip-controller.yaml и сохраните его на локальном компьютере.

   Примечание.

   Можно использовать service.beta.kubernetes.io/azure-pip-name для общедоступного IP-имени или service.beta.kubernetes.io/azure-load-balancer-ipv4 использовать для IPv4-адреса и service.beta.kubernetes.io/azure-load-balancer-ipv6 для IPv6-адреса, как показано в примере YAML. Добавление аннотации service.beta.kubernetes.io/azure-pip-name гарантирует наиболее эффективное создание балансировщика нагрузки и настоятельно рекомендуется, чтобы избежать потенциального регулирования.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-static
   spec:
     ingressClassName: nginx-static
     controllerNamePrefix: nginx-static
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-pip-name: "$PUBLIC_IP_NAME"
       service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"
   

5. Создайте ресурсы контроллера входящего трафика NGINX с помощью kubectl apply команды.

   kubectl apply -f nginx-staticip-controller.yaml
   

   В следующем примере выходных данных показан созданный ресурс:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
   

Убедитесь, что контроллер входящего трафика создан

• Проверьте состояние контроллера входящего трафика NGINX с помощью kubectl get nginxingresscontroller команды.

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

  В следующем примере выходных данных показан созданный ресурс. Для доступности контроллера может потребоваться несколько минут:

  NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
  nginx-public   nginx-public   nginx                  True
  

Просмотр условий контроллера входящего трафика

• Просмотрите условия контроллера входящего трафика для устранения неполадок с помощью kubectl get nginxingresscontroller команды.

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'
  

  В следующем примере выходных данных показаны условия работоспособного контроллера входящего трафика:

  2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
  2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
  2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
  2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed
  

Использование контроллера входящего трафика в сетевом входе

1. Скопируйте следующий манифест YAML в новый файл с именем ingress.yaml и сохраните его на локальном компьютере.

   Примечание.

   Обновите <HostName> на имя вашего узла DNS. Тот <IngressClassName>, который вы определили при создании NginxIngressController.

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: aks-helloworld
     namespace: hello-web-app-routing
   spec:
     ingressClassName: <IngressClassName>
     rules:
     - host: <HostName>
       http:
         paths:
         - backend:
             service:
               name: aks-helloworld
               port:
                 number: 80
           path: /
           pathType: Prefix
   

2. Создайте ресурсы кластера с помощью kubectl apply команды.

   kubectl apply -f ingress.yaml --namespace hello-web-app-routing
   

   В следующем примере выходных данных показан созданный ресурс:

   ingress.networking.k8s.io/aks-helloworld created
   

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

• Убедитесь, что управляемый вход был создан с помощью команды kubectl get ingress.

  kubectl get ingress --namespace hello-web-app-routing
  

  Выходные данные должны выглядеть примерно так:

  NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
  aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m
  

Удаление контроллеров входящего трафика

• Удалите контроллер входящего трафика NGINX с помощью kubectl delete nginxingresscontroller команды.

  kubectl delete nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

Настройка ресурса входа с помощью аннотаций

Контроллер входящего трафика NGINX поддерживает добавление заметок в определенные объекты входящего трафика для настройки их поведения.

Вы можете аннотировать объект Ingress, добавив соответствующую аннотацию в metadata.annotations поле.

В следующих разделах приведены примеры распространенных конфигураций. Полный список см. в документации по аннотациям ingress для NGINX.

Настраиваемый максимальный размер тела

Для NGINX ошибка 413 возвращается клиенту, когда размер запроса превышает максимальный допустимый размер текста запроса клиента. Чтобы переопределить значение по умолчанию, используйте заметку:

nginx.ingress.kubernetes.io/proxy-body-size: 4m

Вот пример конфигурации Ingress с использованием этой аннотации:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Время ожидания пользовательского подключения

Вы можете изменить таймаут, в течение которого контроллер входящего трафика NGINX выдерживает паузу перед закрытием соединения с рабочей нагрузкой. Все значения времени ожидания являются безразмерными и выражены в секундах. Чтобы переопределить время ожидания по умолчанию, используйте следующую заметку, чтобы задать допустимое время ожидания чтения прокси-сервера в 120 секунд:

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

Просмотрите пользовательские тайм-ауты для других параметров конфигурации.

Вот пример конфигурации Ingress с использованием этой аннотации:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Протокол серверной части

Контроллер входящего трафика NGINX используется HTTP для доступа к службам по умолчанию. Чтобы настроить альтернативные внутренние протоколы, например HTTPS или GRPC, используйте одну из следующих заметок:

# HTTPS annotation
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

# GRPC annotation
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

Просмотрите внутренние протоколы для других параметров конфигурации.

Вот пример конфигурации Ingress с использованием этой аннотации:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Общий доступ к ресурсам между источниками (CORS)

Чтобы включить общий доступ к ресурсам между источниками (CORS) в правиле Ingress, используйте следующую аннотацию:

nginx.ingress.kubernetes.io/enable-cors: "true"

Проверьте включение CORS для других параметров конфигурации.

Вот пример конфигурации Ingress с использованием этой аннотации:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Отключите перенаправление SSL

Контроллер перенаправляет (308) на HTTPS, если протокол TLS включен для входящего трафика по умолчанию. Чтобы отключить эту функцию для определенных ресурсов входящего трафика, используйте следующую заметку:

nginx.ingress.kubernetes.io/ssl-redirect: "false"

Просмотрите вариант принудительного применения HTTPS с помощью серверного перенаправления для других параметров конфигурации.

Вот пример конфигурации Ingress с использованием этой аннотации:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Переопределение URL-адресов

В некоторых сценариях предоставленный URL-адрес в серверной службе отличается от указанного пути в правиле входящего трафика. Без перезаписи любого запроса возвращается значение 404. Эта конфигурация полезна с маршрутизацией на основе пути , где можно обслуживать два разных веб-приложения в одном домене. Вы можете задать путь, ожидаемый службой, с помощью следующей заметки:

nginx.ingress.kubernetes.io/rewrite-target: /$2

Вот пример конфигурации Ingress с использованием этой аннотации:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

Обновление пути проверки работоспособности NGINX

Путь пробы работоспособности по умолчанию для Azure Load Balancer, связанного с контроллером входящего трафика NGINX, должен иметь значение "/healthz". Чтобы убедиться в правильности проверок работоспособности, убедитесь, что служба контроллера входа имеет следующую аннотацию:

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Если вы используете Helm для управления контроллером NGINX для входящего трафика, вы можете определить аннотацию пробы работоспособности Azure Load Balancer в файле параметров и применить её при обновлении.

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Эта конфигурация помогает поддерживать доступность службы и избежать непредвиденных сбоев трафика во время обновления.