Install and use PDK

12 minute readReferenceExtensibilityDeveloper productivity

The CloudBees PDK (Plugin Development Kit) is a versatile framework for developing plugins to interact with CloudBees CD/RO. The PDK is a combination of tools, specifications, APIs, and libraries that work together with the overall goal of making plugin development easy and consistent.

This page explains:

Setup PDK

CloudBees offers two versions of the PDK framework: one compatible with Java 8 and 11 and another compatible with Java 17. Both PDK versions operate the same except for the required Java version. Based on your development requirements, follow the steps in the following sections.

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 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 PDK.
      • 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.

  3. To use the pdk CLI, include PDK in your PATH environmental variable. Once you have added it, ensure it is present.

PDK commands

The PDK CLI is structured as a hierarchy of commands with top-level commands, subcommands, and additional switches/options that control the output of the command:

Command syntax
Example
pdk command subcommand [switches] [--option=value]
pdk config proxy <serverAddress> <port> -u <user> -p <password>

Top-level commands

Top-level commands perform PDK functions using subcommands and switches/options. The following sections explain these commands and their subcommands, switches/options, and common use cases.

The --help and -h switches can be used for PDK top-level commands and subcommands to display the basic descriptions in the terminal.

pdk config

This command is used to configure general-purpose defaults for the pdk utility, such as author, support URL, and so on. 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 general-purpose defaults 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 configured item.

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

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

pdk generate

This command is used to generate a templated plugin workspace (pdk generate workspace) or boilerplate code after modifying the plugin spec during development (pdk generate plugin).

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:

    • Interactive mode with prompts to provide plugin metadata.

      Usage 1: pdk generate workspace
    • Passing the values as arguments required to generate the workspace.

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

      When generating the workspace, choose the type of workspace (category) based on your plugin use case.

      • default: Generates a generic plugin with an example procedure section in the plugin spec.

      • rest: Generates a REST-based plugin with an example REST procedure section in the plugin spec.

      • reporting: Generates a plugin to retrieve third-party data for reporting purposes, and includes a reporting section in the plugin spec.

  • pdk generate plugin: Generates/updates the plugin workspace using the configuration defined in config/pluginspec.yaml.

    When you make changes in the config/pluginspec.yaml, run pdk generate plugin. This ensures your changes are applied to files generated by the PDK, and your workspace stays synced.
    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 is used to compile the plugin into an executable archive (.zip) that can be imported to CloudBees CD/RO. You must execute pdk build in the root directory of the plugin workspace. Once the plugin is compiled, a build directory is created that contains your <YOUR-PLUGIN>.zip.

Usage: pdk build

pdk showdoc

This command shows the description of the various fields that make up the plugin spec to provide reference during plugin development.

  • 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 PDK --help reference.

    Usage: pdk showdoc toolkit

pdk describe

Shows the version of plugin pdk dependencies, as described in the config/flowpdf.yaml.

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

pdk debug

This command is used to manage logs written by PDK, with required verbosity where appropriate. When debug is enabled, logs are written to a log file called pdk.log in the <PDK-HOME-DIR>/.flowpdf directory.

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

    Usage: pdk debug on
  • pdk debug off: Disables debug and does not write logs.

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

    Usage: pdk debug off
  • pdk debug setverbosity: Sets the debug verbosity level (info|debug|trace).

    Usage: pdk debug setverbosity pdk debug setverbosity info|debug|trace
  • pdk debug check: Returns detailed information about your PDK installation, its dependencies, and its runtime environment.

    Usage: pdk debug check
    Example
    Command
    Response
    pdk debug check
    INFO: Writing log to the file <PDK-HOME-DIR>.flowpdf/pdk.log INFO: Version Data INFO: pdk version 4.0.2 INFO: toolkit version 4.0.2 INFO: Build Timestamp: 2023-12-27T16:52:47.348+0000 INFO: Build Number: 0 INFO: Commit: b7babaa405e82886a57ed142c79a5074130faf89 INFO: Built with Java: 17.0.7 INFO: OS: <YOUR-OS> INFO: Java version: 17.0.10 INFO: Configuration file: <PDK-HOME-DIR>.flowpdf/config INFO: Configuration values INFO: pluginAuthor = null (Default plugin author name to be set for the new plugins) supportUrl = null (Default support URL to be set for the new plugins) debugOn = true (If set to true, logs will be redirected to the log file.) verbosity = 0 (Log verbosity level. Only applicable if debugOn is enabled.) ignoreSslIssues = false (HTTP clients ignore issues with SSL certificates.) proxyHost = null (Host to connect through proxy server) proxyPort = 0 (Proxy server port to connect) proxyUsername = null (Proxy server authorization username) proxyPassword (SECRET, Password to connect to the proxy server) = Not Set proxyScheme = null (Proxy scheme to connect to the proxy server. HTTP by default.)

Generic switches

  • --help or -h provides help at any level of the hierarchy.

    The --help and -h switches can be used for all top-level commands PDK commands.
    Command
    Response
    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.

    Command
    Response
    pdk --version
    pdk version 4.0.2 toolkit version 4.0.2 Build Timestamp: 2023-12-27T16:52:47.348+0000 Build Number: 0 Commit: b7babaa405e82886a57ed142c79a5074130faf89 Built with Java: 17.0.7

Bash autocomplete

A built-in autocomplete is packaged with PDK, but must be initialized in your installation. To generate the autocomplete script, run the following:

Command
Response
pdk config generate-completion
INFO: Writing log to the file <PDK-INSTALLATION_DIR>/.flowpdf/pdk.log INFO: Saved completion script into <PDK-INSTALLATION_DIR>/.flowpdf/pdk_completion, file is set executable INFO: Please add source <PDK-INSTALLATION_DIR>/.flowpdf/pdk_completion to your .bashrc or .zshrc file

PDK generates an autocompletion script for Bash and adds it to the PDK configuration installation directory. To enable autocompletion, source this script in your .bashrc or .zshrc.

Once your terminal session sources your profile, run:

Command
Response
pdk<TAB>
pdk build cc config cookie-cutter debug describe generate server showdoc watchpatch

Generate plugin example

You have completed Setup PDK, before you can complete these steps.

This section demonstrates the minimal steps to generate a basic plugin using PDK:

  1. Navigate to the directory where you want to generate the plugin.

  2. Generate the plugin workspace, by running:

    For this exercise, you only need to provide a plugin name, and all other values can be set to default. In the following examples, QuickStartPlugin is used as the plugin name.
    Command
    Response
    pdk generate workspace
    >> pdk generate workspace INFO: Plugin name is not provided Please provide a name for the new plugin, e.g. MyPlugin: QuickStartPlugin Please provide a workspace type or types. Available types are rest, reporting or default (default: 'default', separated by a comma or a space): Please provide the author name (default: none): Please provide the support URL (default: none): Please provide the plugin category (default: Utilities): Please provide the description for the plugin: Demo plugin for QuickStart Please provide the language for the plugin (default: groovy, available languages are perl, groovy): WARN: Language is not supported, Groovy will be used by default WARN: Language is not supported, Groovy will be used by default INFO: Wrote initial declaration to ~/work/plugins: QuickStartPlugin/config/pluginspec.yaml INFO: Plugin folder is ~/work/plugins: QuickStartPlugin INFO: Wrote flowpdf specification into ~/work/plugins: QuickStartPlugin/config/flowpdf.yaml INFO: Initial plugin spec has been placed into ~/work/plugins: QuickStartPlugin/config/pluginspec.yaml INFO: Go into the plugin directory: 'cd ~/work/plugins: QuickStartPlugin' INFO: Change the plugin spec and run 'pdk generate plugin' from the plugin directory
    This step used the interactive mode to create the plugin workspace/directories, and you were prompted to provide your plugin metadata. You can also pass plugin metadata as arguments, refer to [pdk-generate-workspace-usage-2].

    The PDK generates the following directory structure:

    QuickStartPlugin
    └── config
        ├── flowpdf.yaml
        └── pluginspec.yaml

    The flowpdf.yaml contains PDK metadata about your plugin. If the data in this file is erroneously modified, your plugin may behave in expected ways or not function.

    flowpdf.yaml example
    flowpdf-plugin-spec: 2 flowpdf-groovy-sdk: 1.3.0 flowpdf-plugin-layout: 1.3.7

    For more information about reserved PDK and plugin resources, refer to Reserved PDK and plugin resources.

  3. Open and review the config/pluginspec.yaml, which contains the following sections:

    • pluginInfo: This section contains the plugin metadata.

      Example pluginInfo section
      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' version: '1.0.0' description: 'Demo plugin for QuickStart' author: 'none' supportUrl: 'none' category: 'Utilities' shell: 'ec-groovy'
    • configuration: This section contains the fields and parameters used to create plugin configurations in CloudBees CD/RO.

      Example configuration section
      # Plugin configuration description configuration: # This is a shell used for checking connection shell: 'ec-groovy' # A script for checking connection will be generated checkConnection: 'true' # A set of fields will be added to process debug level in the configuration hasDebugLevel: true parameters: - name: config documentation: The name for the created configuration required: true type: entry label: Configuration Name - name: desc documentation: Description for the configuration required: false type: entry label: Description - name: endpoint documentation: Third-party endpoint to connect to. required: false type: entry label: Endpoint - name: credential documentation: A sample credential required: true type: credential label: Credential
    • procedures: This section contains the fields and parameters for plugin procedures.

      Example procedures section
      procedures: - name: 'Sample Procedure' description: 'Sample procedure description' # configuration field will be generated automatically hasConfig: true parameters: - name: applicationPath documentation: Path to the application required: true type: entry label: Application Path outputParameters: deployed: 'JSON representation of the deployed application'
  4. In your plugin root directory, generate the plugin code by running:

    pdk generate plugin

    The generated plugin directory structure should be similar to:

    Generated plugin directory structure
    . ├── README.md ├── agent │ ├── README.md │ └── deps │ └── libs │ └── flowpdf-groovy-lib-2.0.3.0.jar ├── build.gradle ├── config │ ├── flowpdf.yaml │ └── pluginspec.yaml ├── dsl │ ├── procedures │ │ ├── CreateConfiguration │ │ │ └── steps │ │ │ └── checkConnection.groovy │ │ ├── SampleProcedure │ │ │ └── steps │ │ │ └── SampleProcedure.groovy │ │ └── TestConfiguration │ │ └── steps │ │ └── checkConnection.groovy │ └── properties │ └── groovy │ └── lib │ ├── QuickStartPlugin.groovy │ └── SampleProcedureParameters.groovy ├── htdocs │ ├── images │ │ └── icon-plugin.svg │ └── pluginhelp.css └── pages └── help.xml
  5. Review the boilerplate code for Sample Procedure generated by PDK, by opening dsl/properties/groovy/lib/SampleProcedureParameters.groovy. This file contains the code logic for this procedure, and would be where to modify it during plugin development.

    For a better understanding of how this code is generated, open config/pluginspec.yaml, and refer to procedures.name=Sample Procedure.
  6. In your plugin root directory, build the plugin by running:

    pdk build

    This compiles the plugin image as a .zip in the build directory.

    This plugin currently has no real functionality, and should not be added to your CloudBees CD/RO instance as is. However, for instructions on how you would import this file into your CloudBees CD/RO instance, refer to Install plugins from a file.

As is, this plugin has no real functionality. If you were developing an actual plugin, you would now modify the config/pluginspec.yaml and procedure code in the corresponding files. For more information, refer to Common development use cases.

If you want more practice developing plugins, you can also try the Basic Jira plugin tutorial. It demonstrates developing a functional plugin that retrieves data about issues in your Jira instance using a Groovy-based plugin.

Reserved PDK and plugin resources

Some pdk generated resources are critical to the behavior of your plugin’s interactions with CloudBees CD/RO, and thus, reserved. These reserved resources include:

Modifying these resources may result in your plugin behaving in unexpected ways or not functioning.
  • The .assets, META-INF, and core directories in their entirety.

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

  • Any block of code between the ## DO NOT EDIT THIS BLOCK markers in any generated files, such as shown in the following example:

    ## 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 ===
  • Any one-line marker used to demarcate system-generated procedure code boundaries, such as shown in the following example:

    ## === step ends === # Please do not remove the marker above, it is used to place new procedures into this file.

Common development use cases

This section provides information about common use cases involved in plugin development, a description of how PDK handles them, and recommended user actions.

Whenever modifying your plugin config/pluginspec.yaml, ensure you run pdk generate plugin to update the corresponding workspace resources.

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, but the 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 directory 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 Delete and Add action. The directory 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 referencing 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 directory is updated (form.xml).

Recommended Action: None.

Delete procedure parameter

PDK behavior: The procedure specification in the procedure directory 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 directory is updated (form.xml).

Recommended Action: Update the procedure code (in the main module) to handle the new parameter name.

Configuration parameter added/renamed/removed

PDK behavior: The form.xml of the CreateConfiguration procedure is modified.

Recommended Action: None

New REST action added to configuration

PDK behavior: The form.xml of the CreateConfiguration procedure is modified.

Recommended Action: None

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: None

Add checkConnection to configuration

PDK behavior: If there is a REST section, an auto-generated REST check connection script is added. If there is no REST section, a boilerplate step for checking the connection is generated instead.

Recommended Action: None

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 endpoint method 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 accommodate 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 the main module and 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 the main module and 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 the main module and reporting module.