Внешний доступ к KServe

Раздел по ML-сценариям уточняется. Отдельные шаги и примеры могут быть дополнены. При возникновении вопросов обратитесь к команде платформы «Штурвал».

KServe входит в установку Kubeflow. Из Notebook в том же кластере модель доступна по внутреннему имени сервиса. Шаги этой страницы нужны, только если модель вызывают снаружи — другая система, CI, пользовательский сервис.

Снаружи адрес выглядит как: http://kserve.<commonName>/serving/<неймспейс-профиля>/<имя-модели>/v1/models/<имя-модели>:predict.

Что должно получиться #

1. Knative Serving знает домен кластера и не преобразует тег образа в digest для перечисленных реестров. Если CA реестра отсутствует в доверенном хранилище контроллера Knative, ему монтируется корневой CA реестра.
2. KServe публикует модели по одному хосту и пути /serving/<неймспейс>/<имя>.
3. Внешний nginx принимает kserve.<commonName>, подменяет Host на <commonName> и отдаёт трафик в istio-ingressgateway:80.
4. AuthorizationPolicy разрешает пути inference. Снаружи запрос несёт cookie сессии Kubeflow. Сама политика ограничивает пути, но не проверяет cookie.

Требования #

Ресурсы Kubernetes создавайте в клиентском кластере. Проверочный запрос на шаге 6 выполняйте с внешнего хоста, для которого настраивается доступ.

• установлены kubeflow-step-0 … kubeflow-step-4, режим Авто, состояние Healthy;
• известно <commonName> — status.appliedCustomValues.controller.shturval.commonName у SSC shturval-ingress-controller;
• DNS kserve.<commonName> указывает на Ingress клиентского кластера (тот же, что у kubeflow.<commonName>);
• есть Profile Kubeflow и его неймспейс. Не используйте default и kubeflow-system как рабочую область;
• в реестре есть образ runtime модели (в примере — sklearnserver);
• известен <хост-реестра> — FQDN реестра, откуда кластер тянет этот образ (часто FQDN зеркала).

Подставляйте свои значения:

Куда подставлять <commonName>:

В configDomain и ingressDomain не указывайте kserve.<commonName>: nginx как раз подменяет Host на голый <commonName>, и VirtualService KServe должен совпасть с этим Host.

Шаг 1. Корневой CA зеркала #

Образы моделей кластер скачивает с зеркала. Соединение идёт по HTTPS, поэтому кластер должен доверять сертификату зеркала.

Если сертификат зеркала выпущен удостоверяющим центром, которому контроллер Knative не доверяет, подключите корневой CA зеркала.

Если зеркало и кластер уже используют один и тот же CA, шаг можно пропустить: не создавайте ConfigMap, а блок controller в SSP на шаге 2 удалите.

Запросите корневой сертификат у администратора зеркала. Для диагностики можно получить цепочку сертификатов командой ниже, подставив FQDN зеркала:

echo | openssl s_client -showcerts -servername <хост-зеркала> -connect <хост-зеркала>:443 2>/dev/null

Не определяйте корневой сертификат только по его положению в выводе: сервер может не передать корневой CA. Перед добавлением проверьте subject, issuer и отпечаток сертификата. Сохраните подтверждённый корневой сертификат в файл, например mirror-root-ca.pem.

Неймспейс knative-serving появляется после установки Kubeflow. Создайте в нём ConfigMap с сертификатом.

apiVersion: v1
kind: ConfigMap
metadata:
  name: registry-root-ca
  namespace: knative-serving
data:
  ca-bundle.pem: |
    -----BEGIN CERTIFICATE-----
    <PEM-корневого-CA-зеркала>
    -----END CERTIFICATE-----    

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" -n knative-serving create configmap registry-root-ca \
  --from-file=ca-bundle.pem=<путь>/mirror-root-ca.pem
kubectl --kubeconfig "${KUBECONFIG_CLIENT}" -n knative-serving get configmap registry-root-ca

Шаг 2. SSP для Knative Serving #

SSP задаёт домен кластера, список реестров без проверки тега и (если выполняли шаг 1) том с CA.

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: knative-for-kserve-external
spec:
  patchOrder: 100
  shturvalServiceConfigName: kubeflow-step-1
  customvalues:
    knative-serving1:
      configDomain:
        domains:
          - "<commonName>": {}
      configDeployment:
        extraArgs:
          registries-skipping-tag-resolving: "r.shturval.tech,<хост-реестра>,kind.local,ko.local,dev.local"
      controller:
        caBundle:
          configMapName: registry-root-ca
          key: ca-bundle.pem
          path: ca-bundle.pem
          mountPath: /etc/ssl/custom-certs

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" apply -f - <<'EOF'
apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: knative-for-kserve-external
spec:
  patchOrder: 100
  shturvalServiceConfigName: kubeflow-step-1
  customvalues:
    knative-serving1:
      configDomain:
        domains:
          - "<commonName>": {}
      configDeployment:
        extraArgs:
          registries-skipping-tag-resolving: "r.shturval.tech,<хост-реестра>,kind.local,ko.local,dev.local"
      controller:
        caBundle:
          configMapName: registry-root-ca
          key: ca-bundle.pem
          path: ca-bundle.pem
          mountPath: /etc/ssl/custom-certs
EOF

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get shturvalservicepatch knative-for-kserve-external
kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get ssc kubeflow-step-1

Шаг 3. SSP для KServe #

SSP задаёт pathTemplate и ingressDomain, чтобы к разным моделям был доступ по одному хосту и разным путям. Подставьте <commonName> только в ingressDomain. Остальные поля оставьте как в примере: gateway Istio, класс istio, схема http, путь /serving/{{ "{{ .Namespace }}" }}/{{ "{{ .Name }}" }}.

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: kserve-path-template
spec:
  patchOrder: 100
  shturvalServiceConfigName: kubeflow-step-2
  customvalues:
    kserve:
      inferenceserviceConfig:
        ingress: |-
          {
              "enableGatewayApi": false,
              "kserveIngressGateway": "istio-system/istio-ingressgateway",
              "ingressGateway" : "kubeflow/kubeflow-gateway",
              "localGateway" : "knative-serving/knative-local-gateway",
              "localGatewayService" : "knative-local-gateway.istio-system.svc.cluster.local",
              "ingressDomain"  : "<commonName>",
              "ingressClassName" : "istio",
              "domainTemplate": "{{ "{{ .Name }}-{{ .Namespace }}.{{ .IngressDomain }}" }}",
              "pathTemplate": "{{ "/serving/{{ .Namespace }}/{{ .Name }}" }}",
              "urlScheme": "http",
              "disableIstioVirtualHost": false,
              "disableIngressCreation": false
          }          

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" apply -f - <<'EOF'
apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: kserve-path-template
spec:
  patchOrder: 100
  shturvalServiceConfigName: kubeflow-step-2
  customvalues:
    kserve:
      inferenceserviceConfig:
        ingress: |-
          {
              "enableGatewayApi": false,
              "kserveIngressGateway": "istio-system/istio-ingressgateway",
              "ingressGateway" : "kubeflow/kubeflow-gateway",
              "localGateway" : "knative-serving/knative-local-gateway",
              "localGatewayService" : "knative-local-gateway.istio-system.svc.cluster.local",
              "ingressDomain"  : "<commonName>",
              "ingressClassName" : "istio",
              "domainTemplate": "{{ "{{ .Name }}-{{ .Namespace }}.{{ .IngressDomain }}" }}",
              "pathTemplate": "{{ "/serving/{{ .Namespace }}/{{ .Name }}" }}",
              "urlScheme": "http",
              "disableIstioVirtualHost": false,
              "disableIngressCreation": false
          }
EOF

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get shturvalservicepatch kserve-path-template
kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get ssc kubeflow-step-2

Шаг 4. Ingress и AuthorizationPolicy #

Два объекта в неймспейсе istio-system:

• Ingress kserve-external — внешняя точка входа nginx на хост kserve.<commonName>;
• AuthorizationPolicy kserve-inference-access — разрешает на подах модели служебные пути inference.

В примере внешний Ingress без TLS, схема http. UI Kubeflow при этом остаётся на https://kubeflow.<commonName>/.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kserve-external
  namespace: istio-system
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/upstream-vhost: "<commonName>"
spec:
  ingressClassName: nginx
  rules:
  - host: kserve.<commonName>
    http:
      paths:
      - path: /serving/
        pathType: Prefix
        backend:
          service:
            name: istio-ingressgateway
            port:
              number: 80
---
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: kserve-inference-access
  namespace: istio-system
  labels:
    app.kubernetes.io/part-of: kserve-integration
spec:
  action: ALLOW
  rules:
  - to:
    - operation:
        paths:
        - /v1/models/*
        - /v2/models/*
        - /v2/health/*

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" apply -f - <<'EOF'
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kserve-external
  namespace: istio-system
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/upstream-vhost: "<commonName>"
spec:
  ingressClassName: nginx
  rules:
  - host: kserve.<commonName>
    http:
      paths:
      - path: /serving/
        pathType: Prefix
        backend:
          service:
            name: istio-ingressgateway
            port:
              number: 80
---
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: kserve-inference-access
  namespace: istio-system
  labels:
    app.kubernetes.io/part-of: kserve-integration
spec:
  action: ALLOW
  rules:
  - to:
    - operation:
        paths:
        - /v1/models/*
        - /v2/models/*
        - /v2/health/*
EOF

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get ingress kserve-external -n istio-system
kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get authorizationpolicy kserve-inference-access -n istio-system

Шаг 5. Тестовая модель #

Создайте InferenceService в неймспейсе Profile. minReplicas: 1 — чтобы ревизия не ушла в ноль до проверки. Образ runtime возьмите из своего реестра.

Укажите <URI-модели> — адрес совместимого артефакта модели в доступном кластеру хранилище. Образ среды выполнения задаётся отдельно в поле image.

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: sklearn-iris
  namespace: <неймспейс-профиля>
spec:
  predictor:
    minReplicas: 1
    sklearn:
      image: <хост-реестра>/kubeflow/kserve/sklearnserver:<тег>
      storageUri: "<URI-модели>"
      resources:
        requests:
          cpu: 50m
          memory: 128Mi
        limits:
          cpu: 200m
          memory: 256Mi

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" apply -f - <<'EOF'
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: sklearn-iris
  namespace: <неймспейс-профиля>
spec:
  predictor:
    minReplicas: 1
    sklearn:
      image: <хост-реестра>/kubeflow/kserve/sklearnserver:<тег>
      storageUri: "<URI-модели>"
      resources:
        requests:
          cpu: 50m
          memory: 128Mi
        limits:
          cpu: 200m
          memory: 256Mi
EOF

kubectl --kubeconfig "${KUBECONFIG_CLIENT}" get inferenceservice sklearn-iris -n <неймспейс-профиля> -w

Шаг 6. Проверьте внешний вызов #

Запрос к модели — это POST, а не открытие адреса в браузере. Cookie сессии выдаёт oauth2-proxy после входа в UI Kubeflow.

1. В браузере откройте https://kubeflow.<commonName>/ и войдите.
2. Откройте инструменты разработчика → Cookies (Chrome: Application → Cookies, Firefox: Storage → Cookies) для хоста kubeflow.<commonName>.
3. Скопируйте значение cookie oauth2_proxy_kubeflow.

export COOKIE='oauth2_proxy_kubeflow=<значение-cookie>'

curl -sS -D - -X POST \
  -H "Cookie: ${COOKIE}" \
  -H 'Content-Type: application/json' \
  -d '{"instances": [[6.8, 2.8, 4.8, 1.4]]}' \
  "http://kserve.<commonName>/serving/<неймспейс-профиля>/sklearn-iris/v1/models/sklearn-iris:predict"

Ожидается HTTP 200 и поле predictions в теле ответа. Значение зависит от модели, указанной в <URI-модели>.

Если ответа нет:

Связанные страницы:

• Установка Kubeflow
• Как управлять CustomValues сервисов
• Профили Kubeflow
• Устранение неполадок