В приложении содержится пошаговая инструкция для Kubernetes-кластера Polymatica ML. Инструкция предназначена для подготовки в кластере IngressClass nginx, через который будут опубликованы Keycloak и сервисы Polymatica ML. Ingress-nginx является инфраструктурной предпосылкой и не устанавливается основным архивом Polymatica ML.

Официальный публичный образ

registry.k8s.io/ingress-nginx/controller:v1.15.1@sha256:594ceea76b01c592858f803f9ff4d2cb40542cae2060410b2c95f75907d659e1

Версия 4.15.1 официально совместима с Kubernetes 1.31-1.35. 

Официальные источники

• Руководство по установке 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

Выбор схемы публикации

Подготовка файлов

Выберите сценарий в зависимости от наличия доступа в интернет.

Подготовка на хосте с интернетом

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 закрытого контура

Рекомендуемый способ — загрузить образ в 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"

Конфигурация Helm

Создайте файл 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

Фиксированный VIP

Если кластер поддерживает назначение фиксированного IP для Service type LoadBalancer, добавьте:

controller:
service:
loadBalancerIP: <INGRESS_VIP>

Если фиксированный IP назначается аннотацией MetalLB или облачного провайдера, используйте документированные аннотации конкретной платформы вместо loadBalancerIP.

Вариант NodePort

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

Подключение Polymatica ML

В файле install/offline-install.conf укажите:

INGRESS_CLASS=nginx
OFFLINE_BASE_DOMAIN=ml.customer.example
OFFLINE_TLS_SECRET=ml-apps-tls

DNS

Создайте DNS-запись для домена Polymatica ML, направленную на внешний IP Service ingress-nginx или на внешний балансировщик перед NodePort.

kubectl get service ingress-nginx-controller -n ingress-nginx

TLS

Если 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.

Типовые проблемы

Диагностические команды

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>

Контрольный список

• Chart 4.15.1 проверен по SHA256.
• Используется upstream-образ v1.15.1 либо его точная копия в registry заказчика.
• IngressClass nginx создана один раз и принадлежит установленному контроллеру.
• Определен внешний IP или NodePort и настроен DNS.
• Выбрана и проверена схема TLS.
• В offline-install.conf задано INGRESS_CLASS=nginx.