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 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 - Public endpoint​

By default, Witboost computational governancance is not publicly exposed. There are some circumstances where having it public might be mandatory:

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

In order to publicly expose WCG, you can enable its dedicated ingress

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 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​
warning

Migration procedure mentioned in this section is NOT supported by Witboost Infra CLI and needs to be performed manually.

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​

warning

Migration procedure mentioned in this section is NOT supported by Witboost Infra CLI and needs to be performed manually.

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)