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

For the migration, use the service catalog item, Migrate configurations. You must run it once for each promoted plugin for which a custom configuration exists at your site.

To access this catalog item:

From the main menu, select Service catalog. The service catalog displays.
From the All service catalogs dropdown in the upper right, select Plugin configurations. The Migrate configurations tile displays.
Select Migrate on the Migrate configurations tile. The Migrate configurations dialog opens.

Enter the required information for your configuration, repeating this step for each configuration that you need to migrate.

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-separated 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 version.
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.

Select OK to migrate the plugin configurations.

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 plugin configurations

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