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

Procedures

For all parameter descriptions below, required parameters are shown in bold italics.

InstallDsl

Deploy a DSL file structure from an Artifact Version on your CloudBees CD/RO server.

Parameter Description

Parameter	Description
Artifact Name	Required. The name of your artifact.
Artifact Version	The version of the artifact you want to deploy. If empty, the latest version is deployed. NOTE: Use an empty version only in your `Dev` environment. In higher environments, it’s 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 will be retrieved. The DSL is evaluated on the server so all system actions, such as file reads, will be evaluated on a server node. Default value is `local`.
Retrieve on All server nodes	Required (By default, is set to false). Use this option when running in a cluster with a local workspace, as the artifact version needs to be retrieved on all nodes (as the system pick a random server node for each action). Use alongside a resource pool covering all server node agents for the parameter above. Default is `false`
Overwrite mode	Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Artifact Name

Required. The name of your artifact.

Artifact Version

The version of the artifact you want to deploy. If empty, the latest version is deployed. NOTE: Use an empty version only in your Dev environment. In higher environments, it’s 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 will be retrieved. The DSL is evaluated on the server so all system actions, such as file reads, will be evaluated on a server node.

Default value is local.

Retrieve on All server nodes

Required (By default, is set to false). Use this option when running in a cluster with a local workspace, as the artifact version needs to be retrieved on all nodes (as the system pick a random server node for each action). Use alongside a resource pool covering all server node agents for the parameter above.

Default is false

Overwrite mode

Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.

InstallDslFromDirectory

Deploy 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 SCM in a local directory on your Dev CloudBees CD/RO server, and deploys it.

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 will be retrieved. Use . if you have retrieved in your workspace.

Overwrite mode

Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Additional argument(s)

For evalDsl calls, additional arguments such as --timeout or --debug. Values used in --timeout are used as timeouts for ectool, evalDsl, and the job step time out used to import the DSL.

Ignore failures

Ignore failures during import of DSL files.

Local mode

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

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.

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/*/releases“ - all releases in all projects

Objects with depth > 2 are not supported. Examples:

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

Exclude objects

New line separated list of paths to exclude (See Include objects for examples). Exclude nothing by default.

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

Deploy DSL file structure from a directory on your CloudBees CD/RO server as a project.

The main purpose of the procedure to be a part of installDslFromDirectory procedure.

Parameter Description

Parameter	Description
Project Name	Name of the project to install.
Project directory	The location of the project DSL code on your `Dev` CloudBees CD/RO server.
Overwrite mode	Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.
Additional argument(s)	For evalDsl calls, additional arguments such as `--timeout` or `--debug`. Values used in `--timeout` are used as timeouts for ectool, evalDsl, and the job step time out used to import the DSL.

Project Name

Name of the project to install.

Project directory

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

Overwrite mode

Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Additional argument(s)

For evalDsl calls, additional arguments such as --timeout or --debug. Values used in --timeout are used as timeouts for ectool, evalDsl, and the job step time out used to import the DSL.

InstallProject input example

In the following InstallProject input example, you can see a sample directory structure to install a project. In this example, project1 project with the procedure1 and procedure2 procedure.

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

GenerateDslToDirectory

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

Parameter Description

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 null value.
Suppress Defaults	Exclude from the generated DSL properties with default value.
Suppress Parent	Exclude from the generated DSL properties referred to object parent.
Include ACLs	Include in ACLs for objects.
Include All Children	Include in the generated DSL all object children. If `True`, the value of the `Include Children` parameter is ignored.
Include children	A 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	A comma-separated list of patterns to include, like pipelines, procedures.`*`, applications.applicationTiers.components

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 null value.

Suppress Defaults

Exclude from the generated DSL properties with default value.

Suppress Parent

Exclude from the generated DSL properties referred to object parent.

Include ACLs

Include in ACLs for objects.

Include All Children

Include in the generated DSL all object children. If True, the value of the Include Children parameter is ignored.

Include children

A 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

A comma-separated list of patterns to include, like pipelines, procedures.*, applications.applicationTiers.components

GenerateDslToDirectory project output example

In the following GenerateDslToDirectory output example, you can see the directory structure generated for an example project, testProject1 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, you can see the directory structure 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 it and use ImportDslFromGitNew instead.

Import DSL file structure from a Git repository.

This procedure main usage is to set up a CI process.

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 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?

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

Overwrite mode

Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Configuration

Required. The name of a saved SCM configuration.

Git repository

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

Commit Hash

The 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?

This option will clone a repository into a newly created directory.

Overwrite?

This option will overwrite a repository if it already exists.

Depth

Create 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 help of clientFiles argument of the evalDsl operation in local mode.

Additional DSL Arguments

Additional argument for evalDsl call.

ImportDslFromGitNew

Import DSL file structure from a Git repository.

This procedure main usage is to set up a CI process.

This procedure uses the Git plugin.

When using ImportDslFromGitNew, 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 plugin itself, and the count of entities is based on this format.

Parameter Description

Server Pool or Resource

Required. The 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 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 the job execution.

Overwrite mode

Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files.

Configuration

Required. EC-Git 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

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

Additional DSL arguments

Additional argument(s) for the evalDsl call. For example, --timeout or --debug. Values used in --timeout are used as timeouts for ectool, evalDsl, and the job step timeout used to import the DSL.

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 max 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

New line separated list of paths to exclude (See Include objects for examples). Exclude nothing by default.

Incremental import

Select to only import the incremental changes that have occurred since the previous run of the procedure. When selected, 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 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.

Release notes

EC-DslDeploy 4.3.1

Add child process entities support for the microservice container entity

EC-DslDeploy 4.3.0

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

EC-DslDeploy 4.2.2

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

EC-DslDeploy 4.2.1

Fixed issue with import environment reservations
Supported new option 'suppressEmpty' in the 'generateDsl' plugin procedure

EC-DslDeploy 4.2.0

Added 'httpIdleTimeout' argument into the 'generateDsl' plugin procedure
Fixed import issue with entity names that contain special characters in the overwrite mode
Improved logging in the 'generateDslToDirectory' procedure for properties and property sheets
Fixed issue with 'timeout' argument in the 'generateDslToDirectory' procedure
Fixed import issue for CD entities with names contain punctuated characters
Fixed issue with import new properties in the overwrite mode

EC-DslDeploy 4.1.11

Fixed regression with multiline property values generation.

EC-DslDeploy 4.1.10

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

EC-DslDeploy 4.1.9

Fixed regression with multiline property values generation

EC-DslDeploy 4.1.8

Added support to run sub procedure 'importDslFromGitNew' for EC-DslDeploy plugin
Fixed issue with import non project entities in case remote agent is used

EC-DslDeploy 4.1.7

Added support for property detail information like description, etc
Fixed incremental imports in the importDslFromGitNew procedure when used as a subprocedure
Instrumented EC-DslDeploy code to help debug performance issue where importing a release from a nested DSL file structure

EC-DslDeploy 4.1.6

Added DSL import of completed releases - EC-DslDeploy side
Fixed incremental import in the importDslFromGitNew procedure when it is used as a subprocedure

EC-DslDeploy 4.1.5

Fixed exception during import DSL using service catalog item

EC-DslDeploy 4.1.4

Fixed issue with exceptions that should be retried
Added support for serviceAccount objects

EC-DslDeploy 4.1.3

Fixed issues caused by incremental import support

EC-DslDeploy 4.1.2

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

EC-DslDeploy 4.1.1

Internal improvements

EC-DslDeploy 4.1.0

Enhanced the import procedure to perform partial/incremental import

EC-DslDeploy 4.0.4

Internal improvements

EC-DslDeploy 4.0.3

Fixed importDslFromGitNew doesn’t proceed additionalArguments property into installDslFromDirectory step

EC-DslDeploy 4.0.2

Fixed unexposed DSL import timeouts preventing large DSL imports

EC-DslDeploy 4.0.1

Added configuration object support to DslDeploy plugin - plugin side

EC-DslDeploy 4.0.0

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

EC-DslDeploy 3.0.3

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

EC-DslDeploy 3.0.2

Support Triggers import/export

EC-DslDeploy 3.0.1

Fixed project import in the remote mode

EC-DslDeploy 3.0.0

The plugin is made CloudBees Supported and moved under the private repository
Speedup noop deploy steps
Added ignoreFailed and localMode parameters for import procedures
Added support for object names with slash and backslash symbols
Fixed wrong counts in step summary for import procedures

EC-DslDeploy 2.2.1

The plugin is adopted to use new clientFiles argument in evalDsl API what allows to remove limitation of shared folder usage for DSL import
Fixed issue with import of release property sheet under the project
Fixed issue for generateDslToDirectory with includeAcls='1'

EC-DslDeploy 2.2.0

Added overwrite parameter to install procedures
Added generateDslToDirectory procedure
Added importDslFromGit procedure
Enhanced installDsl procedure to support deploy of more types of objects

EC-DslDeploy 2.1.3

Fixed issue with . on DSL

EC-DslDeploy 2.1.2

Converted deployMain and deployPost to EC-Perl

EC-DslDeploy 2.1.0

Add ACLs support

EC-DslDeploy 1.1.0

Add support for resources.

EC-DslDeploy 1.0.2

Refactor tests and add sample code as test.
Refactored InstallDsl and installDslFromDirectory

EC-DslDeploy 1.0.1

Remove EC-Admin dependency.

EC-DslDeploy 1.0.0

First official version.