Create plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them. The following steps illustrate how to create a plugin configuration that can be used by one or more plugin procedures.

Plugin configurations are stored in CloudBees CD/RO as first-class objects. The access to these configurations can be managed individually. For more information about plugin configurations and procedures, along with use cases and plugin release notes, refer to CloudBees CD/RO plugins.

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. For more information, refer to Migrate legacy plugin configurations.

Create a plugin configuration using the CloudBees CD/RO UI

You can create plugin configurations using the CloudBees CD/RO UI.

To create a plugin configuration:

Navigate to DevOps Essentials Plugin Management Plugin configurations.
Select Add plugin configuration to create a new configuration.
In the New Configuration window, specify a Name for the configuration.
Select the Project that the configuration belongs to.
Optionally, add a Description for the configuration.
Select the appropriate Plugin for the configuration.
Configure the plugin configuration parameters. For more information, refer to CloudBees CD/RO plugins.
Select OK.

Depending on your plugin configuration and how you run procedures, the Input parameters Configuration name field may behave differently in the CloudBees CD/RO UI. For more information, refer to Differences in plugin UI behavior.

Create a plugin configuration using the CloudBees CD/RO REST API, DSL, or `ectool`

You can create plugin configuration objects using the CloudBees CD/RO REST API, DSL, or ectool. 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, and token_credential. In this example, authType = token is used with a 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 you can use a credential reference to use an existing credential in the plugin configuration:

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

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

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

Configure access control lists

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

To configure ACLs:

Assume you 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 is not able to access it.

For this, we are going to grant the Allow privilege to the u1 user:

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

When trying to run a plugin procedure from the u2 user, the following error is received:

[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'▼

However, the procedure finishes successfully for the u1 user.

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

Migrate legacy plugin configurations

As of CloudBees CD/RO release 23.02.0, the legacy CloudBees plugin manager is deprecated. Any plugin using a legacy model should be migrated to the Plugin Developer Kit (PDK) configuration model to continue support.

For more information on migrating plugins, refer to Migrate legacy plugins to PDK.

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. The best practice is for the CloudBees CD/RO admin to perform the migration.

Create plugin configurations

Create a plugin configuration using the CloudBees CD/RO UI

Create a plugin configuration using the CloudBees CD/RO REST API, DSL, or ectool

Configure access control lists

Migrate legacy plugin configurations

Create a plugin configuration using the CloudBees CD/RO REST API, DSL, or `ectool`