DslDeploy plugin

CloudBees CD/RO allows you to take a fully code-native approach to continuous delivery and release orchestration using the CloudBees CD/RO Groovy-based Domain Specific Language (DSL). The CloudBees CD/RO model-based approach means that every object in CloudBees CD/RO, including release pipelines, deployment automation and strategies, environments, configurations, and application models are all backed by code.

The DslDeploy plugin makes it easy to synchronize CloudBees CD/RO DSL code with your local repository, allowing you to treat your pipeline as a product, making it versionable, testable, and reusable, exactly like your application code. This plugin maintains your code in a file structure that maps directly to the CloudBees CD/RO model-based structure, making it easy to reuse, collaborate, and maintain. It supports:

Management of all CloudBees CD/RO objects as code.
Per-project synchronization.
The use of .dsl and .groovy extensions.
The ability to create generic DSL files.
Artifacts to support CloudBees CD/RO code-promotion pipelines.
Continuous integration (CI) support for your DEV environment.
Compatibility with the ectool CLI.

Updated Perl version required

This plugin uses an updated version of Perl, cb-perl shell (Perl v5.32), and requires CloudBees CD/RO agents version 10.3+ to work.

Plugin Version 4.3.1.2024032795

Create DslDeploy plugin procedures

Plugin procedures can be used in procedure steps, process steps, and pipeline tasks, allowing you to orchestrate third-party tools at the appropriate time in your component, application process, or pipeline.

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.

InstallDsl

Deploy a DSL file structure from an artifact version on your CloudBees CD/RO server.

Parameter Description

Artifact Name

Required. The name of your artifact.

Artifact Version

The version of the artifact you want to deploy. If left empty, the latest version is deployed.

Use an empty version only in your Dev environment. In higher environments, it is recommended that you use a specific version that has been tested in lower environments.

Server Pool or Resource

Required. The name of the pool or resource where the artifact is retrieved. The DSL is evaluated on the server so all system actions, such as file reads, are evaluated on a server node. The default value is local.

Retrieve on all server nodes

Required. If selected, the artifact version is retrieved on all nodes and the system selects a random server node for each action. This can be useful when running in a cluster with a local workspace and can be used in conjunction with a resource pool to cover all server node agents. The default is false.

Overwrite mode

If selected, overwrite mode is enabled and if the object exists, all attributes and child objects are overwritten by the values in the DSL files.

InstallDslFromDirectory

Deploys a DSL file structure from a directory on your CloudBees CD/RO server. This procedure’s main usage is to set up a CI process. It extracts your code from your source control tool to a local directory on your Dev CloudBees CD/RO server, and then deploys it.

Input parameters

Parameter Description

Directory Path

Required. The location of the DSL code on your Dev CloudBees CD/RO server.

Server Pool or Resource

Required. The name of the pool or resource where the artifact is retrieved. Use . if you have retrieved it in your workspace.

Overwrite mode

If selected, overwrite mode is enabled and if the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Additional argument(s)

Additional arguments, such as --timeout or --debug, used for evalDsl tools. Values used in --timeout are used as timeouts for ectool, evalDsl, and the job step timeout used to import the DSL.

Ignore failures

Ignore failures during the import of DSL files.

Local mode

Do not send files to the server with the help of the clientFiles argument of the evalDsl operation in local mode.

Include objects

Newline-separated list of paths to objects to synchronize. If set, only these objects are synchronized. If empty, all available objects are synchronized.

Examples:

/projects - All projects
/projects/Default/applications - All applications in project Default
/users - All users
/projects/Commander/procedures/Master - Master procedure in the Commander project.
/projects/*/releases - All releases in all projects

Objects with a depth greater than two are not supported. For example:

/projects/*/releases/release1
/projects/Default/application/application1/applicationTiers

Exclude objects

Newline-separated list of paths to exclude (refer to Include objects for examples). By default, nothing is excluded.

InstallDslFromDirectory input example

In the following InstallDslFromDirectory input example, /projects is being used to install the projects catalogTest, testProject, and testPipeLine.

├── projects
    ├── catalogTest
    │   ├── catalogs
    │   │   └── Test\ Catalog
    │   │       ├── catalog.dsl
    │   │       └── catalogItems
    │   │           └── Service\ OnBoarding
    │   │               └── catalogItem.dsl
    │   ├── procedures
    │   │   └── catalogProcedure1
    │   │       ├── procedure.groovy
    │   │       └── steps
    │   │           └── echo.pl
    │   └── project.groovy
    ├── testProject
    │   ├── procedures
    │   │   └── testProcedure1
    │   │       ├── procedure.groovy
    │   │       └── steps
    │   │           └── echo.pl
    │   ├── project.groovy
    │   └── properties
    │       └── prop1.txt
    └── testPipeline
        ├── pipelines
        │   └── UC1
        │       └── pipeline.groovy
        └── project.groovy▼

InstallProject

Deploys the DSL file structure from a directory on your CloudBees CD/RO server as a project. The main purpose of the procedure is to be a part of the InstallDslFromDirectory procedure.

Input parameters

Table 2. InstallProject input parameters
Parameter	Description
Project Name	Name of the project to install.
Project directory	Location of the project DSL code on your `Dev` CloudBees CD/RO server.
Overwrite mode	If selected, overwrite mode is enabled and if the object exists, all attributes and child objects are overwritten by the values in the DSL files.
Additional argument(s)	Additional arguments, such as `--timeout` or `--debug`, used for `evalDsl` tools. Values used in `--timeout` are used as timeouts for `ectool`, `evalDsl`, and the job step timeout used to import the DSL.

InstallProject input example

In the following InstallProject input example, is a sample directory structure to install a project. In this example, project1 contains two procedures: procedure1 and procedure2.

project1
├── procedures
│   ├── procedure1
│   │       ├── procedure.groovy
│   │       └── steps
│   │           └── echo.pl
│   └── procedure2
│       ├── procedure.groovy
│       └── steps
│           └── echo.pl
├── project.groovy
└── properties
    └── prop1.txt▼

GenerateDslToDirectory

Exports DSL for a top-level CloudBees CD/RO object, with options for the child objects and values to include. For ease of editing and management, export the DSL in separate files in a directory tree representing the object hierarchy.

Input parameters

Table 3. GenerateDslToDirectory input parameters
Parameter	Description
Directory path	Required. Folder where the code is generated.
Server Pool or Resource	Required. Server pool to use for a cluster setup.
Object Type	Required. Object type to generate DSL for.
Object Name	Required. Object name to generate DSL for.
Suppress Nulls	Exclude from the generated DSL properties with a null value.
Suppress Defaults	Exclude from the generated DSL properties with a default value.
Suppress Parent	Exclude the object parent from the generated DSL properties.
Include ACLs	Include in access control lists (ACLs) for objects.
Include All Children	Include in the generated DSL for all object children. If `True`, the value of the `Include Children` parameter is ignored.
Include children	Comma-separated list of object children the DSL should be generated for.
Include Children in Same File	Include in the generated DSL all object children. If `True`, the value of the `Include Children` parameter is ignored.
Children in Different Files	Comma-separated list of patterns to include (for example, `pipelines, procedures.*, applications.applicationTiers.components`).

GenerateDslToDirectory project output example

In the following GenerateDslToDirectory output example, the directory structure is generated for an example testProject1 project into a /tmp/dsl directory.

/tmp/dsl
├── projects
│   ├── testProject1
│   │   ├── acls
│   │   │   └── acl.dsl
│   │   ├── procedures
│   │   │   ├── testProcedure1
│   │   │   │   ├── acls
│   │   │   │   │   └── acl.dsl
│   │   │   │   ├── procedure.dsl
│   │   │   │   ├── properties
│   │   │   │   │   ├── testProperty1
│   │   │   │   │   │   └── property.dsl
│   │   │   │   │   ├── testProperty1.txt
│   │   │   │   │   └── testPropertySheet1
│   │   │   │   │       ├── propertySheet.dsl
│   │   │   │   │       ├── testProperty2
│   │   │   │   │       │   └── property.dsl
│   │   │   │   │       └── testProperty2.txt
│   │   │   │   └── steps
│   │   │   │       ├── metadata.json
│   │   │   │       ├── testStep1
│   │   │   │       │   ├── acls
│   │   │   │       │   │   └── acl.dsl
│   │   │   │       │   └── step.dsl
│   │   │   │       ├── testStep1.cmd
│   │   │   │       ├── testStep2
│   │   │   │       │   ├── acls
│   │   │   │       │   │   └── acl.dsl
│   │   │   │       │   └── step.dsl
│   │   │   │       └── testStep2.cmd
│   │   │   └── testProcedure2
│   │   │       ├── acls
│   │   │       │   └── acl.dsl
│   │   │       ├── procedure.dsl
│   │   │       ├── properties
│   │   │       │   ├── testProperty1
│   │   │       │   │   └── property.dsl
│   │   │       │   ├── testProperty1.txt
│   │   │       │   └── testPropertySheet1
│   │   │       │       ├── propertySheet.dsl
│   │   │       │       ├── testProperty2
│   │   │       │       │   └── property.dsl
│   │   │       │       └── testProperty2.txt
│   │   │       └── steps
│   │   │           ├── metadata.json
│   │   │           ├── testStep1
│   │   │           │   ├── acls
│   │   │           │   │   └── acl.dsl
│   │   │           │   └── step.dsl
│   │   │           ├── testStep1.cmd
│   │   │           ├── testStep2
│   │   │           │   ├── acls
│   │   │           │   │   └── acl.dsl
│   │   │           │   └── step.dsl
│   │   │           └── testStep2.cmd
└───└───└── project.dsl▼

GenerateDslToDirectory resources output example

In the following GenerateDslToDirectory output example, the directory structure is generated for two example resources, testResource1 (line 3) and testResource2 (line 16) into a /tmp/dsl directory.

/tmp/dsl
├──resources
├── testResource1
│   ├── acls
│   │   └── acl.dsl
│   ├── properties
│   │   ├── testProperty1
│   │   │   └── property.dsl
│   │   ├── testProperty1.txt
│   │   └── testPropertySheet1
│   │       ├── propertySheet.dsl
│   │       ├── testProperty2
│   │       │   └── property.dsl
│   │       └── testProperty2.txt
│   └── resource.dsl
└── testResource2
├── acls
│   └── acl.dsl
├── properties
│   ├── testProperty1
│   │   └── property.dsl
│   ├── testProperty1.txt
│   └── testPropertySheet1
│       ├── propertySheet.dsl
│       ├── testProperty2
│       │   └── property.dsl
│       └── testProperty2.txt
└── resource.dsl▼

ImportDslFromGit

This procedure is deprecated and relies on the ECSCM-Git plugin, which is no longer supported. Unless you have legacy installations of CloudBees CD/RO, you should not use the ImportDslFromGit procedure and use ImportDslFromGitNew instead.

Imports the DSL file structure from a Git repository to set up a CI process.

Input parameters

Parameter Description

Server Resource

Required. The resource where the DSL files are checked out from Git and imported to the CloudBees CD/RO server.

Destination Directory

Required. The directory on the resource where the source tree is created and from where the DSL files are read to be imported in the CloudBees CD/RO server.

Relative path to DSL files

If the DSL files are not located at the top-level in the repository, then specify the relative path to the directory containing the DSL files within the repository.

Cleanup?

Deletes the destination directory with the source tree after job execution.

Overwrite mode

If selected, overwrite mode is enabled and if the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Configuration

Required. Name of a saved source control configuration.

Git repository

Required. URL to the repository to pull from (for example, git://server/repo.git).

Commit Hash

The Git commit hash to update the index.

This moves the HEAD.

Remote Branch

The name of the Git branch to use (for example, my_feature).

Clone?

Clones a repository into a newly created directory.

Overwrite?

Overwrites a repository if it already exists.

Depth

Creates a shallow clone with a history truncated to the specified number of revisions.

Tag

Provide the name of a specific tag to check out after the clone command.

Ignore failures

Ignore failures during import of DSL files.

Local mode

Do not send files to the server with the help of the clientFile`s argument of the `evalDsl operation in local mode.

Additional DSL Arguments

Additional argument for the evalDsl call.

ImportDslFromGitNew

Imports the DSL file structure from a Git repository to set up a CI process.

This procedure uses the Git plugin.
When using the ImportDslFromGitNew procedure, the count of imported entities does not increment for manually modified DSL files. The plugin expects each DSL file to contain one CloudBees CD/RO entity, which is how DSL files are generated by the plugin itself, and the count of entities is based on this format.

Input parameters

Parameter Description

Server Pool or Resource

Required. Resource or one of the pool resources where the DSL files are checked out from Git and imported to the CloudBees CD/RO server.

Destination Directory

Required. The directory on the resource where the source tree is created and the DSL files are stored.

Relative path to DSL files

If the DSL files are not located at the top-level in the repository, then specify the relative path to the directory containing the DSL files within the repository. For example, scripts/dsls is where the DSL files are located in the following subdirectories in the repository: scripts/dsls/projects and scripts/dsls/resources.

Cleanup?

This option deletes the destination directory with the source tree after job execution.

Overwrite mode

If selected, overwrite mode is enabled and if the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Configuration

Required. The EC-Git plugin configuration name.

Git repository

Required. URL to the repository to pull from (for example, git://server/repo.git).

Remote Branch

The name of the Git branch to use (for example, experimental).

Ignore failures

Ignore failures during import of DSL files.

Local mode

Does not send files to the server with the help of the clientFiles argument of the evalDsl operation when in local mode. Available only if the destination directory is accessible from the CloudBees CD/RO server. In a clustered deployment, all CloudBees CD/RO server nodes must have access to this directory.

Additional argument(s)

Include objects

New line separated list of paths to objects to synchronize. If set, only these objects are synchronized. If empty, all available objects are synchronized.

Paths can refer to collections or specific objects, but the maximum depth is 2.
- Supported examples:
  - /projects - All projects
  - /projects/Default/applications - All applications in project Default
  - /users - All users
  - /projects/Commander/procedures/Master - Master procedure in Commander project
  - /projects/Default/application/demoApp - demoApp application in Default project
- Unsupported example that exceeds depth:
  - /projects/Default/application/application1/applicationTiers
Wildcards can be used for first-level objects if the max depth is ≤ 2 and the path refers to a collection.
- Supported examples:
  - /projects/*/releases - All releases in all projects
- Unsupported examples:
  - /projects/Default/*/release1 - Wildcard not used on first-level object
  - /projects/*/releases/release1 - Exceeds max depth of 2.

Exclude objects

Newline-separated list of paths to exclude (refer to Include objects for examples). By default, nothing is excluded.

Incremental import

If selected, only incremental changes that have occurred since the previous run of the procedure are imported, the previous run’s commit ID is compared to the current commit ID in the Git repository, and a change list is created. This can potentially reduce the import time because the entire DSL file structure is not re-imported from the Git repository each time the procedure runs.

If the Git commit ID cannot be found or if the procedure or steps cannot find, read, or correctly parse the change list, the entire DSL file structure is re-imported.

DslDeploy plugin release notes

4.3.1

Added child process entities support for the microservice container entity.

4.3.0

Updated Perl from legacy ec-perl (5.8.9) to cb-perl (5.32.1).

4.2.2

Fixed an issue where the plugin could incorrectly not set warning statuses in job steps. If warnings occurred, the plugin attempted to set the status, which would result in a failure of the complete job.
Fixed an issue with setting the job step status in overwrite mode during DSL evaluation.

4.2.1

Fixed an issue with importing environment reservations.
Added support for a new suppressEmpty option to the generateDsl plugin procedure.

4.2.0

Added the httpIdleTimeout argument to the generateDsl plugin procedure.
Fixed import issue with entity names that contain special characters in overwrite mode.
Improved logging in the GenerateDslToDirectory procedure for properties and property sheets.
Fixed an issue with the timeout argument in the GenerateDslToDirectory procedure.
Fixed an import issue for CloudBees CD/RO entities with names that contain punctuated characters.
Fixed an issue with importing new properties in overwrite mode.

4.1.11

Fixed a regression with multiline property value generation.

4.1.10

A regression was introduced in version 4.1.10. Do not use this version.

4.1.9

Fixed a regression with multiline property value generation.

4.1.8

Added support to run the importDslFromGitNew subprocedure for the EC-DslDeploy plugin.
Fixed an issue with importing non-project entities when a remote agent is used.

4.1.7

Added support for property detail information (for example, descriptions).
Fixed incremental imports in the importDslFromGitNew procedure when used as a subprocedure.
Instrumented EC-DslDeploy code to help debug performance issues when importing a release from a nested DSL file structure.

4.1.6

Added support for DSL import of completed releases.
Fixed incremental imports in the importDslFromGitNew procedure when it is used as a subprocedure.

4.1.5

Fixed a problem where an exception error could be returned during DSL import when using a service catalog item.

4.1.4

Fixed an issue with exceptions that should be retried.
Added support for service account objects.

4.1.3

Fixed issues that were caused by incremental import support.

4.1.2

Added support for overwrite mode in the main deploy step for single DSL files.
Added support for the import/export of triggers.

4.1.1

Internal improvements.

4.1.0

Enhanced the import procedure to perform partial/incremental import.

4.0.4

Internal improvements.

4.0.3

Fixed an issue with the importDslFromGitNew procedure where it did not proceed the additionalArguments property in the installDslFromDirectory step.

4.0.2

Fixed unexposed DSL import timeouts preventing large DSL imports.

4.0.1

Added configuration object support.

4.0.0

Added support for a new procedure to provide import from Git functionality using the EC-Git plugin.
Fixed command task contents duplicates for tasks contained in a task group.
Added metadata for GitSync and the scmType-level property sheet.
Fixed an issue with exports not generating the Groovy command task.
Removed the import of old services from the EC-DslDeploy plugin.
Fixed the import of DSL for projects with an application microservice model when all children are in separate files.

3.0.3

Added credentials import/export support.
Fixed files path to fix deletion issue on Windows.
Fixed the Relative path to DSL files parameter in importDslFromGit.

3.0.2

Added support triggers for import/export.

3.0.1

Fixed project import in the remote mode.

3.0.0

Renamed to "CloudBees".
Improved the speed of noop deploy steps.
Added support for ignoreFailed and localMode parameters for import procedures.
Added support for object names with slash and backslash (/ and \) symbols.
Fixed an issue that resulted in wrong counts in step summaries for import procedures.

2.2.1

The plugin has been updated to use the clientFiles argument in the evalDsl API, which allows the removal of the limitation of shared folder usage for DSL import.
Fixed an issue with importing the release property sheet under the project.
Fixed an issue for GenerateDslToDirectory with includeAcls='1'.

2.2.0

Added an Overwrite parameter to installation procedures.
Added support for the GenerateDslToDirectory procedure.
Added support for the importDslFromGit procedure.
Enhanced the installDsl procedure to support the deployment of more objects types.

2.1.3

Fixed an issue with . on DSL.

2.1.2

Converted deployMain and deployPost to EC-Perl.

2.1.0

Added ACLs support.

1.1.0

Added support for resources.

1.0.2

Refactored tests and added sample code for testing.
Refactored the InstallDsl and InstallDslFromDirectory procedures.

1.0.1

Remove the EC-Admin dependency.

1.0.0

First official version.