Skip to main content

Migrating to 2.6.0

Migration Guide​

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

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

Backup Your Data​

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

Update Dependencies​

Ensure all the dependencies in the Helm files are updated to their compatible versions for 2.6.0. Refer to the published Helm chart for details.

Upgrade Steps​

External DNS Configuration Update​

If you have enabled external-dns in your deployment, you may need to update your configuration to align with the new chart structure especially if there are any custom configurations you wish to keep.

As part of this release, ExternalDNS has moved from the Bitnami chart to the Kubernetes SIGs chart.

Please review the official Kubernetes SIGs ExternalDNS chart documentation for the full set of supported values and configuration options.

AWS provider example​

If you previously enabled external-dns for the aws provider, you must update your values.yaml file with the new configuration fields. Specifically, you will need to define both:

  1. Provider Configuration The provider block specifies which DNS provider ExternalDNS should use. For example, when using AWS Route53:

    external-dns:
      provider:
        name: aws

  2. Environment Variables Environment variables must now be declared under the env section. For AWS, you must at minimum specify the region:

    external-dns:
      env:
        - name: AWS_DEFAULT_REGION
          value: <your-aws-region>
Example Updated values.yaml​

Here is a combined example showing the updated structure:

external-dns:
  enabled: true
  ...
  ...
  provider:
    name: aws
  env:
    - name: AWS_DEFAULT_REGION
      value: <your-aws-region>

Replace <your-aws-region> (e.g., us-east-1, eu-west-1) with the region where your Route53 hosted zones are configured.

Extension Manager​

Secrets​

New secrets have been introduced for the sensitive headers webhooks functionality.

Add the new section notifications.webhooks.secrets (under appConfig in the ui block of the values.yaml file of the Witboost Chart) like this:

notifications:
  webhooks:
    ...
    secrets:
      key: '${CORE_USER_CONFIG_KEY}'
      iv: '${CORE_USER_CONFIG_IV}'

If there was no notifications.webhooks section in your values.yaml file, you must create it and add the secrets section as described above.

The default configuration provided above will leverage the same secrets defined for the user config functionality, since they are fully compatible, but you can change them if you prefer.

To generate them:

  • key: Can be any 32 bytes hexadecimal key. The following command can be used to generate such a key in a terminal:

     > node -p 'require("crypto").randomBytes(32).toString("hex")'

  • iv: Can be any 16 bytes hexadecimal key. The following command can be used to generate such a key in a terminal:

     > node -p 'require("crypto").randomBytes(16).toString("hex")'
Permissions​

In order to access the new Webhooks Extension Manager section, you must assign the platform.extensions.webhooks.edit permission to your administrator role.

CustomUrlPicker​

The implementation of the CustomUrlPicker offset param has been changed to reflect the originally intended behaviour defined in the Custom URL Picker API specification.

Previously, offset was incorrectly implemented in the CustomUrlPicker as a page, sending an offset increased by 1 to retrieve the next batch of items.

Now, the current offset implementation treats it as an actual offset, meaning each request will include an offset exactly equal to the number of already fetched items and thus to be skipped, as defined by the Custom URL Picker API specification.

If you previously implemented your microservices assuming offset behaved as a page instead of an actual offset, you can defer migrating the microservices by adding mesh.builder.ui.remoteProvider.oldOffsetBehaviour (under appConfig in the ui block of the values.yaml file of the Witboost Chart) and setting it to true. This will enforce the old behaviour on components interfacing with the Custom URL Picker API specification, such as CustomUrlPicker and the new Remote provider on the EntitySearchPicker.

Software Catalog​

UI Changes​

The Software Catalog has been relocated and renamed in version 2.6.0:

  • Removed from main page: The Software Catalog is no longer accessible from the main navigation page
  • New location: It has been moved to the Administration area and renamed to "Entities"
  • Path: You can now find it under Administration > Entities
Template Management​

Template-related functionalities have been centralized for all template types:

  • Template registration: No longer available from the main template page
  • Template editor: Moved from the main template page to the Administration area
  • Installed actions: No longer viewable from the main template page

All these functionalities are now available under Administration > Templates and apply to all template types including:

  • Blueprints
  • Edit Templates
  • Reverse Provisioning Templates
  • System Prototype Templates
  • Access Control Request Template
Permissions​

To access the renamed Software Catalog (now called "Entities"), users need both:

  • builder.software-catalog.view - existing permission for Software Catalog access
  • platform.settings.edit - new permission required to access the Administration area

Ensure your user roles include both permissions to maintain access to the Software Catalog functionality.

Post-Migration Verification​

After completing the migration:

  1. Verify that users with appropriate permissions can access Administration > Entities
  2. Confirm that template management functions are working properly under Administration > Templates
  3. Test that all existing Software Catalog data is visible in the new Entities section

Custom Views​

The custom views builder_entity_content and practice_shaper_content have been modified and no longer include the builder_system_general custom view.

This means that if you have previously customized the builder_system_general custom view, your modifications will no longer be visible in the builder_entity_content and practice_shaper_content default views.

This change affects only the default builder_entity_content and practice_shaper_content custom views, so if you are using customizations for them nothing will change. If you want these custom views to still include builder_system_general, you can create a customization for them and add the include statement as described below, even though this is NOT recommended.

builder_entity_content

# "builder_entity_content" custom view snippet to restore previous behavior

view:
  children:
    - children:
        - type: catalog_warnings
        - type: include
          id: builder_system_general

practice_shaper_content

# "practice_shaper_content" custom view snippet to restore previous behavior

view:
  children:
    - children:
        - type: include
          id: builder_system_general