Pipeline Stage Plugin Walkthrough

This article illustrates a plugin stage, using the RandomWait stage plugin (pf4jStagePlugin) as an example.

The contents of this page refer to alpha features in Spinnaker 1.19.4.

This means we are working on their stability and usability, as well as possibly adding or changing features. Expect rough edges, and file issues as needed.

This guide is a work in progress. Help us improve the content by submitting a pull request!

Requirements

• You have read the Plugin Creators Guide Overview .
• Gradle and Yarn for building the plugin locally
• IntelliJ IDEA, Orca branch release-1.19.x and Deck branch for local testing
• Spinnaker v1.19.4 and Halyard 1.34 for deploying the pf4jStagePlugin 1.0.16

pf4jStagePlugin plugin

The pf4jStagePlugin creates a custom pipeline stage that waits a number of seconds before signaling success. The plugin consists of a random-wait-orca Kotlin server component and a random-wait-deck React UI component.

This is a very simplistic plugin for educational purposes only. You can use this plugin as a starting point to create a custom pipeline stage.

random-wait-orca

This component implements the SimpleStage PF4J extension point in Orca and consists of five classes in the io.armory.plugin.state.wait.random package:

• Context.kt: a data class that stores the maxWaitTime value; SimpleStage uses Context
• Output.kt: a data class that stores the timeToWait getValue; this data is returned to the extension point implementation and can be used in later stages
• RandomWaitConfig.kt: a data class with the @ExtensionConfiguration tag; key-value pairs in this class map to the plugin’s configuration
• RandomWaitInput.kt: a data class that contains the key-values pairs that we care about from the Context map
• RandomWaitPlugin.kt: this is the plugin’s main class; implements SimpleStage

Watch a video walkthrough and read code comments for more information.

random-wait-deck

This component uses the <code>rollup.js</code> plugin library to create a UI widget for Deck.

• rollup.config.js: configuration for building the JavaScript application
• package.json: defines dependencies
• RandomWaitStage.tsx: defines the custom pipeline stage; renders UI output
• RandomWaitStageIndex.ts: exports the name and custom stages

Watch a video walkthrough and read code comments for details.

Building the release bundle

After you download the 1.0.16 source code, build the release bundle.

cd pf4jStagePlugin
./gradlew releaseBundle

This command creates the pf4jStagePlugin-1.0.16.zip in pf4jStagePlugin/build/distributions. Locate the MANIFEST.MF in pf4jStagePlugin-1.0.16.zip -> orca.zip -> classes -> META-INF

Manifest-Version: 1.0
Plugin-Description: An example of a PF4J based plugin, that provides a
  new stage.
Plugin-Id: Armory.RandomWaitPlugin
Plugin-Provider: https://github.com/claymccoy
Plugin-Version: unspecified
Plugin-Class: io.armory.plugin.stage.wait.random.RandomWaitPlugin

Debugging random-wait-orca in Orca locally

Help us improve this section by submitting a pull request!

1. Ensure your development environment is set up to run Orca locally.
2. Clone Orca branch release-1.19.x
3. Import into IntelliJ
4. Follow the steps in the Debugging section of the pf4jStagePlugin README.

Debugging random-wait-deck in Deck locally

Help us improve this section by submitting a pull request!

1. Obtain the Deck release-1.19.x branch.

2. Create a folder called plugins in the deck directory. Copy RandomWaitStageIndex.js to the new directory.

3. Add to deck\plugin-manifest.json:

   [
     {
       "id": "Armory.RandomWaitPlugin",
       "version": "1.0.16",
       "url": "/plugins/RandomWaitStageIndex.js>"
     }
   ]

   ``

4. Start Deck and navigate to the Pipeline creation screen. Verify that Random Wait is an option in the Stage drop-down.

Plugin build and configuration files

Help us improve this section by submitting a pull request!

build.gradle

• spinnakerBundle section
• subprojects section

random-wait-orca subproject, random-wait-orca.gradle

• spinnakerPlugin section

Last modified June 24, 2021: Redesign Progress (#83) (8231bcf)