В приложении содержится пошаговая инструкция для Kubernetes-кластера Polymatica ML. Инструкция предназначена для подготовки в кластере IngressClass nginx, через который будут опубликованы Keycloak и сервисы Polymatica ML. Ingress-nginx является инфраструктурной предпосылкой и не устанавливается основным архивом Polymatica ML.
| Компонент | Зафиксированная версия |
|---|---|
| Kubernetes | Kubernetes 1.31.x (проверенная конфигурация: 1.31.6) |
| Helm chart | ingress-nginx 4.15.1 |
| Controller | v1.15.1 |
| NGINX | 1.27.1 |
| Архитектура | linux/amd64 |
| IngressClass | nginx / k8s.io/ingress-nginx |
registry.k8s.io/ingress-nginx/controller:v1.15.1@sha256:594ceea76b01c592858f803f9ff4d2cb40542cae2060410b2c95f75907d659e1 |
Версия 4.15.1 официально совместима с Kubernetes 1.31-1.35.
Community ingress-nginx завершил развитие и не получает новые исправления безопасности. Для текущей версии системы используется финальная совместимая версия v1.15.1. Для следующих релизов необходимо запланировать переход на поддерживаемую реализацию Ingress или Gateway API. |
• Руководство по установке ingress-nginx.
• Таблица совместимости Kubernetes и ingress-nginx.
• Helm chart 4.15.1.
Перед установкой ingress-nginx убедитесь, что выполнены следующие условия:
• Kubernetes-кластер доступен и все рабочие узлы находятся в состоянии Ready.
• На хосте администратора установлены kubectl и Helm 3.
• Контекст kubectl указывает на целевой кластер.
• В кластере отсутствует другая IngressClass с именем nginx.
• Определен способ публикации портов 80 и 443: LoadBalancer или внешний балансировщик перед NodePort.
• DNS-имя Polymatica ML будет направлено на внешний адрес ingress-контроллера.
kubectl version kubectl get nodes -o wide kubectl get ingressclass helm version |
Если IngressClass nginx уже существует, сначала определите ее владельца и версию контроллера. Второй контроллер с тем же именем устанавливать нельзя.
kubectl get ingressclass nginx -o yaml kubectl get pods -A -l app.kubernetes.io/name=ingress-nginx |
| Условия кластера | Рекомендуемая схема |
|---|---|
| Есть облачный LoadBalancer или MetalLB | Service type LoadBalancer. При необходимости указать фиксированный VIP. |
| Нет реализации LoadBalancer | Service type NodePort и внешний L4-балансировщик на порты NodePort. |
| TLS завершается в ingress-nginx | В namespace продукта заранее создается TLS Secret. |
| TLS завершается на внешнем балансировщике | TLS Secret в ingress-nginx не требуется; до backend передается HTTP или повторно зашифрованный трафик. |
Адрес 10.172.164.200 используется только в текущем тестовом кластере Polymatica. В контуре заказчика должен быть выделен собственный VIP или адрес внешнего балансировщика. |
Выберите сценарий в зависимости от наличия доступа в интернет.
curl -fL -o ingress-nginx-4.15.1.tgz \ https://github.com/kubernetes/ingress-nginx/releases/download/helm-chart-4.15.1/ingress-nginx-4.15.1.tgz sha256sum ingress-nginx-4.15.1.tgz |
Ожидаемая контрольная сумма chart:
3eff0bd18151d6e6b1c441463410571443dda1ac78292cb189346628de784f0c |
Скачайте официальный образ строго для linux/amd64:
UPSTREAM_IMAGE='registry.k8s.io/ingress-nginx/controller:v1.15.1@sha256:594ceea76b01c592858f803f9ff4d2cb40542cae2060410b2c95f75907d659e1' docker pull --platform linux/amd64 "$UPSTREAM_IMAGE" docker image inspect "$UPSTREAM_IMAGE" |
Рекомендуемый способ — загрузить образ в registry заказчика, доступный со всех Kubernetes-узлов.
CUSTOMER_REGISTRY='registry.customer.local' TARGET_IMAGE="$CUSTOMER_REGISTRY/ingress-nginx/controller:v1.15.1" docker login "$CUSTOMER_REGISTRY" docker tag "$UPSTREAM_IMAGE" "$TARGET_IMAGE" docker push "$TARGET_IMAGE" |
Проверка образа в registry заказчика:
docker pull --platform linux/amd64 "$TARGET_IMAGE" docker image inspect "$TARGET_IMAGE" |
Прямой адрес registry.k8s.io в values использовать нельзя, если Kubernetes-узлы не имеют доступа в интернет. В таком случае укажите registry заказчика и очистите поле digest, поскольку digest manifest после зеркалирования может отличаться. |
Создайте файл ingress-nginx-values.yaml. Пример ниже соответствует проверенной конфигурации Polymatica ML, но не содержит адресов внутренней инфраструктуры Polymatica.
global: image: registry: registry.k8s.io controller: replicaCount: 1 image: image: ingress-nginx/controller tag: v1.15.1 digest: sha256:594ceea76b01c592858f803f9ff4d2cb40542cae2060410b2c95f75907d659e1 pullPolicy: IfNotPresent ingressClass: nginx ingressClassByName: true ingressClassResource: enabled: true name: nginx default: false controllerValue: k8s.io/ingress-nginx admissionWebhooks: enabled: false config: access-log-path: /var/log/nginx/access.log hsts: "true" hsts-include-subdomains: "true" hsts-max-age: "31536000" worker-processes: "4" use-forwarded-headers: "true" service: type: LoadBalancer externalTrafficPolicy: Local |
Для закрытого контура замените только блок образа:
global: image: registry: registry.customer.local controller: image: image: ingress-nginx/controller tag: v1.15.1 digest: "" pullPolicy: IfNotPresent |
Если кластер поддерживает назначение фиксированного IP для Service type LoadBalancer, добавьте:
controller: service: loadBalancerIP: <INGRESS_VIP> |
Если фиксированный IP назначается аннотацией MetalLB или облачного провайдера, используйте документированные аннотации конкретной платформы вместо loadBalancerIP.
controller: service: type: NodePort externalTrafficPolicy: Local |
В этом варианте внешний балансировщик должен направлять TCP 80/443 на опубликованные NodePort Kubernetes-узлов.
Создайте namespace и установите chart из заранее проверенного файла:
kubectl create namespace ingress-nginx --dry-run=client -o yaml | kubectl apply -f - helm upgrade --install ingress-nginx ./ingress-nginx-4.15.1.tgz \ --namespace ingress-nginx \ --values ingress-nginx-values.yaml \ --wait \ --timeout 10m |
kubectl rollout status deployment/ingress-nginx-controller \ -n ingress-nginx --timeout=10m kubectl get pods -n ingress-nginx -o wide kubectl get service -n ingress-nginx kubectl get endpoints -n ingress-nginx ingress-nginx-controller kubectl get ingressclass nginx -o yaml |
Ожидаемый результат:
• Deployment ingress-nginx-controller успешно завершил rollout.
• Pod контроллера находится в состоянии Running и Ready.
• Service имеет внешний IP или опубликованные NodePort.
• IngressClass nginx содержит controller k8s.io/ingress-nginx
POD=$(kubectl get pods -n ingress-nginx \
-l app.kubernetes.io/component=controller \
-o jsonpath='{.items[0].metadata.name}')
kubectl exec -n ingress-nginx "$POD" -- \
/nginx-ingress-controller --version |
В выводе должна присутствовать версия v1.15.1.
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=200 |
В файле install/offline-install.conf укажите:
INGRESS_CLASS=nginx OFFLINE_BASE_DOMAIN=ml.customer.example OFFLINE_TLS_SECRET=ml-apps-tls |
Создайте DNS-запись для домена Polymatica ML, направленную на внешний IP Service ingress-nginx или на внешний балансировщик перед NodePort.
kubectl get service ingress-nginx-controller -n ingress-nginx |
Если TLS завершается в ingress-nginx, создайте Secret в namespace, куда устанавливается Polymatica ML:
NAMESPACE=offline kubectl create secret tls ml-apps-tls \ --namespace "$NAMESPACE" \ --cert=tls.crt \ --key=tls.key |
Если TLS завершается на внешнем балансировщике, создание Secret определяется принятой схемой прохождения трафика. Сам установщик Polymatica ML не требует наличия Secret на этапе preflight.
NAMESPACE=offline
kubectl get ingress -n "$NAMESPACE"
kubectl get ingress -n "$NAMESPACE" \
-o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.ingressClassName}{"\n"}{end}'
./install/offline-smoke.sh --namespace "$NAMESPACE" |
Все Ingress Polymatica ML должны использовать IngressClass nginx.
| Симптом | Проверка и действие |
|---|---|
| Preflight: IngressClass nginx does not exist | Проверьте kubectl get ingressclass. Убедитесь, что Helm-релиз установлен и ingressClassResource.enabled=true. |
| Pod ImagePullBackOff | Проверьте доступность registry с Kubernetes-узла, имя зеркального образа и imagePullSecret. Для зеркального registry очистите controller.image.digest. |
| Service LoadBalancer остается Pending | В кластере нет реализации LoadBalancer либо не выделен адрес. Настройте MetalLB/облачный LB или используйте NodePort с внешним балансировщиком. |
| Ingress существует, но сайт недоступен | Проверьте DNS, внешний адрес Service, endpoints контроллера, firewall на 80/443 и журналы ingress-nginx-controller. |
| HTTP 404 от ingress-nginx | Проверьте host в Ingress, DNS-запрос и ingressClassName. Запрос должен приходить с ожидаемым Host. |
| Ошибка TLS | Проверьте имя Secret, namespace, содержимое tls.crt/tls.key и соответствие сертификата доменному имени. |
| В логах неверный IP клиента | Проверьте externalTrafficPolicy и настройки внешнего балансировщика. Use-forwarded-headers включен в рекомендуемых values. |
kubectl describe deployment ingress-nginx-controller -n ingress-nginx kubectl describe service ingress-nginx-controller -n ingress-nginx kubectl logs deployment/ingress-nginx-controller -n ingress-nginx --tail=300 kubectl get ingress -A kubectl describe ingress -n <NAMESPACE> <INGRESS_NAME> |
Установка ingress-nginx завершена, когда контроллер Ready, Service доступен снаружи, IngressClass nginx создана, DNS указывает на внешний адрес и тестовый HTTPS/HTTP-запрос достигает нужного Ingress. |
• Chart 4.15.1 проверен по SHA256.
• Используется upstream-образ v1.15.1 либо его точная копия в registry заказчика.
• IngressClass nginx создана один раз и принадлежит установленному контроллеру.
• Определен внешний IP или NodePort и настроен DNS.
• Выбрана и проверена схема TLS.
• В offline-install.conf задано INGRESS_CLASS=nginx.