Creating plugin configurations

4 minute readAutomation

Plugins can have one or more configurations created and managed by CloudBees CD/RO. Plugin configuration management allows users to create custom configurations that manage several aspects, including:

  • Configuation name

  • Descriptions

  • Default values

  • Determine whether a parameter is required or optional

  • Access control of a configuration

Plugin configurations are now stored in CloudBees CD/RO as first class objects. The access to these configurations can be managed individually. All CloudBees supported CloudBees CD/RO plugins will eventually support creation of plugin configurations as first class objects. Check CloudBees CD/RO release notes for up-to-date information.

Note: The CloudBees CD/RO UI does not currently support creation of the plugin configuration as first class object. However all plugins will continue to support the legacy plugin configuration method. As a result there should be no impact to existing procedures and pipelines using the legacy configurations.

Migrating plugin configurations

If you are migrating to CloudBees CD/RO v10.3 or later from a pre-v10.3 version, you must perform a one-time migration for each plugin configuration at your site.
The user performing the migration must have the full set of permissions on the plugin project that is being migrated. Best practice is for the CloudBees CD/RO admin to perform the migration.

Use the service catalog item, Migrate configurations, for the migration. You run it once for each promoted plugin for which a custom configuration exists at your site. To access this catalog item:

  1. Navigate to the Service catalog: from CloudBees CD/RO banner, select Service catalog. The service catalog displays.

  2. From the All Catalogs dropdown list in the upper right, select Plugin configurations. The Migrate configurations tile displays.

  3. Select Migrate on the Migrate configurations tile. The Migrate configurations dialog displays.

From here, use the dialog to iterate through your configurations. One or more configurations can be specified for a given plugin. The migration process creates a set of helper procedures in the plugin project that are removed after the migration is complete.

  • Configuration names: A newline-separate list of configuration names to migrate for the specified plugin. If not provided, all configurations for the specified plugin are migrated. To rename the configuration, specify the name mapping with JSON as {"oldName": "newName"}; otherwise, the migrated configuration has the same name as the older verion.

  • Plugin name: The name of the plugin to migrate configurations, for example, EC-JIRA. The plugin must be promoted before its configuration can be migrated.

  • Project name: The CloudBees CD/RO project to host the migrated configurations.

Creating a plugin configuration

Create plugin configuraton objects using the CloudBees CD/RO REST API, DSL, or ectool as shown in the examples below. The example below creates a configuration for the EC-Git plugin.

Creating a new plugin configuration depends on the parameters supported by the plugin. For the list of available fields, consult the procedure named ConfigurationParametersHolder located in the plugin’s project. For EC-Git, we have fields like authType, credential, token_credential, and more.

We will be using authType = token with token credential.

This DSL creates a plugin configuration named git-config in a project named p1.

project 'p1', {
    pluginConfiguration 'git-config', {
        pluginKey = 'EC-Git'

        field = [
            library: 'jgit',
            authType: 'token'
        ]

        addCredential 'token_credential', {
            userName = ''
            password = 'my token'
        }
    }
}

Or, alternatively we can use a credential reference to use an already existing credential in our plugin configuration:

project 'p1', {
    pluginConfiguration 'git-config', {
        pluginKey = 'EC-Git'

        field = [
            library: 'jgit',
            authType: 'token'
        ]

        credentialReferenceParameter ['token_credential': '/projects/creds/credentials/gitToken']
    }
}

As noted above, the UI does not yet support the configurations as first class objects. To create a configuration from the UI, select the Configure option from the Plugin menu and then select the Create Configuration link. This runs the plugin’s createConfiguration procedure. Here is a sample parameter view for one of the plugins:

Using plugin configuration

Let’s create a pipeline and use the EC-Git procedure Clone. The available plugin configurations is accessible through the Configuration Name dropdown list. Note that on expansion, the full path to the configuration in the form /projects/<projectName>/pluginConfigurations/<pluginConfigurationName>, for our case it is /projects/p1/pluginConfigurations/git-config.

ACL inheritance

Since the plugin configuration is part of the project, by default plugin configuration objects inherit the ACLs from the CloudBees CD/RO project. The configurations consist of non-secret fields and secret credentials. When a plugin fetches a configuration, it first gets the configuration object itself and then gets credential in the configuration. In order to modify the configuration fully, modify permission must be set on both configuration object and the underlying credentials. In order to make this easier all ACLs applied to the plugin configuration objects are automatically applied to the underlying credentials by CloudBees CD/RO.

Setting ACL

Let’s assume we have two users: u1 and u2 in groups g1 and g2, respectively. User u1 is going to have access to the configuration while user u2 will not be able to see it.

For this, we are going to grand allow privilege to the user u1:

ectool createAclEntry group  g1 --projectName p1 --pluginConfigurationName git-config --readPrivilege allow

When trying to run a plugin procedure from user u2, we will get this error:

[BAILED OUT]: Plugin step clone execution was finished with an error: Error [AccessDenied]: None of the principals in this authentication context ('u2', 'project: CloudBees') have read privilege on pluginConfiguration 'git-config'

Caught: java.lang.RuntimeException: Error [AccessDenied]: None of the principals in this authentication context ('u2', 'project: CloudBees') have read privilege on pluginConfiguration 'git-config'

While the procedure will finish successfully for the user u1.

Both users and projects can have permissions on the plugin configuration objects. By default, group Everyone has read access everywhere, and you need to disable this access in order to set granular permissions.