Using the CloudBees CD Groovy API

The CloudBees CD Groovy API is a client-side Apache Groovy library for the CloudBees CD REST APIs. When CloudBees CD is installed—Server, Agent, or Tools (using the express or advanced installation type)—the client-side Groovy library for the CloudBees CD REST APIs is installed along with ec-groovy, which is a small wrapper program that can be used to run Groovy scripts.

Default Location of ec-groovy

  • The default location for ec-groovy on Linux is

    /opt/electriccloud/electriccommander/bin/ec-groovy
  • The default location for ec-groovy on Windows is

    C:\Program Files\Electric Cloud\ElectricCommander\bin\ec-groovy

On Windows hosts, the CloudBees CD installation process automatically adds ec-groovy to your path. On Linux hosts, you need to add $INSTAL_DIE/bin to the path manually:

export PATH=$PATH:/opt/electriccloud/electriccommander/bin

Running ec-groovy

To run ec-groovy from the command line:

  1. Set COMMANDER_HOME and COMMANDER_DATA as environment variables.

    If you are running ec-groovy within a CloudBees CD job context, these environment variables are automatically set.

  2. Enter ec-groovy <yourGroovyOptions> <GroovyScriptName>.groovy on the command line.

NOTE:

In multizone CloudBees CD deployments, CloudBees CD agents that are in a different zone than the CloudBees CD server must be running version 9.2 or later for the ec-groovy job step to run successfully on those agents. If you have any other zones in between that lead back to the server, you must also upgrade their gateway agents to version 9.2 or later.

For details about multiple zones and gateway agents, see Zones and Gateways.

Troubleshooting

If you encounter this error while running ec_groovy from the command line,

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed

then perform the following steps to resolve the issue.

  • Obtain the CloudBees CD server’s certificate.

    • Windows platforms:

      • Issue the following on a command line to display the server certificate contents.

        openssl s_client -connect :8443
      • Copy the server certificate contents after Server certificate into a file, say ef-server.crt. Here is an example of the content that needs to be copied.

        -----BEGIN CERTIFICATE-----
        MIIF5zCCBM+gAwIBAgIHBG9JXlv9vTANBgkqhkiG9w0BAQUFADCB3DELMAkGA1UE
        HLKJLhDJGFD66RhkgfkjgfHFJFR7i656FGKgf6cvfKHFKFKHGFKFHKGFHKFKFHFHK
        ...
        os5LW3PhHz8y9YFep2SV4c7+NrlZISHOZVzN
        -----END CERTIFICATE-----
    • UNIX platforms:

      Issue the following on a command line; this gets the certificate and saves it to the file, ef-server.crt (newlines added for readability).

      COMMANDER_HOME=/opt/electriccloud/electriccommander &&
         LD_LIBRARY_PATH=$COMMANDER_HOME/lib &&
         OPENSSL_CONF="$COMMANDER_HOME/conf/agentssl.cnf" && echo -e "quit\n" |
         $COMMANDER_HOME/bin/openssl s_client -connect replace-electricflow-server-name-here:8443
         | \sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ef-server.crt
      
      [source,txt,subs="attributes"]
  • Verify the certificate contents saved in ef-server.crt (newlines added for readability).

    COMMANDER_HOME=/opt/electriccloud/electriccommander &&   LD_LIBRARY_PATH=$COMMANDER_HOME/lib &&      OPENSSL_CONF="$COMMANDER_HOME/conf/agentssl.cnf" && echo -e "quit\n" |     $COMMANDER_HOME/bin/openssl x509 -in ef-server.crt -text
  • Import the certificate into the Java keystore (newlines added for readability).

    COMMANDER_HOME=/opt/electriccloud/electriccommander &&
       $COMMANDER_HOME/jre/bin/keytool -import -trustcacerts
                                       -keystore $COMMANDER_HOME/jre/lib/security/cacerts -storepass changeit
                                       -noprompt -alias myEFcert -file ef-server.crt

Confirm that ec-groovy successfully runs from the command line.

Running Groovy Scripts using Third-Party Libraries

In addition to the CloudBees CD Groovy APIs, ec-groovy can be used to run any Groovy script using third-party libraries. Consider the following Groovy script:

import groovyx.net.http.RESTClient

def client = new RESTClient('\https://www.google.com')

client.get( path : '/search', query : [q:'Groovy'] ) { response, data ->

  println "Response Status: ${response.statusLine}"
  println data
}

[source,txt,subs="attributes"]

Example: Groovy GET Script 1

import groovyx.net.http.HTTPBuilder
def http = new HTTPBuilder('\https://www.google.com')
def html = http.get( path : '/search', query : [q:'Groovy'] )

Example: Groovy GET Script 2

import groovyx.net.http.HTTPBuilder
def http = new HTTPBuilder('\https://www.google.com')

http.get( path : '/search',
          contentType : TEXT,
          query : [q:'Groovy'] ) { resp, reader ->

  println "response status: ${resp.statusLine}"
  println 'Headers: -----------'
  resp.headers.each { h ->
    println " ${h.name} : ${h.value}"
  }
  println 'Response data: -----'
  System.out << reader
  println '\n--------------------'
}

Example: Groovy POST Script

import groovyx.net.http.HTTPBuilder
import static groovyx.net.http.ContentType.URLENC

def http = new HTTPBuilder( '\https://restmirror.appspot.com/' )
def postBody = [name: 'bob', title: 'construction worker'] // will be url-encoded

http.post( path: '/', body: postBody,
           requestContentType: URLENC ) { resp ->

  println "POST Success: ${resp.statusLine}"
  assert resp.statusLine.statusCode == 201

Example of a grapeConfig.xml File Without Internet Repositories

Groovy also allows runtime resolution of artifacts that can download themselves across the internet. To disable this ability or to denylist only trusted repositories to download, write a grapeConfig.xml file and put it in the $COMMANDER_DATA/grape directory. This is an example of a grapeConfig.xml file without internet repositories: