Use the CloudBees CD/RO domain-specific language (DSL)

4 minute readReferenceDeveloper productivity

Process-as-code, leveraging a CloudBees CD/RO domain-specific language (DSL), enables you to maintain your release orchestration and deployment model as code. You can store and version this code in a source control management system. Release managers, product teams, and engineering leaders can design and code release orchestration or deployment automation processes.

CloudBees CD/RO DSLs are intuitive, easy-to-use computer languages that allow you to model continuous delivery (CD) and application release automation (ARA) solutions. Key benefits are:

  • Easy to understand

  • Self-documenting

  • Automation-as-code: define your processes as high-level code that can be versioned, tested, and reused.

  • User-defined versions for any object, supporting various means of code reuse.

  • Simple, logical constructs to model any CloudBees CD/RO object.

  • Groovy-based syntax

  • YAML declarative syntax is a Preview feature.

In addition to enabling the creation and modification of CloudBees CD/RO objects, the CloudBees CD/RO DSL gives full access to the API through DSL methods. These APIs are the same as those available through ectool, Groovy, and Perl. Unlike Groovy, the DSL API methods can be used immediately without first importing packages or creating an ElectricFlow instance. For a list of available APIs and interface formats refer to the CloudBees CD/RO Perl API command overview.

The CloudBees CD/RO IntelliJ IDEA plugin allows the IntelliJ editor to create and modify CloudBees CD/RO projects, releases, and pipelines. This plugin leverages EvalDsl and GenerateDsl functionality to provide CloudBees CD/RO object editing in Groovy or YAML formats within the IntelliJ editors. Refer to Intellij IDEA plugin.

When to use Groovy vs. YAML DSL

YAML DSL format is a Preview feature.
A Preview feature:
  • Has not undergone end-to-end testing with CloudBees products

  • Is provided without service-level agreements (SLA) and therefore does not include CloudBees' commitment on functionality or performance

  • May impact other stable areas of the product when used

  • May have limited documentation

  • May not be feature complete during the Preview period

  • May graduate from preview state to fully supported or be removed from the product

  • May introduce incompatible, backward-breaking changes that could revoke the ability to upgrade

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

The Groovy DSL is a full feature language supporting the entire programming language and the CloudBees CD/RO API. For very sophisticated implementations, such as advanced self-service catalog items, this is the language to use. It is the language for dynamic parameter definitions. In contrast, YAML is better suited for capturing simpler objects such as releases or procedure definitions.

Why Use DSL?

CloudBees CD/RO DSL is the easiest of the CloudBees CD/RO programming constructs to use.

The following is a comparison of DSL (the easiest to use) and Perl scripts (the most difficult to use):

DSL Perl

Declarative (what)

Script-based, imperative (how)

Concise

Relatively verbose

Understanding of Groovy is not needed to read DSL.

Understanding of Perl required.

The entire DSL script is sent only once to the server for evaluation, reducing client-server chattiness.

Each API invocation is a separate call to the server, creating client-server chattiness.

The following examples show the helloProcedure in both DSL and Perl.

Groovy DSL
YAML
Perl
project "Hello Project", { procedure "Hello Procedure", { step "Hello World", command: "echo 'Hello World from CloudBees DSL!'" } }
apiVersion: cloudbees.com/v2023.2 kind: project metadata: name: Hello Project spec: procedures: - name: Hello Procedure steps: - name: Hello World command: echo Hello World from CloudBees YAML!
use strict; use ElectricCommander; $|=1; my $ec=new ElectricCommander({'format'=>'json'}); $ec->createProject("Hello Project"); $ec->createProcedure("Hello Project", "Hello Procedure"); $ec->createStep("Hello Project", "Hello Procedure", "echo'Hello World from Perl");

Below are the corresponding CloudBees CD/RO commands to run the script.

  • Groovy DSL: ectool evalDsl --dslFile helloProcedure.dsl

  • YAML: ectool evalDsl --format yaml --dslFile helloProcedure.yaml

  • Perl: ec-perl helloProcedure.pl

You create scripts to model the CloudBees CD/RO objects using the DSL methods and let the CloudBees CD/RO DSL engine take care of invoking the correct API to create or update the object. DSL scripting is based on the Groovy scripting language; however, you do not need to know Groovy in detail to use it.

The benefits of using DSL scripts are:

  • Create one master model or script and run it one or more times for different scenarios to build, test, and deploy your application or microservice by passing different parameter values for evaluating the script.

  • Automate software delivery processes to produce repeatable, scalable, and efficient results.

  • Quickly and easily create and deploy applications or microservices using DSL scripts. Using these scripts enables a higher-order command-line interface (CLI) with richer syntax than the CLI on your system.

  • Quickly learn to create and run DSL to perform specific operations with little to no programming experience. Users do not need to know how to use the CloudBees CD/RO API or UI to create and deploy an application or microservice.

  • Make continuous delivery and continuous integration possible at scale.

For more information about the CloudBees CD/RO DSL, go to:

Test your DSL

You can write and run specification and acceptance testing on your CloudBees CD/RO DSL using ec-specs.

For more information, visit the ec-specs-examples GitHub repository.