KNIME Documentation

Ingress-NGINX Deprecation and Migration to Istio ​

KNIME Business Hub 1.18.0

With KNIME Business Hub 1.18.0, the ingress approach changes from Ingress-NGINX (deprecated) to Istio as the ingress controller. This can simplify networking but may require changes to your configuration and/or infrastructure during upgrade.

Overview ​

  • What changed: Ingress is now fulfilled via the Istio Ingress Gateway.
  • Impact: Depending on how your environment is set up (delivery method, TLS termination, load balancers, DNS), you may need to update configuration and possibly infrastructure when upgrading.

How to Prepare for the Upgrade ​

To minimize risk:

  • Upgrade successfully to 1.17.3 before attempting 1.18.0.
  • Plan a maintenance window with enough time for troubleshooting.
  • Perform the upgrade in a lower environment first.
  • Ensure you have a clear plan of action before beginning.
  • Ensure you have verified backups.
    • For kURL environments, VM-level backups provide an additional safety net on top of Velero.

Recommended participants for the upgrade window:

  • Your IT / infrastructure team
  • A networking expert (if available)
  • An experienced Kubernetes administrator

Key Configuration Considerations ​

ArgoCD vs. Replicated (KOTS) ​

  • ArgoCD: You will need to update your local-values.yaml configuration.
  • Replicated (KOTS): Some configuration options may require review depending on your setup.

Service URL updates ​

Some configurations refer to the ingress service URL. You may need to update references from:

text
ingress-nginx-controller.knime.svc.cluster.local

to:

text
istio-ingressgateway.istio-system.svc.cluster.local

TLS behavior ​

If TLS is enabled—regardless of where it is terminated—it must be enabled in the relevant configuration (Replicated/KOTS or ArgoCD values).

Node port defaults (Replicated) ​

Default exposed node ports have changed:

  • kURL clusters should remain 80/443
  • For existing clusters, defaults are 30080/30443

This is intended to improve compatibility with Kubernetes distributions that block low-level ports.

A setting exists to customize these exposed node ports in the Networking: Istio section.

Load balancer and DNS risks ​

If your environment previously used an ingress-nginx-controller Service of type LoadBalancer, that load balancer may be deprovisioned when the service is removed. In that case, DNS and routing may need updates.

Questions to Answer Before Upgrading ​

  • Is TLS configured for this installation?
  • If yes, where is TLS terminated?
  • Is the ingress controller currently managed by KNIME or by your organization?
  • Which ingress controller is currently used (e.g., Ingress-NGINX, Traefik)?
  • Does the ingress-nginx-controller service exist? If so:
    • What type is it (ClusterIP, NodePort, LoadBalancer)?
  • If you use an external load balancer:
    • Was it created automatically, manually, or via Terraform?
    • Are you ready to update it if needed?
  • Are you ready to update DNS records if needed?
  • Do you have advanced networking requirements?

Upgrade Scenarios ​

INFO

The configuration required for your environment may differ from the examples below.

ArgoCD ​

  • The values schema changed significantly for the knime-hub-infrastructure chart.
  • It is recommended and preferred for load balancers to be configured manually instead of using a LoadBalancer Service type to provision them automatically. Removing such a service can cause deletion of the load balancer and require updates to DNS and routing rules.
  • To reduce repetition, align your ArgoCD values with the equivalent settings described in the Replicated scenarios below.

Example snippet:

yaml
knime-hub-infrastructure:
  overrides:
    ingress:
      enabled: true
      class:
        enabled: true
        name: istio
        controller: istio.io/ingress-controller
      service:
        URL: istio-ingressgateway.istio-system.svc.cluster.local
        httpPort: 80
        httpsPort: 443
      gateway:
        enabled: true
        httpsRedirectEnabled: false
        tlsTermination:
          enabled: false
          mode: SIMPLE
          secretName: business-hub-certificate
    istio_outbound_redirect:
      enabled: false

Istio as ingress controller with TLS termination at an external load balancer ​

This scenario uses the KNIME deployment of Istio, while TLS is terminated outside the cluster.

Replicated (KOTS) ​

  • TLS is enabled.
  • TLS certificate configuration is set to Handled by the External Load Balancer.
  • The CoreDNS updater job option is disabled.
  • Ensure CoreDNS rewrites are removed from the configmap and CoreDNS pods are restarted (this does not happen automatically).

Istio as ingress controller with TLS termination at the Istio Ingress Gateway ​

This scenario is common when DNS records point directly to a compute instance (or equivalent).

Replicated (KOTS) ​

  • TLS is enabled and the certificate is configured.
  • The Istio TLS secret option is enabled to ensure the TLS secret exists in the Istio namespace.
  • CoreDNS updater job is enabled to keep traffic in-cluster.
  • HTTP → HTTPS redirect is enabled.

Customer-provided ingress controller routed to Istio Ingress Gateway ​

In this scenario, you run your own ingress controller and route traffic to the Istio Ingress Gateway on port 443.

Example snippet:

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: knime-business-hub-ingress
  namespace: istio-system
spec:
  ingressClassName: <REPLACE_WITH_YOUR_INGRESS_CLASS>
  rules:
    - host: hub.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: istio-ingressgateway
                port:
                  number: 443
    - host: "*.hub.example.com"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: istio-ingressgateway
                port:
                  number: 443

Customer-provided Istio ​

Known requirements:

  • Istio must be installed and healthy, using a version supported for your KNIME Business Hub release (the default version for KBH 1.18.0 is Istio v1.28.3).
  • The Istio Ingress Gateway must be deployed (the istio-ingressgateway pod and service exist).
  • The gateway may be deployed to istio-system or to the primary installation namespace (required for OpenShift).
  • A Gateway resource must exist and match your TLS setup.

Example (TLS enabled, gateway terminates TLS):

yaml
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: hub-api-gateway
  namespace: knime
spec:
  selector:
    istio: ingressgateway
  servers:
    - hosts:
        - hub.example.com
        - apps.hub.example.com
        - api.hub.example.com
        - auth.hub.example.com
        - storage.hub.example.com
        - ws.hub.example.com
      port:
        name: http
        number: 80
        protocol: HTTP
      tls:
        httpsRedirect: true
    - hosts:
        - hub.example.com
        - apps.hub.example.com
        - api.hub.example.com
        - auth.hub.example.com
        - storage.hub.example.com
        - ws.hub.example.com
        - registry.hub.example.com
      port:
        name: https
        number: 443
        protocol: HTTPS
      tls:
        credentialName: business-hub-certificate
        mode: SIMPLE

OpenShift ​

  • The customer must provide their own Istio installation.
  • The Istio Ingress Gateway chart should be deployed in the primary installation namespace (for example, knime) rather than istio-system.
  • All relevant service URL configuration options should be updated accordingly.
  • In ArgoCD, the global global.namespaces.istio setting and the knime-hub-infrastructure ingress settings require review.

Post-Upgrade Checklist ​

After upgrading, verify the following:

  1. Log into KNIME Business Hub.
  2. Upload and download workflows.
  3. Create secrets and app passwords.
  4. Execute workflows, including those with Data Apps.
  5. Verify the certificate shows as secure in the browser.
  6. Inspect running jobs to verify WebSocket connectivity.

Troubleshooting ​

Troubleshooting Questions During Upgrade ​

  • Is Istio installed? Who installed it (KNIME or your organization)?
  • Does the istio-ingressgateway service and pod exist?
    • What type is the service (ClusterIP, NodePort, LoadBalancer)?
    • Which namespace is it in?
  • Is TLS configured on the Istio Gateway resource?
  • If TLS termination happens in-cluster:
    • Does the TLS secret (business-hub-certificate by default) exist in the same namespace as the Istio Gateway?
  • Is HTTP → HTTPS redirection enabled in the Istio Gateway?
  • Can you communicate with:
    • the Istio Gateway?
    • Keycloak?
    • the external load balancer (if applicable)?
  • Does DNS resolve to the expected IP address?
  • Can you send a curl request to:
    • https://auth.<baseURL>/auth/realms/knime and get a healthy-looking response?

Troubleshooting Scenarios ​

Node port conflicts: port already allocated ​

Error

text
The Service "istio-ingressgateway" is invalid:
spec.ports[0].nodePort: Invalid value: 80: provided port is already allocated
spec.ports[1].nodePort: Invalid value: 443: provided port is already allocated

Likely cause

A conflicting service (often ingress-nginx-controller) is still mapped to node ports 80/443.

Resolution

Delete the conflicting service and redeploy.

Node port conflicts: port not in the valid range ​

Error

text
... provided port is not in the valid range. The range of valid ports is 30000-32767 ...

Likely cause

The Kubernetes distribution blocks low-level ports (80/443).

Resolution

Override the node ports to 30080/30443 and update any load balancers that target specific node ports.

Example override:

yaml
knime-hub-istio-ingressgateway:
  overrides:
    gateway:
      service:
        type: NodePort
        ports:
          - name: http2
            nodePort: 30080
            port: 80
            protocol: TCP
            targetPort: 8080
          - name: https
            nodePort: 30443
            port: 443
            protocol: TCP
            targetPort: 8443

Services can’t talk to Keycloak ​

Symptom example:

  • OIDC server is not available at the https://auth.<baseURL>/auth/realms/knime URL

Likely cause

Redirect behavior mismatch (HTTP → HTTPS redirect enabled when it should not be, or vice versa).

Resolution

Review the Istio Gateway configuration and enable/disable HTTP → HTTPS redirect as appropriate.

SSL verification issues (insecure certificate, etc.) ​

Likely causes

  • Invalid certificate
  • Incorrect HTTP → HTTPS redirection
  • Incorrect backend protocol configuration on the load balancer

Resolution

  • Certificate validity must be addressed by providing a valid certificate.
  • If TLS is terminated at the load balancer, ensure the backend protocol configuration matches the expected gateway behavior. In some configurations, the Istio Gateway receives HTTP traffic on port 443 when TLS is terminated upstream by the load balancer.

Redirection error: http: server gave HTTP response to HTTPS client (SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER) ​

Likely cause

This error can have several causes but generally indicates that TLS traffic is not being terminated where expected.

To help diagnose the issue, test the authentication endpoint using both HTTP and HTTPS:

bash
curl -vL http://auth.<baseURL>/auth/realms/knime
curl -vL https://auth.<baseURL>/auth/realms/knime

If TLS is enabled and the HTTP request returns a valid JSON response but the HTTPS request fails, this usually confirms that TLS termination is not configured or functioning correctly.

Resolution

  • Replicated (KOTS)

    • Verify that the TLS Certificate Configuration setting is configured correctly.

      • If the value was previously changed from Upload your own certificate, confirm that the Private Key File and Certificate File are still present and valid. If applicable, restore the configuration to Upload your own certificate and redeploy.

      • If Networking → TLS Certificate Configuration is set to Existing TLS Secret, ensure that the TLS secret named business-hub-certificate exists in the istio-system namespace. If it does not exist, create it. For KNIME-managed Istio deployments, this secret can also be created by enabling Networking: Istio → Enable Istio TLS Secret.

    • You can also test whether disabling Enable Istio Gateway HTTP to HTTPS Redirect resolves the issue.

  • ArgoCD

    • Ensure that the knime-hub-infrastructure and knime-hub-istio-ingressgateway overrides are configured correctly and consistent with your TLS setup.

Webpage does not load (spins, then times out) ​

Likely cause

Load balancer / DNS mismatch. For example:

  • DNS points to a load balancer that no longer exists
  • Load balancer has no valid targets
  • A LoadBalancer service was removed and the load balancer was deprovisioned

Resolution

Confirm the correct load balancer endpoint exists and DNS resolves to it. If a load balancer is required but missing, recovery steps depend on your delivery method and existing infrastructure approach.

Webpage returns 400 Bad Request ​

Likely cause

Requests are received by Istio but cannot be routed to the relevant service.

Resolution

Check istio-ingressgateway pod logs. If you see proxy-protocol-related symptoms (e.g., flags suggesting proxy protocol), ensure proxy protocol is disabled on the load balancer, or remove the relevant service annotation if using that method.

Replicated deployment fails due to missing TLS cert ​

Likely cause

Some clusters with separately managed ingress (including OpenShift) may default to “Upload your own Certificate”.

Resolution

In KOTS config, confirm “Handled by External Load Balancer” is selected where applicable before redeploying.

Edge case: /jobs/* endpoints return 403 (customer-managed Istio) ​

This scenario can occur when:

  • The customer installs Istio themselves, and
  • They are installing Istio for the first time as of 1.18.0.

Symptom

  • /jobs/* endpoints returning 403
  • Istio-proxy logs mention RBAC/ext-authz policies

Resolution

Edit the istio configmap in the Istio namespace and verify the configured namespace and service for the ext-authz provider matches the KNIME Business Hub namespace in your cluster.

For example, a configuration referencing:

auth-exchanger.knime.svc.cluster.local

may need to be updated to:

auth-exchanger.<your-namespace>.svc.cluster.local

Reference ​