Install and use the PDK CLI

10 minute readReferenceExtensibilityDeveloper productivity

Setup

CloudBees offer two versions of the PDK framework: one that is compatible with Java 8 and 11, and one that is compatible with Java 17. Both PDK versions operate the same except for the required Java version. Follow the steps in the following sections based on your development requirements.

Prerequisites

To use Java 17, the following minimum CloudBees CD/RO version requirements must be met or plugins using Java 17 cannot be used in your environment. You must use:

  • CloudBees CD/RO server v10.11 or later.

  • CloudBees CD/RO agent v10.5 or later.

Install the PDK

Complete the following steps to set up the PDK environment for your required Java version:

  1. Download and open the archive of one of the following pdk CLI options:

    • Java 8 and 11 option:

      • Full bundle (pdk-cli-bundle.zip): Standalone version.

    • Java 17 options:

      Ensure your system meets the minimum CloudBees CD/RO version requirements listed in Setup.
      • Thin bundle (pdk-cli.zip): Requires internet connection during the generation/build process to fetch new versions of remote assets.

      • Full bundle (pdk-cli-bundle.zip): Standalone version.

  2. Set the JAVA_HOME environmental variable to the top-level directory of the Java binary installation path.

    The pdk CLI version requires a corresponding Java runtime environment (JRE) based on the Java version you are using, and expects the JAVA_HOME environmental variable to be set to the top directory of the Java binary installation path. For example, if Java is installed under /opt/cloudbees/sda/jre/bin, the JAVA_HOME should look similar to:

    $ ls -lrt /opt/cloudbees/sda/jre/bin | grep java

    Example response:

    -r-xr-xr-x 1 vagrant vagrant 128791 Mar 15 2017 javaws -r-xr-xr-x 1 vagrant vagrant 7734 Mar 15 2017 java vagrant@commander5:/vagrant/plugindevguide/docs$ echo $JAVA_HOME /opt/cloudbees/sda/jre
  3. To use the pdk CLI, include PDK in your PATH environmental variable. Once you have added it, ensure it is present. For example:

    $ echo $PATH /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/opt/cloudbees/sda/bin:/vagrant/framework/pdk/bin

Command hierarchy

The CLI is structured as a hierarchy of commands with each top level command having subcommands and additional switches/options that control the output of the command. This is a list of all top level commands and their purpose. The following is an example of a hierarchy:

pdk (CLI) pdk config (config command) pdk config listoptions (config with listoptions as a subcommand)

Top-level commands

Command Description

config

Used to configure the pdk utility for general purpose defaults—​plugin author, support URL, and so on.

generate

Used for one of the following scenarios:

  • Generate a plugin workspace containing an empty starter plugin spec for a new plugin, the first time.

  • Generate the boilerplate code for a plugin after filling/modifying the plugin spec, during the course of plugin development.

build

Used to build the plugin.

showdoc

Used to show the description of the various fields that make up the plugin spec. This can be used as a reference during plugin procedure interface development.

describe

Shows the various dependencies and their versions of pdk. This is typically used.

debug

Turns on/off/purge logs written by the utility with required verbosity where appropriate. When debug is enabled logs are written to a log file called pdk.log under the $HOME/.flowpdf directory.

cookie-cutter

Manages process as code projects. This command should run from a project root: the folder that contains project.dsl file in it.

Generic switches

  • --help or -h provides the help at any level of the hierarchy. Here are some examples.

    $ pdk --help Usage: pdk [-hv] [COMMAND] Commands: config Configure the pdk utility generate Generate a plugin workspace along with a starter plugin spec or a plugin from a filled in plugin spec. build Build the plugin showdoc Show the description of the various fields that make up the plugin spec describe Show the content of the pdk spec which contains its dependencies debug Turn on/off/purge logs written by the pdk utility with required verbosity where appropriate. When debug is enabled logs will be written to a log file called pdk. log under the pdk/bin directory. $ pdk config setoption --help Usage: pdk config setoption [-h] [-v]... optionName optionValue Description: Set a specific configuration option optionName Option name optionValue Option value
  • --version or -v provides miscellaneous version information about pdk.

    $ pdk --version pdk version 1.0.0 toolkit version 1.0.0 Build Timestamp: 2019-06-19T15:01:45.409+0300 Build Number: 138 Commit: a1104bcf6b44276ce93a44876eff27c29e701f05 Built with Java: 1.8.0_201

Quick Start

Prerequisite: The setup section above has been completed successfully.

For first time users, this section provides the steps to get started with a simple plugin.

  1. Generate workspace: this step uses the interactive mode to create a subdirectory with a predefined sample plugin configuration specification.

    $ pdk generate workspace INFO: Plugin name is not provided Please provide a name for the new plugin, e.g. MyPlugin: QuickStartPlugin ...

    This will result in the following directory structure being created:

    QuickStartPlugin
    └── config
        ├── flowpdf.yaml
        └── pluginspec.yaml
  2. Look at plugin spec: the goal is to edit this file to add all the procedures needed. Lets take a look at it:

    $ cat QuickStartPlugin/config/pluginspec.yaml pluginInfo: # This is default sample specification # Feel free to change it # Call pdk showdoc pluginspec to see the list of available fields and their description pluginName: 'QuickStartPlugin' ...
  3. Generate the plugin code.

    $ cd QuickStartPlugin/ $ pdk generate plugin

    The generated plugin drectory structure will be as follows:

    .
    ├── README.md
    ├── agent
    │   ├── README.md
    │   └── deps
    │       └── libs
    │           └── flowpdf-groovy-lib-1.2.0.0.jar
    ├── build.gradle
    ├── config
    │   ├── flowpdf.yaml
    │   └── pluginspec.yaml
    ├── dsl
    │   ├── procedures
    │   │   ├── CreateConfiguration
    │   │   │   └── steps
    │   │   │       └── checkConnectionGeneric.groovy
    │   │   ├── SampleRESTProcedure
    │   │   │   └── steps
    │   │   │       └── SampleRESTProcedure.groovy
    │   │   └── TestConfiguration
    │   │       └── steps
    │   │           └── checkConnectionGeneric.groovy
    │   └── properties
    │       └── groovy
    │           └── lib
    │               ├── QuickStartPlugin.groovy
    │               ├── QuickStartPluginRESTClient.groovy
    │               └── SampleRESTProcedureParameters.groovy
    ├── htdocs
    │   ├── images
    │   │   └── icon-plugin.svg
    │   └── pluginhelp.css
    └── pages
        └── help.xml
  4. Build the plugin.

    $ pdk build

    This will create a plugin image: build/QuickStartPlugin.zip

  5. Load the plugin into CloudBees CD/RO

    • In the UI "Plugin Manager" "Install from File" tab the plugin image can be uploaded.

The QuickStartPlugin is ready to be used

Now go to step 2 the plugin spec can be edited to add the procedures as required and repeat the rest of the steps. Refer to Regeneration after a spec change before proceeding.

Command list

pdk config

This command supports the following subcommands.

listoptions List available configuration options show Show currently saved configuration setoption Set a specific configuration option
  • pdk config listoptions: lists items that can be configured for the pdk as a one-time setup.

    Usage: pdk config listoptions pluginAuthor: Default plugin author name to be set for the new plugins supportUrl: Default support URL to be set for the new plugins debugOn: If set to true, logs will be redirected to the log file. verbosity: Log verbosity level. Only applicable if debugOn is enabled.
  • pdk config show: shows the value of each of the configured items.

    Usage: pdk config show debugOn: false verbosity: 2
  • pdk config setoption: sets the value of each item.

    Usage: pdk config setoption <optionName> <optionValue> pdk config setoption pluginAuthor "James Doe"

pdk generate

This command is sensitive to the directory from which it is executed. For example, if you execute pdk generate workspace from directory X and call your plugin EC-Myplugin, the workspace called EC-Myplugin is created under X. Similarly if you want to generate plugin EC-Myplugin, generate plugin should be executed from the directory EC-MyPlugin.

Usage 1: pdk generate workspace Usage 2: pdk generate plugin
  • pdk generate workspace: generates a workspace for the plugin to hold the source code based on a standard layout. It can be invoked in one of the following ways. The first one is in interactive mode and the second one is passing the values required to generate the workspace on the command line.

    Usage 1: pdk generate workspace Usage 2: pdk generate workspace [--category=<category>] [--description=<description>] [--plugin-name=<pluginName>] [--author=<author>] [--support-url=<supportUrl>]

    When generating the workspace choose the following types based on your use case.

    • default: starts on a simple template. This generates a sample procedure section in the plugin spec.

    • rest: builds a rest plugin. This generates a sample rest based procedure section in the plugin spec.

    • reporting: interfaces with third party to bring in data for reporting purposes. This generates a reporting section in the plugin spec.

  • pdk generate plugin: generates a plugin in the workspace using the spec defined in pluginspec.yaml.

    Usage: pdk generate plugin --overwrite --upgrade --overwrite This flag forces rewrite for auto-generated portions of code on files shared with user. --upgrade This flag will launch the upgrade process for plugin cores.

pdk build

This command builds a plugin and should be executed from the root directory of the plugin workspace.

Usage: pdk build

pdk showdoc

This command is used to show documentation corresponding to various aspects of pdk.

  • pdk showdoc pluginspec: produces a list of fields available in the pluginspec and their description.

    Usage : pdk showdoc pluginspec
  • pdk showdoc toolkit: shows the full help for utility in one page.

    Usage: pdk showdoc toolkit

pdk describe

Show the version of all the dependencies of pdk.

Usage: pdk describe Layout version: 1.0.10 Language core Perl version: 1.1.11

pdk debug

This command is used to manage the creation of logs written by the utility with required verbosity where appropriate.

  • pdk debug on: enable debug and write logs to pdk.log under the /bin directory. Default is lowest verbosity.

    Usage: pdk debug on
  • pdk debug off: disable debug and do not write logs.

    Usage: pdk debug off
  • pdk debug purge: purge debug logs.

    Usage: pdk debug off
  • pdk debug setverbosity: set the verbosity level of debug log to one of infotrace.

    Usage: pdk debug setverbosity pdk debug setverbosity trace
  • pdk debug check: Returns detailed information about (for example build timestamp, commit id), its dependencies (for example Perl library version, groovy library version) and its runtime environment (for example Java version). Note that this command provides more detailed information than desc.

    Usage: pdk debug check

Aliases: cc

The command executes incremental update for the project. It saves its state under folder .cdproj that is located under the project root, in the same folder where project.dsl is located. After the command runs for the first time, it saves the timestamp in the state, and uses this timestamp to determine which files were updated. The next runs applies changes only from updated files. The command is using session saved by ectool login command, execute it before running the command or provide COMMANDER_SESSIONID environment variable.

Usage: pdk cc --hostname <myserver>

pdk watchpatch

Access to live plugin update functions. The command hangs in the background and waits until a file in the plugin directory is saved and then updates the corresponding property on the CloudBees CD/RO server. Only properties in the dsl/properties folder are supported.

Usage: pdk watchpatch --hostname mydevserver

Bash autocomplete

To generate an autocomplete script, use

pdk config generate-completion

It will generate an autocompletion script for Bash and add it the PDK configuration home directory. You source this script from your .bashrc or .zshrc file.

For example:

pdk config generate-completion INFO: Writing log to the file /Users/imago/.flowpdf/pdk.log INFO: Saved completion script into /Users/imago/.flowpdf/pdk_completion, file is set executable INFO: Please add source /Users/imago/.flowpdf/pdk_completion to your .bashrc or .zshrc file

Start a new session and type

pdk<Tab>

You see a list of commands you are able to run.

pdk build cc config cookie-cutter debug describe generate server showdoc watchpatch

Generated code

Reserved sections

The workspace of a plugin generated by pdk has a code layout like the sample below. The name of the plugin here is EC-Git.

image

Note the following pdk generated sections. Do not OVERRIDE or EDIT at any time.

  • The folders called .assets, META-INF and core (under properties/perl) in their entirety.

  • The files flowpdf.yaml, Baseplugin.groovy, form.xml (under individual procedures) and deleteConfiguration.pl in their entirety.

  • Any block of code that is in between the markers as mentioned below in any of the generated files. See first snippet below.

  • Any one line marker that are used to demarcate system generated code boundaries. See second snippet below.

## DO NOT EDIT THIS BLOCK === rest client imports starts === package FlowPlugin::CBGitRESTClient; use strict; use warnings; use LWP::UserAgent; use JSON; use Data::Dumper; use FlowPDF::Client::REST; use FlowPDF::Log; ## DO NOT EDIT THIS BLOCK === rest client imports ends, checksum: 96d6a71a265e9e05f1b5eb17e5a29ac1 ===
## === step ends === # Please do not remove the marker above, it is used to place new procedures into this file.

Regeneration after a spec change

This section provides information about the behavior of upon regenerating an already generated plugin after changing its specification, pluginspec.yaml. Here is a list of common scenarios of change, behavior in each scenario, and what the developer is recommended to do for it.

Add a new procedure

pdk behavior: A new folder in the dsl/procedures folder is created to store the procedure metadata. A new section is generated for the main module. A procedure is added to the dsl/promote.groovy to the list of "steps with credentials" (but only if the procedure requires configuration). Recommended Action: Change the generated boilerplate code to introduce the required logic for the new procedure.

Delete a procedure

pdk behavior: The folder with the procedure metadata is deleted. The procedure steps are removed from the dsl/promote.groovy (code section is not deleted). Recommended Action: Cleanup the code in the main module code by removing the method that was previously associated with the procedure.

Add a new input/output procedure parameter

pdk behavior: The procedure specification in the procedure folder is updated (form.xml and procedure.dsl). Recommended Action Update the procedure code (in the main module) to incorporate the new parameter.

Rename a procedure

pdk behavior: Renaming is handled as a Delete and Add. The folder for the procedure with the old name is deleted and a new one is created. The dsl/promote.groovy file is updated with the new procedure name, and a new code block with the method name mentioning the new procedure name is generated. Recommended Action: Transfer whatever logic the old procedure method contained to the newly generated boilerplate and remove the old procedure method.

Update procedure parameter

pdk behavior: The procedure specification in the procedure folder is updated (form.xml). Recommended Action: No action required.

Delete procedure parameter

pdk behavior: The procedure specification in the procedure folder is updated (form.xml). Recommended Action: Update the procedure code (in the main module) to handle the deletion of the parameter

Rename procedure parameter

pdk behavior: The procedure specification in the procedure folder is updated (form.xml). Recommended Action: Update the procedure code (in the main module) to handle the new parameter name.

New configuration parameter added/renamed/removed

pdk behavior: The form.xml of the CreateConfiguration procedure is modified. Recommended Action: No Action Required.

New REST action added to configuration

pdk behavior: The form.xml of the CreateConfiguration procedure is modified. Recommended Action: No action required.

New REST based auth scheme in configuration

pdk behavior: The form.xml of the CreateConfiguration procedure is modified according to the REST layout. Recommended Action: No action required.

Add checkConnection to configuration

pdk behavior: If there is REST section, an auto-generated REST check connection script is added. If there is no REST section, a boilerplate step for checking connection is generated instead. Recommended Action: No action required.

REST endpoint added to restclient section

pdk behavior: A method for this REST endpoint is generated in the REST client. Recommended Action: Utilize the newly generated method in the procedure code.

REST endpoint removed from restclient section

pdk behavior: The proxy method corresponding to the REST endpoint is removed from the REST client. Recommended Action: Cleanup the method usages from the main module code.

New parameter added to restclient section endpoint

pdk behavior: The method for the endpoint is regenerated in the REST client to accommodate the new parameter. Recommended Action: Change the method call in the main module to accommodate the new parameter.

Parameter removed from REST client endpoint

pdk behavior: The method for the endpoint is regenerated in the REST client to accommodate the updated set of parameters. Recommended Action: Change the method call in the main module to accommodate the changes.

New devOpsInsight section added

pdk behavior: A new procedure named CollectReportingData is generated along with a set of reporting dashboard scripts and forms under dsl/properties. A new module called <PluginName>/Reporting.pm is generated. The code for the CollectReportingData procedure is generated and placed in the main module. Recommended Action: Change the Reporting module to accomodate your Reporting logic and change the code for the CollectReportingData procedure to provide the actual parameters required for your particular case.

New payload type added to devOpsInsight section

pdk behavior: A new set of dashboard scripts is added. Recommended Action: Change the main module and the Reporting module to incorporate the change in the payload types.

New parameter added to devOpsInsight section

pdk behavior: Forms for both CollectReportingData procedure as well as the dashboard get generated. Recommended Action: Incorporate the new parameter in both main module as well as in the reporting module.

Parameter removed from devOpsInsight section

pdk behavior: Forms for both CollectReportingData procedure as well as the dashboard get generated. Recommended Action: Incorporate the new parameter in both main module as well as in the reporting module.

Payload type in devOpsInsight section removed/renamed

pdk behavior: The folder with the dashboard scripts for the old payload type is removed. Recommended Action: Incorporate the new parameter in both main module as well as in the reporting module.