Skip to main content

Migrating to 2.7.0

Migration Guide​

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

Follow these steps to migrate from the previous version to Witboost version 2.7.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.7.0. Refer to the published Helm chart for details.

Upgrade Steps​

Authentication against Witboost Computational Governance​

Starting from this version, the Witboost Computational Governance (WCG) service now requires authentication to contact their endpoints. Please check the WCG authentication page of the documentation to understand how it works, but in short there are two ways you can set up authentication:

  • Service Account JWTs, short-lived, secure and scoped tokens provided by Witboost Core through an endpoints using an Service Account access token
  • Legacy technical tokens, where you can generate yourself a JWT token using a valid backend secret configured under computational-governance-platform.platform-services.auth.backend-secrets.
warning

Migration procedures mentioned in this section are NOT supported by Witboost Infra CLI and need to be performed manually.

WCG - Public endpoint​

By default, Witboost Computational Governance is not publicly exposed. There are some circumstances where having it public might be necessary:

  • you have external remote policies that must interact with it
  • you use the Witboost CLI from a CI/CD

If this is not your case you can skip this section. Otherwise, in order to publicly expose WCG, you can enable its dedicated ingress in the governance-platform section of the values.yaml file:

governance-platform:
  ingress:
    enabled: true
    domain: *domain
    annotations:
      << : *ingress_defaults
      cert-manager.io/cluster-issuer: *clusterIssuer

If domain is witboost.foo, this ingress will expose the endpoint wcg.witboost.foo

note

In this snippet, domain, ingress_defaults and clusterIssuer are globals defined in the main Helm chart, but you might need to change them based on your current setup.

WCG - Coordinator authentication​

If your installation includes the full Control Plane, it is necessary to update the Witboost Computational Governance and the Provisioning Coordinator configurations in order to allow the Provisioning Coordinator to contact WCG with a valid JWT token, and for WCG to correctly allow these tokens. Please follow these steps:

  • Define and store a backend secret on the Witboost Computational Governance configuration computational-governance-platform.platform-services.auth.backend-secrets. It is possible to reuse the CORE_BACKEND_PLUGIN_AUTH_SECRET secret present in the vault for this purpose:

Example updated values.yaml

governance-platform:
  configOverride: |
    computational-governance-platform {
      platform-services {
        auth {
          backend-secrets = [
            ${CORE_BACKEND_PLUGIN_AUTH_SECRET}
          ],
        },
      },
    }

Otherwise, you can also define a new secret and store it as part of your vault. This value must be at least 24 bytes long and generated in a secure way. To generate this value you can for example use a tool like openssl:

> openssl rand -base64 24

Or node if you have it installed:

> node -p 'require("crypto").randomBytes(24).toString("base64")'
  • Store this secret and refer to it also in the Provisioning Coordinator configuration migration explained below.
  • We recommend to add this value also under the UI configuration ui.appConfig.backend.auth.keys like shown below, by replacing the <new-secret-base64-encoded> placeholder:

Example updated values.yaml

ui:
  appConfig:
    backend:
      auth:
        keys:
          - secret: '${CORE_BACKEND_PLUGIN_AUTH_SECRET}'
          - secret: '<new-secret-base64-encoded>'
warning

Be careful updating this section, as both backend.auth.keys[].secret and backend.auth.secrets.key configurations exist in this section, and they relate to different values.

WCG - external authentication​
warning

Migration procedures mentioned in this section are NOT supported by Witboost Infra CLI and need to be performed manually.

This section applies only if you have external services/actors contacting the Witboost Computational Governance. If this is not your case you can skip to the next section.

To migrate your installation in order for these services to correctly work with the new authentication layer follow these steps:

  • If you're now exposing the Witboost Computational Governance through its own ingress: No further migrations are needed, follow the WCG authentication documentation to set up your authentication flow.

  • If you're proxying Computational Governance endpoints through Core configuration: If you're configuring ui.appConfig.proxy.endpoints to expose Computational Governance endpoints through the UI service, follow these steps to update your configuration:

    • On the UI configuration, in order to not only require these credentials but to forward them to the target endpoint, set the value credentials: 'forward' and proxy.reviveConsumedRequestBody: true like shown below:
    ui:
      appConfig:
        proxy:
          reviveConsumedRequestBodies: true
          endpoints:
            <your endpoint>:
              target: http://governance-platform:8090/governance-platform
              credentials: "forward"
    • If you're using Technical Tokens (tokens defined via a backend secret) to contact the proxied endpoint, you must also add the backend secret being used to generate these JWTs in the Witboost Computational Governance configuration section under computational-governance-platform.platform-services.auth.backend-secrets.
    warning

    Be aware that even if User tokens are allowed for the proxy service, these are not allowed by the Witboost Computational Governance. If you're using JWTs picked directly from users, please migrate your authentication flow to use either Service Account tokens (recommended) or technical tokens. Check the WCG authentication page of the documentation for more information.

  • If you're contacting Computational Governance endpoints through a service internal to the cluster: If a service you use contacts the Witboost Computational Governance internally (i.e. contacting its service URL http://governance-platform:8090/governance-platform), you need to now include an HTTP Authorization header with a valid token as part of your request. Follow the WCG authentication documentation in order to set up your authentication flow via either Service Account Tokens (preferred) or technical JWTs.

Provisioning Coordinator​

warning

Migration procedures mentioned in this section are NOT supported by Witboost Infra CLI and need to be performed manually.

Coordinator-WCG split​

Until now, the Provisioning Coordinator and Witboost Computational Governance (WCG) could been run as two distinct services within the same server (i.e., a single Docker image — the Provisioning Coordinator's one — containing both).

Starting with this release, WCG and Coordinator must be run independently.

If in your values.yaml config provisioning-coordinator.enable-coordinator-cgp-compatibility it set to true, please refer to the Witboost v2.3 Migration Notes to understand how to migrate your installation to launch WCG and the Coordinator as two different services.

Coordinator-WCG authentication​

In order for the Coordinator to contact WCG, you need to define a proper authentication configuration. Ensure to configure a token factory of type jwt-factory as explained in our official docs inside provisioning-coordinator.tokens section. Then, store the name of the factory under a new section http-auth inside provisioning-coordinator.governance-platform like the following example, where the name given to the token factory in this case is wcg-jwt:

warning

Be sure to use as secret of the factory one of the backend-secrets defined in WCG configuration (computational-governance-platform.platform-services.auth.backend-secrets section defined above).

Example Updated values.yaml​
provisioning-coordinator:
  configOverride: |-
    provisioning-coordinator {
      tokens = {
        wcg-jwt = {
          type = "jwt-factory"
          jwt-factory = {
            secret = ${CORE_BACKEND_PLUGIN_AUTH_SECRET}
            isSecretBase64Encoded = true
            expiration = 1 hour
            payload = "{\"sub\": \"coordinator\"}"
          }
        }
      }
      governance-platform {
        http-auth = {
          bearer-token-key = "wcg-jwt"
        }
      }
    }

Core​

Secrets​
note

You can skip this section if you're using the Witboost Infra CLI transform operation, as this is automatically performed by it, unless you want to customize the used secrets.

New secrets have been introduced for the access token functionality.

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

ui:
  appConfig:
    backend:
      auth:
        secrets:
          key: "${CORE_USER_CONFIG_KEY}"
          iv: "${CORE_USER_CONFIG_IV}"
warning

Be careful updating this section, as both backend.auth.keys.secrets[] and backend.auth.secrets.key might exist in this section, and they relate to different values.

If there was no backend.auth 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 key and IV 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. For example, the following command can be used to generate such a key in a terminal:

     > openssl rand -hex 32

    or in alternative if you have node installed

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

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

     > openssl rand -hex 16

    or in alternative if you have node installed

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

After following the previous steps and successfully migrating, by accessing the Witboost UI on the Administration Panel > Roles and Permissions, you can now update your RBAC setup to include newly introduced permissions:

  • In order to manage Service Accounts, you must assign the platform.users.service-accounts.edit permission to your administrator role.
  • In order to manage Access tokens for Service Accounts, you must assign theplatform.users.service-accounts.access-tokens.edit permission to your administrator role.

Witboost CLI​

Witboost CLI officially reaches v1.0.0 as its first stable release. If you were previously using the Witboost CLI, you may need to adjust the command invocation according to the latest changes. If you were not using the Witboost CLI before, skip this section and explore the new Witboost CLI.

Follow the instructions below to migrate to the new commands:

Authentication

When you run witboost governance evaluate ...other parameters... --token < TOKEN >, now < TOKEN > must be a valid Service Account Access Token. Check the docs to see how to create a service account access token.

Moreover you will now have to pass to the CLI where the base URL of the Witboost backend is located, this is needed by the CLI to exchange the Service Account Access Token with a short-lived JWT (see more details here).

In summary, the witboost governance evaluate command will look like this:

witboost governance evaluate \
  --auth-base-url <witboost UI backend base URL>/api/auth \
  --base-url <witboost computational governance base URL> \ # (should end with /governance-platform)
  --token <service account access token> \
  #...other parameters...

You can also supply auth-base-url, base-url and token via environment variables or CLI configuration file. Check the help command for more details by running witboost governance evaluate --help.

Authentication Base URL

The Authentication Base URL is the URL you use to access your Witboost UI with a fixed trailing part that is /api/auth.

E.g. If you access Witboost at https://witboost.my-example-company.com then your Authentication Base URL will be: https://witboost.my-example-company.com/api/auth

Parameters renaming

Adjust the following options in any of the CI scripts where you are using the Witboost CLI:

  • --res-type has been renamed into --resource-type

Resource metadata parsing

Witboost CLI is no longer parsing the id field from a resource descriptor. You can assign an id to the resource descriptor by supplying the --resource-id parameter, which is now mandatory. If you want to mimic the previous behaviour of the Witboost CLI, you can leverage yq as follows:

witboost governance evaluate \
  ...other parameters...
  --resource-id "$(yq '.id' <path to your resource descriptor>)"

--output and --output-file options behaviour

Previously, --output json was writing to a file, that by default was called evaluation-report.json and the name of the file could be changed using --output-file another-name.json.

Now --output can be set to json and be redirected to stdout to enable pipe operator, without writing any file, this means you can supply the JSON format of your evaluation report to downstream commands. e.g.

witboost governance evaluate \
  ...other parameters...
  --output json | yq -r '.evaluationResults[] | [.governanceEntityId, .outcome] | @tsv' # this prints a list of evaluation result with governance entity ID and outcome

If you want your JSON to be written to a file, you will need to specify a file name:

witboost governance evaluate \
  ...other parameters...
  --output json \
  --output-file output.json

Or, if you want, now you can also write the Table in a file:

witboost governance evaluate \
  ...other parameters...
  --output-file mytable.txt

Or pipe the table to a downstream command, e.g. grep:

witboost governance evaluate \
  ...other parameters... | grep "my policy" # shows the result of applying "my policy" to the input resource

Exit on failure code

If you were previously using --exit-on-failure, now the exit code has changed as follows:

  • 0 evaluation done. either all policies/metrics passed or at least of failed. The outcome can be seen by reading the evaluation report.
  • 1 a technical error that prevented the execution of the evaluation happened
  • 3 any of the policies applied did not pass (the resource is not compliant)