Migrating to 2.10.0

Migration Guide

Here you can find the needed steps to upgrade your current Witboost installation to v2.10.0. Please refer to the release notes for a detailed list of changes and improvements. This guide is intended for users who are currently running Witboost version 2.9.0 or earlier and wish to upgrade to version 2.10.0.

Follow these steps to migrate from the previous version to Witboost version 2.10.0:

Backup Your Data

Before starting the migration, ensure you have a complete backup of your database and configuration files.

Upgrade Steps

If you are using the Witboost Infrastructure CLI, you can execute the following command to automatically migrate your configuration file by replacing the placeholder <path_to_values.yaml> with the path to your values.yaml file:

witboost-infra transform --user-values <path_to_values.yaml> --set-target 2.10.0 --output-path <path_to_values.yaml>

After this, follow the rest of the migration steps, skipping those marked as automatically handled by the Infra CLI.

All configuration changes below are automatically handled by the Infra CLI, but you must still manually update any CHANGEME placeholders in the automatically generated configuration with the actual values required for your environment (such as cluster issuers).

---

Global Ingress and Gateway Configuration

For background on why these changes are required and their impact, please refer to the Ingress and Gateway Migration Guide.

Automatically handled by Infra CLI

note

The Infra CLI applies two distinct transformations to global.ingress and global.gateway, depending on what is already present in your values.yaml:

• If global.ingress or global.gateway is absent: the full default block is created (see below).
• If global.gateway is already present: only the three new fields introduced in v2.10.0 (namespace, sectionName, tlsMode) are added if they are not already set. Existing values are never modified.

Creating global.ingress and global.gateway (first-time)

If global.ingress or global.gateway is not yet present in your values.yaml, the Infra CLI creates them with the following defaults:

global:
  ingress:
    create: true
  gateway:
    create: false
    useExisting: false
    name: witboost-gateway
    namespace: ''
    sectionName: ''
    tlsMode: 'terminate'
    gatewayClassName: nginx
    annotations:
      cert-manager.io/cluster-issuer: CHANGEME
    labels:
      app.kubernetes.io/name: shared-gateway
      app.kubernetes.io/part-of: platform

The CHANGEME placeholder must be replaced manually with the name of your cert-manager ClusterIssuer after the Infra CLI runs. If you are not using cert-manager, remove the annotation entirely.

New global.gateway fields for existing Gateway users

If global.gateway is already present in your values.yaml (for example, because you migrated to Gateway API in v2.9.x), the Infra CLI adds the three new fields below, but only if they are not already set. No existing values are overwritten.

Field	Injected default	Purpose
namespace	""	Namespace where the Gateway resource lives. Required only when useExisting: true and the Gateway is in a different namespace from the Witboost release. Leave empty when both are in the same namespace.
sectionName	""	Pins all Witboost HTTPRoutes to a specific named listener on a shared Gateway. Only relevant with useExisting: true to isolate Witboost routes on a multi-tenant Gateway. Leave empty for standard deployments.
tlsMode	"terminate"	Controls TLS handling on the Gateway. terminate (default): the Gateway terminates TLS and requires certificates. external: TLS is terminated upstream by a cloud load balancer or reverse proxy; no TLS Secrets are required inside the cluster.

---

Reloader Image Configuration

Automatically handled by Infra CLI — only when not already present

Starting from v2.10.0, the Stakater Reloader image coordinates and deployment configuration are explicitly surfaced in the Witboost chart values. Previously these values were implicit, inherited from the upstream Reloader chart defaults. Making them explicit allows them to be overridden — which is particularly useful in air-gapped environments or private-registry deployments where the cluster cannot reach ghcr.io directly.

The following configuration is added under the reloader key:

reloader:
  image:
    repository: ghcr.io/stakater/reloader
    tag: v1.4.16
    pullPolicy: IfNotPresent
  reloader:
    deployment: {}

The Infra CLI handles this in two cases:

• If reloader is absent in your values.yaml: the entire block above is created.
• If reloader already exists: only the keys that are not already present are injected. The merge is shallow — if you already have a reloader.image block (for example, pointing to a private registry), it is left completely untouched, including any sub-keys (repository, tag, pullPolicy). Equally, an existing reloader.reloader.deployment configuration is never overwritten.

---

CSP

Starting from this release, Witboost applies a stricter default Content Security Policy (CSP) by removing the unsafe-inline directive from style sources.

You automatically benefit from this security improvement if you are not overriding the following configuration path:

• ui.appConfig.backend.csp.style-src

If you are overriding them, you can remove unsafe-inline manually to align with the new more secure default (note that this is not mandatory).

For example, if your current configuration is:

ui:
  appConfig:
    backend:
      csp:
        ...
        style-src: ["'self'", "'unsafe-inline'", 'https:']

you can improve the overall security of Witboost by changing it to:

ui:
  appConfig:
    backend:
      csp:
        ...
        style-src: ["'self'", 'https:']

note

If you run custom pages (microfrontends) that require unsafe-inline for some functionalities, those may stop working correctly unless you manually reintroduce unsafe-inline in style-src. However, we recommend to do it only where strictly necessary, and prefer updating those microfrontends to avoid this directive whenever possible.

Microservice Proxy for Custom URL Picker

As a security enhancement, microservice calls made by Custom URL Picker fields (e.g. for retrieval and validation) are now proxied through the Witboost backend instead of being executed directly from the user's browser.

As a result of this change, microservice endpoints must be reachable from within the cluster (i.e. from the Witboost backend pod). If your microservice endpoints were previously only accessible from the user's browser network, you will need to ensure they are also reachable from the cluster where Witboost is deployed (e.g. via internal DNS, VPC peering, or a VPC endpoint).

The microserviceConfiguration entries are located under:

ui:
  appConfig:
    mesh:
      builder:
        scaffolder:
          microserviceConfiguration:
            - microserviceId: 'my-microservice'
              baseUrl: 'https://my-endpoint.example.com/stage' # must be reachable from within the cluster

The same network reachability requirement applies to endpoints (optionally) defined in templates via ui:apiSpec in CustomUrlPicker fields and via apiSpec in EntitySearchPicker with Remote provider fields. When a baseUrl is specified in the template, it overrides the one from the Witboost configuration, and the overridden URL must also be reachable from the Witboost backend pod.

No changes to configuration keys or template syntax are required.

Witty & Marketplace Agent configuration

Witty's LLM and Embedder settings, as well as the Marketplace's semantic search settings and embedding management, can now be managed directly from the Administration panel without the need to redeploy. After the deploy of the new version, you can remove any existing LLM and Embedder configuration from values.yaml. In particular, the following configuration paths are now ignored if present in values.yaml:

Embeddings Search configuration

ui:
  appConfig:
    mesh:
      marketplace:
        backend:
          embeddingsSearch: // you can remove the entire block
            ...

Witty LLM and Embedder configuration

witty:
  configOverride:
    llm: // you can remove the entire block
      ...
    embedder: // you can remove the entire block
      ...

Docs agent LLM and Embedder configuration

docs-agent:
  configOverride:
    llm: // you can remove the entire block
      ...
    embedder: // you can remove the entire block
      ...