Skip to main content

Migrating to 2.9.0

Migration Guide​

Here you can find the needed steps to upgrade your current Witboost installation to v2.9.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.8.0 or earlier and wish to upgrade to version 2.9.0.

Follow these steps to migrate from the previous version to Witboost version 2.9.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.9.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 domain names or cluster issuers).

Gateway and Ingress Configuration​

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

note

If you are using the Infra CLI, it will automatically create the ingress and gateway configuration structure in your values.yaml.
However, you must manually update any CHANGEME placeholders with the actual cluster issuer to be used specifically for gateways if you plan to use one.

Automatically handled by Infra CLI

  • New blocks for global.ingress and global.gateway are added.
  • These control the creation and configuration of whether to use ingress or gateway resources.

Below configurations are added to the values.yaml:

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

Service-Specific Gateway Changes​

note

For all following service-specific gateway changes, after using the Infra CLI or applying the configuration manually, make sure to replace every CHANGEME placeholder with the actual domain name appropriate for your environment.

UI​

Automatically handled by Infra CLI

  • The ui.gateway block is added for gateway's TLS configuration.
ui:
  gateway:
    # -- Optional: If gateway is enabled and you'd like to set a custom tls secret name for the UI gateway listener.
    tls:
      secretName: ''

Hasura​

Automatically handled by Infra CLI

  • The hasura.gateway block is added for subdomain and TLS.
  • The hasura.global.gateway block is added for domain.
hasura:
  # -- Optional: If gateway is enabled and you'd like to set a custom subdomain and tls secret name for the hasura gateway listener.
  gateway:
    subdomain: ''
    tls:
      secretName: ''

hasura.global:
  gateway:
    domain: CHANGEME

Documentation​

Automatically handled by Infra CLI

  • The documentation.gateway block is added for subdomain and TLS.
  • The documentation.global.gateway block is added for domain.
documentation:
  # -- Optional: If gateway is enabled and you'd like to set a custom subdomain and tls secret name for the documentation gateway listener.
  gateway:
    subdomain: ''
    tls:
      secretName: ''

documentation.global:
  gateway:
    domain: CHANGEME

Witty​

Automatically handled by Infra CLI

  • The witty.gateway block is added for subdomain and TLS.
  • The witty.global.gateway block is added for domain.
witty:
  # -- Optional: If gateway is enabled and you'd like to set a custom subdomain and tls secret name for the witty gateway listener.
  gateway:
    subdomain: ''
    tls:
      secretName: ''

witty.global:
  gateway:
    domain: CHANGEME

Governance Platform​

Automatically handled by Infra CLI

  • The governance-platform.gateway block is added for subdomain and TLS.
  • The governance-platform.global.ingress and governance-platform.global.gateway blocks are added for domain configuration.
governance-platform:
  # -- Optional: If gateway is enabled and you'd like to set a custom subdomain and tls secret name for the governance-platform gateway listener.
  gateway:
    subdomain: ''
    tls:
      secretName: ''

governance-platform.global:
  ingress:
    domain: CHANGEME
  gateway:
    domain: CHANGEME

Witboost MCP Server​

Automatically handled by Infra CLI

  • The witboost-mcp-server.gateway block is added for subdomain and TLS.
  • The witboost-mcp-server.global.gateway block is added for domain.
witboost-mcp-server:
  # -- Optional: If gateway is enabled and you'd like to set a custom subdomain and tls secret name for the witboost-mcp-server gateway listener.
  gateway:
    subdomain: ''
    tls:
      secretName: ''

witboost-mcp-server.global:
  gateway:
    domain: CHANGEME

Cert Manager Configuration​

note

Remember to update the CHANGEME placeholder value for gatewayClusterIssuer with the actual cluster issuer used in your environment. This should match the value set earlier under globals.gateway.annotations.cert-manager.io/cluster-issuer.

Automatically handled by Infra CLI

  • The globals.certManager.gatewayClusterIssuer field is added.
globals:
  certManager:
    gatewayClusterIssuer: CHANGEME

External Secrets Configuration​

Automatically handled by Infra CLI

  • The globals.externalSecrets block is augmented with setting the apiVersion for external secrets.
globals:
  externalSecrets:
    apiVersion: external-secrets.io/v1beta1

Convert HOCON sections to YAML​

Automatically handled by Infra CLI

  • The provisioning-coordinator.configOverride, governance-platform.configOverride, and mock-specific-provisioner.configOverride (if any) should be converted from HOCON format to YAML format. Backward compatibility is still supported, but we strongly encourage migrating to YAML because the HOCON sections will be deprecated soon.

An example of existing configuration in the values.yaml file to be converted:

provisioning-coordinator:
  enabled: true
  image:
    registry: <registry>
  extraEnvVars:
      - name: COORDINATOR_DB_DBNAME
        value: *provisioningCoordinatorDB
      - name: CGP_DB_DBNAME
        value: *provisioningCoordinatorDB
  configOverride: |-
      akka {
        http.parsing.max-header-value-length = 256k
        http.server.request-timeout = 120 seconds
        http.server.idle-timeout = 120 seconds
      }

How the configurations should look after the conversion:

provisioning-coordinator:
  enabled: true
  image:
    registry: <registry>
  extraEnvVars:
      - name: COORDINATOR_DB_DBNAME
        value: *provisioningCoordinatorDB
      - name: CGP_DB_DBNAME
        value: *provisioningCoordinatorDB
  configOverride:
    akka:
      http:
        parsing:
          max-header-value-length: 256k
        server:
          request-timeout: 120 seconds
          idle-timeout: 120 seconds

How to convert HOCON blocks

  • If you already use the Infra CLI for migrations, the conversion will be automatically handled by the transform command when targeting version 2.9.0. See the transform command reference for details.
  • If you have never used the Infra CLI for migrations before, a new convert-hocon command has been introduced specifically for this purpose. It converts HOCON blocks to YAML in your values.yaml without requiring you to adopt the CLI for future upgrades. See the convert-hocon command reference for details.
  • If you prefer not to use the CLI, you can perform the conversion manually by rewriting the HOCON blocks as equivalent YAML, following the example shown above.

What happens if you do not migrate to full YAML

HOCON format is still supported in this release. However, migrating configOverride blocks to YAML enables the Infra CLI to apply migration rules to parameters nested within those blocks. Before this release, migration rules could not act on parameters in HOCON format, requiring manual intervention for any such changes. With a fully YAML-structured values.yaml, migration rules can operate at every level of the file, reducing the risk of manual errors during future upgrades.

In this release, there are no parameters within HOCON blocks that require automatic migration. However, starting from the next release, there may be. If you plan to continue using the Infra CLI for upgrades, a fully YAML-structured values.yaml will be mandatory at that point.

CSP​

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

You automatically benefit from this security improvement if you are not overriding either of these configuration paths:

  • ui.appConfig.backend.csp.script-src
  • ui.appConfig.backend.csp.script-src-elem

If you are overriding them, you can remove unsafe-eval 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:
        ...
        script-src: ["'self'", "'unsafe-eval'", 'http:', 'https:']
        script-src-elem: ["'self'", "'unsafe-eval'", 'http:', 'https:']

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

ui:
  appConfig:
    backend:
      csp:
        ...
        script-src: ["'self'", 'http:', 'https:']
        script-src-elem: ["'self'", 'http:', 'https:']
note

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

Memory Allocation​

To support the stricter CSP described above, some processing flows that previously ran in the frontend have been moved to the backend. As a result, the core backend pod may experience increased memory usage.

If you are configuring explicit resource limits for the ui backend pod (ui.backend.resources config), we recommend increasing the memory allocation by at least 5% compared to your current values, with a minimum increase of 128Mi.

This can be configured via ui.backend.resources, which follows the standard Kubernetes resource syntax:

ui:
  backend:
    resources:
      requests:
        memory: '1Gi'
      limits:
        memory: '5Gi'

Adjust the values above according to your current resource configuration.

Custom Views​

Removed support for the following configuration values:

  • ui.appConfig.mesh.marketplace.ui.dataProductPage.additionalGeneralInfo
  • ui.appConfig.mesh.marketplace.ui.outputPortPage.additionalGeneralInfo

These values allowed to specify some fields that were automatically injected in the default marketplace_system_general and marketplace_component_general custom views.

If you were not using any of these configuration values or you have you have active customizations for marketplace_system_general or marketplace_component_general, nothing will change: to check, go to Administration > Custom Views > marketplace_system_general (marketplace_component_general) and check if there are some customizations with enabled status.

If there aren't any and you wish to still retain the previously configured fields, you can create new customizations and add the fields directly in the customizations themselves.

For example, if originally you had configured the following field:

ui:
  appConfig:
    mesh:
      marketplace:
        ui:
          dataProductPage:
            additionalGeneralInfo:
              - label: Example field
                value: Example
                type: string

you can arrange the field in a customization for marketplace_system_general or marketplace_component_general like this (or wherever you prefer):

view:
  children:
    - type: marketplace_info_card
      title: General Information
      children:
        - type: hbox
          children:
            - type: container
              size: 3
              children:
                - type: automatic_fields_list
                  path: ""
                  ...
                - label: Example field
                  type: string
                  value: Example
            ...
        ...
    ...

Search Filters​

Starting from this release, configuration for search filters has been migrated to the UI under Administration > Configuration page.

On first startup, currently defined search filters will be automatically migrated to the new configuration location, so you don't need to do anything for the migration.

warning

After the migration, you will need to maintain search filters directly from the UI going forward, as any changes to the old configuration location will no longer have any effect.

Custom Pages​

Starting from this release, configuration for custom pages has been migrated to the UI under Administration > Configuration page. Custom pages can be managed from the Marketplace tab and the Builder tab respectively.

On first startup, currently defined custom pages will be automatically migrated to the new configuration location, so you don't need to do anything for the migration.

warning

After the migration, you will need to maintain custom pages directly from the UI going forward, as any changes to the old configuration location will no longer have any effect.

Team Roles​

We have introduced a new feature called "Team Roles" to enable delegation of responsibilities from the project owner to other users. Find out more information about how to enable and configure this feature in its dedicated section.

As part of the configuration of this feature, we recommend to add the new permission control-plane project team-roles troubleshoot to your Administrator role by going to the Administration panel > Roles and Permissions, selecting your administrator role, and adding the permission by clicking on the "Add" button in the Permissions tab. This permissions allows to access all projects Team Roles tab, so be careful to grant it only to your administrator role; other Team Roles role and permissions setup for the end users are explained in the dedicated section for this feature.

Git tokens for service accounts​

We have introduced the possibility to define git tokens for service accounts as explained in the dedicated section.

Since only users with the platform.users.service-accounts.git-tokens.edit permission can manage git tokens for service accounts, make sure to assign this permission to the appropriate roles by going to the Administration panel > Roles and Permissions, selecting the role you want to grant the permission to, and adding the platform.users.service-accounts.git-tokens.edit permission. We recommend granting this permission only to administrator users or to specific users in charge of managing service accounts, as it allows to manage git tokens for all service accounts in the platform.