Witboost Computational Governance Configuration

The Witboost Computational Governance (WCG) configuration is stored in the application.conf file of the governance-core module. It contains all the values that are required in order to make it work properly.

A typical configuration file looks like the following one:

computational-governance-platform {
    cue-config = {
        cue-process-path = "cue"
    }

    events = {
        events-backend-base-url = "http://localhost:7007/api/events"
    }

    notification = {
        mode = "witboost"
        enabled = true
        url = "http://localhost:7007/api/notifications"
        failure-event = "ScheduledPolicyFail"
        new-policy-event = "NewPolicy"
        new-metric-event = "NewMetric
        secret = ""
    }

    previous-vs-current = {
        previous-resource-reference = "original"
        current-resource-reference = "current"
    }

    resource-types = [
        {
            name = "dataproduct"
            configuration = {
                resource-name = "id"
                resource-filter = "version"
            }
            resolver-configuration = {
                url = "http://localhost:8088/datamesh.provisioningcoordinator"
                path = "v1/resolve"
            }
        }
    ]

    platform-services = {
        base-url = "http://localhost:7007"
        http-secret = ""

        environments = {
            environments-path = "/api/environment"
            environments-fetch-retries = 5
        }

        auth = {
            cache-size = 8
            cache-expiration = 8 hours
            backend-secrets = []
        }

        audit = {
            enabled = true
            audit-path = "/api/audit"
        }
    }

    evaluation = {
        enable-on-publish = true
        task-timeout = 20 seconds
        thread-pool-size = 32
    }

    database {
        schema = "cgp"
        driver = "org.postgresql.Driver"
        url = "jdbc:postgresql://localhost:5432/postgres"
        username = "postgres"
        password = "password"
        name = "provisioning_coordinator"
        host = "localhost"
        port = 5432
        migrate-on-start = true
        repair-on-start = false
        thread-pool-size = 4
        connection-timeout = 10 seconds
        max-lifetime = 10 minutes
        leak-detection-threshold = 10 seconds
    }

    cron-policies {
        reload-on-start = true
    }
}

Please note that all values that are critical from a security standpoint (e.g. db credentials) must be kept private and the related variables only referenced inside this file.

The following sections will describe each part of the configuration file shown above.

Cue configuration

The cue-config section contains all the information related to the cue policy execution.

Property Name	Type	Meaning
`cue-process-path`	`string`	The path where the cue executable is located.

Events configuration

The events section contains all configuration properties needed by the Witboost Computational Governance to send events to the witboost events plugin.

Property Name	Type	Meaning
`enabled`	`boolean`	If `true` enables the events generation from the Witboost Computational Governance
`events-backend-base-url`	`string`	It is the base URL of the events backend service that is installed on the witboost events plugin. This is a combination of the UI module base URL and '/api/events'
`runtime-policy-failed-topic`	`string`	The topic unique identifier where the runtime policy failed event will be published

Notification configuration

The notification section contains all the information related to the Witboost notification service. This is used to send notifications to users of a certain group that a new policy has been created or there has been some errors during the policy creation. This is a mandatory configuration that needs to be set. You can disable this functionality by putting the enabled field to false.

Property Name	Type	Meaning
`mode`	`string`	It is the service that will sent the notifications. For example "witboost"
`enabled`	`boolean`	If `true` enables the notification service
`url`	`string`	It contains the url of the service to call in order to send the notification. If you are using the Witboost notification service this must contain a string in the form `http(s)://{host}/api/notifications`
`failure-event`	`string`	It contains the name of the event to call in case of a failed policy creation
`new-policy-event`	`string`	It contains the name of the event to call in case of a succeeded policy creation
`new-metric-event`	`string`	It contains the name of the event to call in case of a succeeded metric creation
`secret`	`string`	It contains the authorization token to insert in the request. If you are using the Witboost notification service you can find this info in the `values.yaml` file of the UI project, under the path `ui.appConfig.backend.auth.keys['secret']`

Breaking change configuration

The breaking-change section is related to breaking change policies. It contains all the information about the references used when creating the aggregated descriptor to perform the comparison between the currently deployed version (if present) and the version you are trying to validate/deploy.

Property Name	Type	Meaning
`previous-resource-reference`	`string`	String that will be used as reference name to wrap the descriptor of the currently deployed version of the resource inside the aggregated descriptor.
`current-resource-reference`	`string`	String that will be used as reference name to wrap the descriptor of the resource version you want to validate/deploy inside the aggregated descriptor.

Resource type configuration

note

The suggested way to register a new resource type is through a POST request to the /v1/computational-governance/resource-types WCG endpoint (refer to the API reference section of the documentation). A resource type defined by configuration will be loaded at startup and will overwrite any previously registered resource type with the same name

The resource-types section of the configuration is specified as an array of objects, each one containing the following fields:

Property Name	Type	Optional	Meaning
`name`	`string`		Unique resource type name and identifier.
`display-name`	`string`	optional	Resource type display name. It defaults to `name` if not provided.
`configuration`	`object`	optional	Subsection containing resource type settings. If not provided, resource enrichment will be disabled for resources of this type and instead, callers of the Evaluate API must provide the ID and optionally a display name and a version for a given resource.
`resolver-configuration`	`object`		Subsection containing the resolver configuration.

Configuration subsection

In order to work properly, you need to specify a resource type configuration in the configuration subsection. The resource type configuration requires the following fields:

Property Name	Type	Optional	Meaning
`resource-name`	`string`		Field inside the resource descriptor that contains its unique identifier.
`resource-display-name`	`string`	optional	List of fields in the resource descriptor to be used to generate a display name.
`resource-filter`	`string`	optional	Field inside the resource descriptor used to differentiate evaluation results for the same resource.
`batch-size`	`string`	optional	Maximum number of resources requested to the perimeter resolver per request (page size).

Example:

    ...
    name = "dataproduct"
    configuration = {
        resource-name = "id"
        resource-filter = "version"
    }
    resolver-configuration = {
        ...
    }
    ...

This example means that for the resource type called dataproduct you will use the field id of the resource content (e.g. the data product descriptor) as resource name, and since it could be not enough to uniquely identify the resource, you are using the field version of the resource content as resource filter.

    ...
    name = "configresource"
    resolver-configuration = {
        ...
    }
    ...

Here, instead, you are defining a resource type called configresource without any information about its shape. This means, for example, that the resource content does not contain any field that can be used as a unique identifier. In this case, the caller must provide the ID and optionally a display name and a version when passing the resource in the Evaluate API or any other API in which resources pass by.

info

If you retrieve the configuration of a Resource Type via API using GET /v1/resource-types/<my-resource-type> and that resource type has no descriptor configuration set, the descriptor configuration block will contain the following default values:

{
  ...
  "descriptorConfiguration": {
      "resourceNameField": "WITBOOST_no_descriptor_configuration_provided",
      "resourceDisplayNameFields": [],
      "resourceFilterField": null
  },
  ...
}

Resolver configuration subsection

This section contains the information related to the resolver endpoint to contact to retrieve the resource data, specified as follows:

Property Name	Type	Meaning
`url`	`string`	Base url of the service to contact to retrieve the resource data.
`path`	`string`	Path of the specific endpoint to contact to retrieve the resource data.

Platform services configuration

The platform-services section contains all the information related to the platform services.

Property Name	Type	Meaning
`base-url`	`string`	Base url of the service to contact to retrieve the resource data. This must contain a string in the form `http(s)://{host}`
`http-secret`	`string`	Secret used to authenticate the HTTP requests.
`environments`	`object`	Subsection containing the environments configuration.
`auth`	`object`	Subsection containing the authentication configuration.

Environments configuration subsection

The environments configuration section consists of an object containing the following fields:

Property Name	Type	Meaning
`environments-path`	`string`	The path to the endpoint that returns the list of environments.
`environments-fetch-retries`	`int`	The number of retries to fetch the environments with exponential backoff.

Environments will be pulled at WCG startup and will be used to evaluate policies against the resources.

Audit configuration subsection

The audit configuration section consists of an object containing the following fields:

Property Name	Type	Meaning
`enabled`	`bool`	By setting this to `false`, auditing will not be performed
`audit-path`	`string`	The path of the endpoint that receives audit events.

Computational governance auditing can be enabled or disabled by editing this configuration section.
When enabled is set to false, auditing is completely disabled for all user operations. When enabled, the platform automatically collects audit logs for all REST API invocations performed by users.

note

audit-path should exclude the final endpoint.
For example, if the full audit URL is http://localhost:7007/api/audit/audit, and the platform service base URL is http://localhost:7007, set audit-path to /api/audit.

Authentication configuration subsection

The auth configuration section consists of an object containing the following fields used to configure Service Account and Technical JWT authentication:

Property Name	Type	Meaning
`cache-size`	`int`	The maximum number of keys stored on the internal cache that stores the JWKS (JSON Web Key Set) used to verify Service Account JWTs
`cache-duration`	`duration`	Duration of an entry of the JWKS cache before it's removed from the cache
`backend-secrets`	`list[string]`	List of backend secrets used to verify a Technical JWT.
`basic-auth`	`object`	Configuration section for the Basic Authentication support

Computational Governance uses an internal cache to store the JWKS exposed by Witboost and used to verify Service Accounts JWTs. This cache is refreshed only when a request is made with a JWT signed with an unknown key.

For Technical Tokens, a list of backend secrets is used by the Computational Governance to attempt to verify incoming JWTs. These secrets are defined on the Witboost main configuration ui.appConfig.backend.auth.keys and should be replicated here as a list of strings.

Basic Authentication configuration subsection

The basic-auth configuration section allows you to enable Basic Authentication for WCG APIs as an additional authentication method.

Property Name	Type	Meaning
`enabled`	`boolean`	Enables/Disables Basic Authentication as WCG APIs authentication method. By default is disabled.
`short-lived-token-duration-seconds`	`int`	Duration of the JWT token exchanged with the Access Token provided in the Basic Auth scheme

Evaluation configuration

The evaluation configuration section configures evaluation execution. All fields are optional and fall back to their default values if omitted.

Property Name	Type	Default	Meaning
`enable-on-publish`	`bool`	true	If true, starts an evaluation against all resources and environments whenever a policy is published.
`task-timeout`	`duration`	20 seconds	Maximum allowed duration for each evaluation task. If the evaluation of a governance entity against a single resource exceeds this timeout, the operation is interrupted.
`thread-pool-size`	`int`	32	Number of threads in the evaluation execution pool. Increase for higher throughput; decrease to limit resource usage.

When enable-on-publish is true, publishing a policy (transitioning its status to enabled) triggers an asynchronous evaluation of that policy against all resources and environments, so that reports and results are immediately up to date. Set it to false to skip this automatic evaluation step.

task-timeout and thread-pool-size govern the performance characteristics of the evaluation engine: the former caps how long a single evaluation task can run before being interrupted, while the latter controls the degree of parallelism by setting the size of the thread pool used to execute tasks concurrently.

Database configuration

The WCG needs to store persistent data inside a database. The database section of the configuration is required to specify all the information to successfully connect to the database instance:

Property Name	Default	Type	Meaning
`schema`	cgp	`string`	The database schema name that will be used.
`driver`	org.postgresql.Driver	`string`	The driver used to access to the database.
`url`	(none)	`string`	The url used to access to the database.
`username`	(none)	`string`	The username used to access to the database.
`password`	(none)	`string`	The password used to access to the database.
`name`	provisioning_coordinator	`string`	The database name to connect to.
`host`	(none)	`string`	The host in which the database is deployed.
`port`	5432	`int`	The port used to locate the database.
`migrate-on-start`	true	`bool`	If true, the database will be initialized with the content of the migration file.
`repair-on-start`	false	`bool`	If true, it overwrites the current database structure with a new one.
`thread-pool-size`	(none)	`int`	The number of threads that can be reused.
`connection-timeout`	(none)	`string`	The amount of time after which the connection will be closed.
`max-lifetime`	(none)	`string`	The maximum possible lifetime of a connection in the pool.
`leak-detection-threshold`	(none)	`string`	The amount of time that a connection can be out of the pool before a message is logged indicating a possible connection leak.

HTTP configuration

http section of the configuration.

Property Name	Default	Type	Meaning
`port`	8090	`int`	Port CGP's HTTP server listens on.
`external-http-pool-size`	4	`int`	Maximum number of simultaneous outbound HTTP connections in the client connection pool.
`client-connect-timeout`	10 seconds	`duration`	Timeout to be used when opening a communications link with an external HTTP resource. If the timeout expires before the connection can be established, an exception is raised. A timeout of zero is interpreted as an infinite timeout.
`client-read-timeout`	45 seconds	`duration`	A non-zero value specifies the timeout when reading from an external HTTP resource. If the timeout expires before there is data available for read, an exception is raised. A timeout of zero is interpreted as an infinite timeout.

TLS / SSL

Configure these when enabling mutual TLS between CGP and external services.

How-to guide

For a full step-by-step walkthrough — including certificate creation, secret manager setup, and Helm configuration — see How to enable mTLS for the Computational Governance Platform.

Property Name	Default	Type	Meaning
`client-certificate-path`	(none)	`string`	Path to the PKCS#12 file that contains the client SSL certificate
`client-certificate-password`	(none)	`string`	Password for the client certificate file
`client-server-certificate-no-check`	false	`bool`	When true, skips server certificate verification for outgoing TLS connections
`server-certificate-path`	(none)	`string`	Path to the PKCS#12 file that contains the server SSL certificate (used when `server-tls-on` is true)
`server-certificate-password`	(none)	`string`	Password for the server certificate file
`server-tls-on`	false	`bool`	Enables TLS on CGP's own HTTP server
`tls-client-bypass-ca-filtering`	false	`bool`	When true, ignores the server-provided list of acceptable certificate issuers when acting as a TLS client. This is useful in mutual TLS scenarios where the server restricts acceptable CAs (via the "certificate_authorities" TLS extension) but the client holds a certificate issued by a different (e.g. internal) CA

Cron policies configuration

The cron-policies section refers, as the name suggests, to the configuration related to cron policies. A cron policy is a particular type of runtime policy that has been scheduled to be executed with a given frequency, specified by a cron expression, associated to it.

Property Name	Type	Meaning
`reload-on-start`	`bool`	If true, at each start of the service, it will identify all the enabled and executable cron policies and schedule them based on their cron expression. Otherwise, the scheduler will only work with pre-existent cron policies, already scheduled before the last service start.

Cue configuration​

Events configuration​

Notification configuration​

Breaking change configuration​

Resource type configuration​

Configuration subsection​

Resolver configuration subsection​

Platform services configuration​

Environments configuration subsection​

Audit configuration subsection​

Authentication configuration subsection​

Basic Authentication configuration subsection​

Evaluation configuration​

Database configuration​

HTTP configuration​

TLS / SSL​

Cron policies configuration​