Computational Governance Platform Configuration

The Computational Governance Platform (CGP) 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"
            }
        }
    ]

    environments = [
        {
            name = "prod"
        },
        {
            name = "dev"
        }
    ]
    
    evaluation = {
        enable-on-publish = true
    }

    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 Computational Governance Platform to send events to the witboost events plugin.

Property Name	Type	Meaning
`enabled`	`boolean`	If `true` enables the events generation from the Computational Governance Platform
`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 Backstage notification service. This is used to send notifications to users of a certain Backstage 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 `app-config.yaml` file of the UI project, under the path `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 CGP 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	Meaning
`name`	`string`	Unique resource type name and identifier.
`display-name`	`string`	Resource type display name. It defaults to `name` if not provided.
`configuration`	`object`	Subsection containing resource type settings.
`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	Meaning
`resource-name`	`string`	Field inside the resource descriptor that contains its unique identifier.
`resource-display-name`	`string`	List of fields in the resource descriptor to be used to generate a display name.
`resource-filter`	`string`	Field inside the resource descriptor used to differentiate evaluation results for the same resource.
`batch-size`	`string`	Maximum number of resources requested to the perimeter resolver per request (page size).

Example:

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

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.

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.

Environments configuration

The environments configuration section consist of an array of objects, each one specifying the environment name. It is important to highlight that since the governance policy UI relies on the information owned by the builder and the other components, to avoid inconsistencies across the platform, the environment list specified here must match the one provided in the builder configuration and all the other components involved.

In fact, when a user utilizes the UI, the environment list shown is the one from the builder. As a result, when the CGP is called, it will receive information related to them, so we are expecting to have the same environments on the CGP backend side.

Property Name	Type	Meaning
`name`	`string`	Environment name.

Evaluation configuration

The evaluation configuration section consists of an object containing a boolean field called enable-on-publish. If the above field is true, whenever a user publish a policy (so the status of a policy changes from whatever to enabled), CGP runs an async evaluation for that policy against all the resources and all the environments. This is done in order to update the report (and related results) for that policy.

If enable-on-publish is false, it skips the evaluation phase on publish.

This configuration is optional since you can avoid insert it and obtain the default behaviour (always run the evaluation on publish).

Property Name	Type	Meaning
`enable-on-publish`	`bool`	If true it starts an evaluation when a policy is published.

Database configuration

The CGP 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	Type	Meaning
`schema`	`string`	The database schema name that will be used.
`driver`	`string`	The driver used to access to the database.
`url`	`string`	The url used to access to the database.
`username`	`string`	The username used to access to the database.
`password`	`string`	The password used to access to the database.
`name`	`string`	The database name to connect to.
`host`	`string`	The host in which the database is deployed.
`port`	`int`	The port used to locate the database.
`migrate-on-start`	`bool`	If true, the database will be initialized with the content of the migration file.
`repair-on-start`	`bool`	If true, it overwrites the current database structure with a new one.
`thread-pool-size`	`int`	The number of threads that can be reused.
`connection-timeout`	`string`	The amount of time after which the connection will be closed.
`max-lifetime`	`string`	The maximum possible lifetime of a connection in the pool.
`leak-detection-threshold`	`string`	The amount of time that a connection can be out of the pool before a message is logged indicating a possible connection leak.

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.

Computational Governance Platform Configuration

Cue configuration​

Events configuration​

Notification configuration​

Breaking change configuration​

Resource type configuration​

Configuration subsection​

Resolver configuration subsection​

Environments configuration​

Evaluation configuration​

Database configuration​

Cron policies configuration​