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 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.

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 in the valut. This value must be at least 24 bytes long and generated in a secure way like so (we recommend to add this value also under the UI configuration backend.auth.keys):

> node -p 'require("crypto").randomBytes(24).toString("base64")'

Store the secret in the Provisioning Coordinator configuration as well, as shown below.

WCG external authentication

If you have services contacting the Witboost Computational Governance, to migrate your installation in order for these services to correctly work with this 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 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' like shown below:

proxy:
  endpoints:
    <your endpoint>:
      target: http://governance-platform:8090/governance-platform
      credentials: "forward"

If you're using Technical Tokens (tokens defined via a backend secret), you must add the backend secret being used to generate these JWTs in the Witboost Computational Governance configuration 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

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:

  provisioning-coordinator {
     governance-platform {
      http-auth = {
        bearer-token-key = "wcg-jwt"
      }
    }
  }

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).

Example Updated `values.yaml`

provisioning-coordinator:
  configOverride: |-
    provisioning-coordinator {
      tokens = {
        wcg-jwt = {
          type = "jwt-factory"
          jwt-factory = {
            secret = "<your-base64-encoded-secret>"
            isSecretBase64Encoded = true
            expiration = 1 hour
            payload = "{\"sub\": \"coordinator\"}"
          }
        }
      }
      governance-platform {
        http-auth = {
          bearer-token-key = "wcg-jwt"
        }
      }
    }

Core

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:

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

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 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 manage Service Accounts, you must assign the platform.users.service-accounts.edit permission to your administrator role. In order to manageAccess tokensfor 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.

Below the instructions to do so:

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)

For additional documentation about the Witboost CLI, checkout its documentation from here

Migration Guide​

Backup Your Data​

Update Dependencies​

Upgrade Steps​

Authentication against Witboost Computational Governance​

WCG - Coordinator authentication​

WCG external authentication​

Provisioning Coordinator​

Example Updated values.yaml​

Core​

Secrets​

Permissions​

Witboost CLI​