YAML Declarative DSL Preview for CD/RO

Written by: Drew Piland
6 min read

CloudBees is always working to find ways to create value and choice for our customers. As part of that effort, we've launched YAML Declarative DSL for CloudBees CD/RO (fka CD and Flow). Introducing YAML provides users with a new configuration automation option for CloudBees CD/RO that’s based on a broadly accepted markup language.

CloudBees originally built CD/RO with DSL Groovy, a robust programming language that offers complete access to a full-featured API. But with YAML Declarative DSL, users have a new level of flexibility and ease of use. The new interface provides a user-friendly grammar that makes it easier for non-programmers and programmers to quickly stand up automated release pipelines and other models.

By supporting both interfaces, CloudBees makes the CD/RO automation platform accessible to a new audience while maintaining support for the existing one. Developers that need complete access to the release orchestration platform can use Groovy, while users that need a simple interface for building and running pipelines now have access to CloudBees YAML Declarative DSL.

Let's first look at the benefits for using a DSL, and then dive further into both DSLs supported by CloudBees CD/RO to help determine which is best for your needs.

Why Use a DSL?

Domain specific languages (DSLs) are code-based alternatives to graphic user interfaces for configuring programmable applications.  While general purpose languages such as Python and Java tend to be more complete, they're harder to learn, come with a more difficult syntax, and can be confusing when trying to perform domain-specific actions.

A DSL removes most, if not all, of these issues with deliberately designed constraints and a simpler grammar that lends itself to the specific application domain.

DSL can be used to create dynamic content based on API calls, for example. In the first procedure below, the getUsers API is used to create a list of users which is used to create a step definition for each user found. The resultant procedure contains a step for each user in the system at the time of running the DSL.

Interestingly, CD/RO procedures can dynamically generate job steps at runtime. In the second procedure example, there is only one step created when the DSL is applied, but at runtime the same getUsers API is used so that a job step can be created for each user that exists at runtime.

​# Scripted Groovy DSL that statically defines steps
project "Dynamic steps",{
	procedure "Hello Users static",{
		def users = getUsers().users
		users.each {
			step it.userName, command: "echo Hello ${it.userName}"
		}
	}

# Groovy DSL produces procedure with dynamic step generation using ec-Groovy
procedure "Hello Users dynamic",{
		step "Hello", shell: "ec-groovy", command: '''\
			import com.electriccloud.client.groovy.ElectricFlow
			ElectricFlow ef = new ElectricFlow()
			def users = ef.getUsers().user
			users.each {
				ef.createJobStep jobStepName: it.userName,
command: "echo Hello ${it.userName}"
			}
		'''.stripIndent()
	}
}

Let’s now shift to the two DSLs supported by CloudBees CD/RO, starting with YAML.

What is YAML?

YAML (YAML Ain't Markup Language) bills itself as a human-friendly data serialization language, and it certainly is easy to use. Its use of indentation to separate objects and fields makes it easy to scan a YAML document. But that doesn't mean YAML can't serve as the foundation for a useful declarative language. You can learn more about what is YAML.

With YAML Declarative DSL you can create pipeline objects and procedures to manipulate them. You don't have full access to all of the resources in CD/RO, but instead focus on the most common use cases like creating a pipeline.

Sample YAML Declarative DSL Script

Here's a sample script:

kind: project
metadata:
  name: YAML Project
spec:
  procedures:
    - name: First procedure
      formalParameters:
        - name: Procedure input
      steps:
        - name: Echo input
          command: echo $[Procedure input]
  pipelines:
    - name: Test pipeline
      stages:
        - name: First stage
          tasks:
            - name: First task
              taskType: PROCEDURE
              subprocedure: First procedure
              actualParameters:
                - name: Procedure input
                  value: 1234

This DSL script defines a procedure named First procedure. This procedure accepts a single argument and echoes it to the terminal. Then it defines a pipeline that executes the procedure with the parameter set.

When Does it Make Sense to Use YAML?

YAML makes it possible for users not familiar with Groovy, or programming in general, to take a high level, “code first,” approach to creating release orchestration pipelines. They use YAML to declare the steps they want their pipeline to take, in a clear, easy to comprehend, syntax. 

But even if you're familiar with Groovy and coding, YAML is a viable option for running pipelines that don't require additional processing such as loops, lookups, conditionals, API calls, or data transformations. The scripts are easy to read and lend themselves to straightforward pipelines that only need simple logic.

What is Groovy?

Groovy is a dynamic language with a syntax that's familiar to most programmers because it’s based on Java. Because of its support for closures, which makes it easy to embed functionality into applications, it's a popular choice for DSLs. It's a fully-featured programming language and has access to the entire CD/RO API, so you have complete control over CD/RO inside your script.

But that additional control comes at the cost of complexity: Every task, regardless of how trivial, requires writing a script. It also introduces risk, since you may not want to give all your users complete access to the CD/RO API.

Sample DSL Groovy Script

def spec = [
	projectName: "${getProperty("/myUser/userName").value} YAML Project",
	pipelineName: 'Test pipeline'
]

project spec.projectName, {
	procedure 'First procedure', {
		formalParameter 'Procedure input'
		step 'Echo input', {
			command = 'echo $[Procedure input]'
		}
	}

	pipeline spec.pipelineName, {
		stage 'First stage', {
			task 'First task', {
				actualParameter = [
					'Procedure input': '1234',
				]
				subprocedure = 'First procedure'
				subproject = 'YAML Project'
				taskType = 'PROCEDURE'
			}
		}
	}
}

This Groovy script duplicates the behavior in the YAML Declarative DSL script above.

When Does it Make Sense to Use Groovy?

DSL Groovy has several capabilities that YAML Declarative DSL does not. Depending on what you need CloudBees CD/RO to do, these features may be important.

  • Direct API access - you may access API calls that the Declarative DSL does not have wrappers for

  • Data transformations - you can alter data, such as the results of steps or data from external sources, inside your pipelines

  • Looping over data sets- to perform iterative tasks such as creating multiple objects from a spreadsheet

  • Complex data types - with DSL Groovy, you can define and use custom objects in your scripts.

  • Need for logic or conditional code- to respond to different types of data inputs

For example, if you’re using CloudBees CD/RO for a service catalog application, or you want to move a system from another tool like a spreadsheet, or if you have a third-party deployment tool and need to translate into CD/RO then you’ll need Groovy’s features.

Wrap-Up

We’ve covered how, with two different DSL options, CloudBees CD/RO now has more to offer to a wider audience.

YAML Declarative DSL makes it easy for anyone to declare and run pipelines in minutes. It has a straightforward, human-friendly syntax that's easy to read, write and share. 

At the same time, developers can still write complex jobs with DSL Groovy. They have complete access to the CD/RO API, as well as all the power groovy code has to offer.

Stay up to date

We'll never share your email address and you can opt out at any time, we promise.