Spinnaker – Plugin Creators

Docs: Plugin Creators Overview

Mon, 01 Jan 0001 00:00:00 +0000

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.

Requirements

Spinnaker v2025.3.0+

Taxonomy

Extension Point: Defined by a Spinnaker service, it represents an official contract for which extensions can be written against. Defined by using an org.pf4j.ExtensionPoint interface. Written by Core Contributors.

Extension: A piece of code that implements an Extension Point. Written by Developers.

Plugin: A collection of Extensions that can be bundled together and shipped as a single artifact. Also written by Developers.

Plugin overview

A plugin enables an operator to extend Spinnaker with custom functionality. Use cases include fetching credentials from a custom authorization service, adding a wait stage to a pipeline, updating a Jira ticket, and sending Echo events to third-party tools.

ExtensionPoint plugins

Spinnaker uses the Plugin Framework for Java (PF4J) to indicate an extension point interface to a service. You can create a plugin that implements the methods declared in an extension point. Creating a plugin based on an extension point has a number of advantages:

It’s the easiest - use the @Extension annotation and implement the methods declared in your chosen extension point
Spinnaker loads the plugin in an isolated classpath
It has the least amount of maintenance work
Updates to Spinnaker are not likely to break your plugin

Finding an extension point

An extension point is an interface that extends org.pf4j.ExtensionPoint and is located in the api module of a service. Spinnaker exposes the following extension points:

Orca
- SimpleStage for creating a custom pipeline stage
- [PreconfiguredJobConfigurationProvider]https://github.com/spinnaker/spinnaker/blob/main/orca/orca-api/src/main/java/com/netflix/spinnaker/orca/api/preconfigured/jobs/PreconfiguredJobConfigurationProvider.java) for provisioning preconfigured Job stages
Echo
- EventListener for processing events posted into Echo

Look through the code or ask in the Spinnaker Slack to find extension points not listed here.

Example ExtensionPoint plugin

The pf4jStagePlugin creates a custom pipeline stage that waits a specified number of seconds before signaling success. Consult the Pipeline Stage Plugin Walkthrough for a detailed explanation of this plugin.

Interface (Non-ExtensionPoint) plugins

The second way you can create a plugin is to implement a regular Java interface that you find in a service. Your plugin uses the PF4J @Extension annotation but does not extend org.pf4j.ExtensionPoint.

Advantages:

Spinnaker loads the plugin in an isolated classpath

Disadvantages:

Requires a moderate knowledge of Spinnaker’s architecture and code
Plugin can break if the service’s interface changes

Example Interface plugin

The pf4jPluginWithoutExtensionPoint plugin extends the functionality of Kork’s SecretEngine . SecretEngine is a regular Java interface that does not import any PF4J classes. pf4jPluginWithoutExtensionPoint’s SillySecretEngine implements SecretEngine and uses the @Extension annotation to identify itself as a PF4J plugin. See the plugin project’s README and code for details on how this plugin works.

Spring plugins

When you can’t find an org.pf4j.ExtensionPoint to use or a Java interface to implement, you can create a plugin using Spring. This is should be done as a last resort, since the disadvantages outweigh the advantages.

Advantages:

Full control

Disadvantages:

Requires an expert knowledge of Spinnaker’s architecture and codebase
Requires working knowledge of Spring
High maintenance; plugin can break when Spinnaker dependencies and functionality change

Example Spring plugin

The Spring Example Plugin does not use a PF4J extension point or dependencies. It uses Spring components and was created to test various use cases. See the project for details.

Docs: Plugin Project Configuration

Mon, 01 Jan 0001 00:00:00 +0000

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!

Project Configuration

Keep the following recommendations and requirements in mind: - We recommend making the project a Gradle project. There is Gradle tooling to support plugin development. - You can add any dependencies you need to make your plugin successful.. TODO-CF this is almost certainly a lie when it comes to things that conflict with the dependencies in the compileOnly scope…

Gradle configuration

Some important aspects of your project’s gradle build:

gradle.properties

Organizing these values into gradle.properties is optional, but these versions are very much mandatory.

spinnakerGradleVersion=7.5.2
pf4jVersion=3.2.0
korkVersion=7.30.0
orcaVersion=8.2.0
version=1.2.3

Note that managing the version of your plugin here (version=1.2.3) requires modifying this file for each release. There are fancier ways (the example project uses a git tag strategy and additional gradle plugins) but those are outside the scope of this documentation.

Top-level build.gradle

// (1):
buildscript {
  repositories {
    maven { url "https://dl.bintray.com/spinnaker/gradle/" }
  }
  dependencies {
    classpath("com.netflix.spinnaker.gradle:spinnaker-extensions:$spinnakerGradleVersion")
  }
}

// (2):
plugins {
  //... other plugins you might be using
  id("com.moowork.node").version("1.3.1").apply(false)
}

// (3):
apply plugin: "io.spinnaker.plugin.bundler"
spinnakerBundle {
  pluginId = "Armory.RandomWaitPlugin"
  description = "An example of a PF4J based plugin, that provides a new stage."
  provider = "https://github.com/spinnaker-plugin-examples"
  version = rootProject.version
}

Notes:

The buildscript block brings in the spinnaker-extensions gradle tooling, which includes plugins for creating a bundle, ui-extension, and service-extension.
The plugins block imports the node plugin but does not apply it. This plugin is needed by the ui-extension to build the us assets.
At the top level we apply the io.spinnaker.plugin.bundler to define the name of the plugin bundle this project is producing along with bundle metadata.

UI-extension build.gradle

To build a UI extension with the base conventions, the only thing necessary is applying the io.spinnaker.plugin.ui-extension plugin.

TODO document what the ui-extension plugin supplies / supports. Maybe some of that is below?

apply plugin: "io.spinnaker.plugin.ui-extension"

Service extension build.gradle

Here are the basic things your service-extension gradle build needs. Note that the example project includes a bunch of additional configuration to configure kotlin for the plugin. The configuration below strips that out to just include the basic gradle configuration necessary for a JVM plugin, if you wish to develop plugins in kotlin refer to the gradle build from the example project.

// (1):
apply plugin: "io.spinnaker.plugin.service-extension"
apply plugin: "maven-publish"

// (2):
sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
  // (3):
  annotationProcessor("org.pf4j:pf4j:$pf4jVersion)

  // (4):
  compileOnly("com.netflix.spinnaker.kork:kork-plugins-api:$korkVersion")
  compileOnly("com.netflix.spinnaker.orca:orca-api:$orcaVersion")

  // (5):
  // implementation("com.something.my.plugin.needs:dependency:version")
}

// (6):
spinnakerPlugin {
  serviceName = "orca"
  pluginClass = "io.armory.plugin.stage.wait.random.RandomWaitPlugin"
}

Notes:

The io.spinnaker.plugin.service-extension and maven-publish are used for plugin bundling and metadata generation.
Spinnaker services require JDK 1.8 compatible bytecode.
Enable pf4j annotation processing to build plugin extension metadata
The plugin APIs are marked as compileOnly so as to not include them in the resulting plugin jar. These dependencies are loaded from the service’s classloader, not the plugin classloader.
You can include additional dependencies that your plugin requires. These dependencies will be bundled into the plugin and in a private classloader for the plugin.
The spinnakerPlugin block is used to generate plugin and bundle metadata. The serviceName is the spinnaker service this plugin extends (and should match the service api dependency brought in in (4) above).

IntelliJ Configuration

With the gradle configuraton above, you should be able to import your plugin into IntelliJ as a project.

UI-extension IDE configuration

Help us improve this section by submitting a pull request!

Service-extension IDE configuration

Help us improve this section by submitting a pull request!

Plugin debugging in a local service

If you have a local instance of a host service (in the pf4jStagePlugin example this is orca) running, you can link your plugin into that service with a plugin-ref that points to your local development workspace.

There are two options, depending on how you run the host service:

Running the host service in the IDE

If you have the ability to run a service locally in IntelliJ (the configuration for that is outside the scope of this document), then you can add configure your IntelliJ project with both the host service and your plugin in the same workspace.

Open the IntelliJ project you have configured for the host service, click the + button on the Gradle tab, and navigate to your plugin project’s build.gradle. This will include the plugin project in the workspace.

Attaching to a remote JVM process for the host service

You can debug a service extension in the IDE, provided you have an instance of the host service to attach a debugger to, and that the host service shares a filesystem with your plugin development workspace.

In your plugin project in IntelliJ, in the run configurations, add a configuration of type Remote.

Select “Attach to a remote JVM”

In use module classpath, select the main classpath from the service-extension plugin (helloworld-orca.main) in the example project.

Copy the command-line arguments for the JVM from this dialog, and ensure however you are launching the host service locally that it gets those JVM arguments.

Linking the plugin-ref to the host service

When you build your plugin project with gradle, it will produce a .plugin-ref file in the build/ directory for the plugin. You only need to do this once initially, and if your plugin dependencies are changed to regenerate it.

Once you have that file generated, navigate to the plugins directory for the host service, wherever you are running it. You can then create a symlink to the .plugin-ref file, and this will cause the host service to see your plugin and load the classes from your development workspace when the host service starts up.

For the example project:

$ cd /path/to/orca/plugins
$ ln -sf /path/to/dev/workspaces/spinnaker-plugin-helloworld/helloworld-orca/build/orca.plugin-ref

Now, when you attach your debugger to the host services, any breakpoints in your plugin code will be hit and you can step through them in your IDE, evaluate expressions, etc.

Docs: Pipeline Stage Plugin Walkthrough

Mon, 01 Jan 0001 00:00:00 +0000

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 current release 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!

Ensure your development environment is set up to run Orca locally.
Clone Orca branch release-1.19.x
Import into IntelliJ
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!

Obtain the Deck release-1.19.x branch.
Create a folder called plugins in the deck directory. Copy RandomWaitStageIndex.js to the new directory.

Add to deck\plugin-manifest.json:

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

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

If you change	Update values in these files
project name	`settings.gradle`, `build.gradle`
subproject name	`settings.gradle`

Spinnaker – Plugin Creators

Docs: Plugin Creators Overview

Requirements

Taxonomy

Plugin overview

ExtensionPoint plugins

Finding an extension point

Example ExtensionPoint plugin

Interface (Non-ExtensionPoint) plugins

Example Interface plugin

Spring plugins

Example Spring plugin

Docs: Plugin Project Configuration

Project Configuration

Gradle configuration

gradle.properties

Top-level build.gradle

UI-extension build.gradle

Service extension build.gradle

IntelliJ Configuration

UI-extension IDE configuration

Service-extension IDE configuration

Plugin debugging in a local service

Running the host service in the IDE

Attaching to a remote JVM process for the host service

Linking the plugin-ref to the host service

Docs: Pipeline Stage Plugin Walkthrough

Requirements

pf4jStagePlugin plugin

random-wait-orca

random-wait-deck

Building the release bundle

Debugging random-wait-orca in Orca locally

Debugging random-wait-deck in Deck locally

Plugin build and configuration files

`random-wait-orca`

`random-wait-deck`

Debugging `random-wait-orca` in Orca locally

Debugging `random-wait-deck` in Deck locally