Spinnaker – Plugin Creator Guide

Docs: Backend Service Extension Points

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

Project Setup

To enable plugins for a service, you only need to do two things:

Add implementation("com.netflix.spinnaker.kork:kork-plugins") to your {service}-core module.
Add @Import(PluginsAutoConfiguration::class) on your Main class or somewhere that will always be loaded.

Once the plugin framework is installed, you must create an API module to home your service extension points.

API Module

Plugins are all about the API. Ensure your project has a {service}-api module (called “the API module” from now on). The API module MUST NOT have other project module dependencies: Your {service}-core module (called the “core service module”) will actually depend on the API module, as it is the core’s and other modules’ responsibility to marshal between internal data structures and objects and the external API contracts.

Minimal transitive API module dependencies

The core service and plugins will evolve separately, so the API surface must be kept to a bare minimum, which includes interfaces and POJOs, but also api, implementation and runtime library dependencies.

Why avoid library dependencies?

Plugins are loaded into their own ClassLoader, but if the byte code of the API changes between what a Plugin is compiled against and what the service is compiled against, runtime exceptions will be thrown, causing the service to fail to start. Minimizing transitive dependencies reduces the risk of plugins breaking service deployments.

There are some “blessed” library dependencies. These libraries are considered fair-game to include as they are fairly stable modules or designed for extension point and plugin use:

com.netflix.spinnaker.kork:kork-annotations
com.netflix.spinnaker.kork:kork-exceptions
com.netflix.spinnaker.kork:kork-plugins-api
javax.inject:javax.inject
org.slf4j:slf4j-api

You are typically welcome to add other dependencies as you see fit, but understand the more dependencies added, the higher risk you’re exposing the service and plugins to breakages.

Language Choices

While the large parts of Spinnaker are written using Kotlin, including the entirety of the plugin framework, use of anything but Java in service API modules is strongly discouraged. Any JVM-based language requires additional dependencies, and those dependencies will need to be carefully managed. Furthermore, the service API module, as opposed to any of the other service modules, is a library module meant for external consumption: we cannot assume that people will want to use Kotlin or other languages built atop the JVM, so we should not burden them with the additional dependency.

Plugin developers are free to use whatever JVM language they like.

Illegal Module Dependencies

Some dependencies are simply a no-go. Here’s a non-exhaustive list of dependencies that must not be included in your API module dependencies:

Any Spring library
Any Jackson library

Don’t worry, there are established, safe patterns for exposing POJOs for Jackson serialization covered later.

Lombok is allowed, but discouraged. The Spinnaker project is looking to deprecate Lombok usage due to tooling difficulties, such as static code analysis. Please do not introduce it if the API module does not already have it.

The surface area of these libraries (and others like them) are so large and include so many transitive dependencies, it’s likely plugin developers will be unable to keep up with changes, and will have frequent ClassLoader issues when their plugin is used, meaning your service — despite having extension points — will be difficult to extend.

But what about kork-plugins-spring-api? That exposes Spring dependencies!

True, it does, but plugin developers are acknowledging and assuming the risk of using this up front — it’s the plugin developer’s choice in this case. We do not recommend using this module as a go-to.

Remote vs. In-Process Extension Points

Extension Points can be targeted for different drivers: in-process (JVM) or remote invocation (RPC, typically). While some extension points can implement both without issue, most extension points will need upfront design consideration on how you want extension points to be interacting with the service and vice-versa.

For in-process extension points, entire rich object trees can be passed between a plugin and service code quite easily, whereas in a remote world, only data (serialized POJOs) can be transmitted through the extension point contracts.

Remote
- Pro: Updates to plugins do not require service restarts.
- Pro: Does not affect core service startup times.
- Pro: In-process plugins can implement remote extension points as well.
- Pro: Plugins can be written in any technology stack the developer is familiar with.
- Con: Cannot integrate as deeply with core service.
- Con: Invocations will be more latent.
- Con: Network-related points of failure are more likely.
In-process
- Pro: Can more deeply integrate with core services than remote plugins.
- Pro: Simpler integration testing story.
- Con: Updates require service restarts / re-deployments.
- Con: Increases service resource utilization, slows down startup times.
- Con: Requires plugin developers to use JVM toolchains.

Remote extensions should be the preference whenever possible; they allow us (or whomever) to deliver changes to features separately from core service functionality and vice-versa. There are, however, times where choosing JVM is better or the only option:

If migrating existing functionality, it’s almost assured that it must be a JVM extension point. Examples of this would be Orca’s StageDefinitionBuilder extension point, or Keel’s ConstraintEvaluator extension point. Existing functionality can be bridged to remote extension points, however, see Retrofitting Existing Extension Points for Remote.
Library-level extensions. An easy example of this would be changing the Micrometer backend of services. Rather than compiling all Micrometer backends into the application, a plugin can be introduced to bring the dependencies along and then hook into each service’s Registry.

Consider how often an extension will be invoked. For example, if an extension point is called within a tight loop or is latency-sensitive, a remote driver may be a poor choice.

Reason about remote extension points as you would any other remote service call, because at the end of the day, that’s exactly what it is. Design APIs for idempotence: while you will be responsible for how extension points are called, Spinnaker’s remote delivery preference is for at-least-once delivery, so idempotent APIs are critical.

Getting Started in Extension Point Development

Common Guidance

Before getting into developing in-process or remote extension points, there are some common guidances that should be observed.

Limiting Exposure

Limiting the exposure of service internals must be a consideration while developing your extension point. While exposing the raw internals of a service is powerful, it makes the extension point more brittle and the core service more resistant to change. A more tightly-coupled extension point is powerful, but refactors may make it less likely for investment in the particular extension point.

Documentation

Extension Points are the entry point to services, as far as integrations are concerned, so they should be well documented. Normally, a service API module will already have static code analysis setup to require documentation, but these tools do not measure quality. Assume that consumers of this documentation are largely unfamiliar with the service codebase and link to relevant sources, and explain contextual behavior where it makes sense.

Null Safety

Being explicit about null safety is a critical aspect of extension point development. Use package-info.java to declare @NonnullByDefault (offered via kork-annotations) and explicitly set @Nullable where properties, methods or return types are nullable.

Note that these annotations are build-time only: You may still yet have to assert nullability within service integration points.

Stability Annotations

A service’s API module is going to be in varying states of stability between any given release. Stability annotations are provided, and should be used, whenever an extension point is created, both annotations are offered by kork-annotations:

@Alpha: Declares that a public API is subject to incompatible changes or even removal in a future release. Features that are in an Alpha state are disabled by default and enabling may introduce bugs. They further do not carry long-term support and may be dropped at any time and without notice. There are no requirements for backwards compatibility.
@Beta: Declares that a public API is subject to incompatible changes, but includes a commitment to support the feature long-term with the caveat that the implementation can still change (even dramatically). Beta features may be potentially enabled by default, and carry an implication that they are reasonably well-tested.

These annotations can be defined broadly on class, as well as specific methods and properties. The absence of any stability annotation indicates that the API is stable and supported.

Deprecations are also supported. Use of Java’s @Deprecated annotation should be used and additionally use @DeprecationInfo, which provides API module consumers more structured information on deprecations, including reasoning, EOL version, Github issue link, and so-on.

In-Process Extension Points

Developing an in-process extension point is easy! All you need to do is create an interface in the API module which implements SpinnakerExtensionPoint. For example:

import com.netflix.spinnaker.kork.plugins.api.internal.SpinnakerExtensionPoint

interface CoolExtensionPoint : SpinnakerExtensionPoint

The SpinnakerExtensionPoint interface is a subtype of PF4J’s ExtensionPoint interface, which has internal uses within the plugin framework, as well as creating a clear definition of what specific types in the service API module are extension points versus supporting types and code.

Extensions (plugin classes that implement SpinnakerExtensionPoint) may be wrapped in a proxy class for various purposes. In these cases, instanceof operations will need to use the getExtensionClass() method.

Aside from this one method, an ExtensionPoint interface can take any form needed, however there are many considerations that need to be thought of. For more information, see the API Design Considerations section of this guide.

There is currently a limitation that disallows use of abstract classes as SpinnakerExtensionPoints: Use interfaces only.

Remote Extension Points

TODO

Configuration
Transports (HTTP)
Lifecycle
Retrofitting existing code for remote

API Design Considerations

In-Process Considerations

TODO

Remote Considerations

TODO

Integrating Service Extension Points

Extensions will be exposed into the application much the same way any other component will be, however there are some notes specifically on dependency injection.

Dependency Injection

Extensions that implement your ExtensionPoint will be available for dependency injection within your service. However, because the plugin framework initializes plugins (and therefore extensions) late in the application lifecycle, it is often too late to auto-wire a List<MyExtensionPoint> into a service component. Furthermore, remote plugins’ extensions will likely be registered after a service starts up, and may create extensions long after service startup that need to be resolved.

There are currently 3 dependency injection options available:

ObjectProvider
ApplicationEventListener
A Registry

`ObjectProvider`

The ObjectProvider, and its superclass Provider, are a way of lazily resolving class dependencies. Often times, these types are used for breaking up circular dependency chains, but you can also use them for referencing extension points.

@Component
class MyServiceComponent(
  val extensions: ObjectProvider<List<MyExtensionPoint>>
) {

  fun doingSomeBusiness() {
    extensions.stream().peek { it.doStuff() }
  }
}

Events

The plugin framework emits an ExtensionCreated application event whenever an extension is initialized and injected into the service ApplicationContext. Your service components can listen for these events to update internal caches. This is the preferred method any time additional processing needs to occur on extensions before use within a component, as processing will only happen during write access, rather than on read access.

@Component
class MyServiceComponent(
  private val extensions: MutableList<MyExtensionPoint> = mutableListOf()
) {

  @EventListener(ExtensionCreated::class)
  private fun onExtensionCreated(e: ExtensionCreated) {
    extensions.add(e.bean)
  }

  fun doingSomeBusiness() {
    extensions.forEach { it.doStuff() }
  }  
}

Alternatively:

@Component
class MyServiceComponent(
  private val extensions: MutableList<MyExtensionPoint> = mutableListOf()
) : ApplicationEventListener<ExtensionCreated> {

  override fun onApplicationEvent(e: ExtensionCreated) {
    extensions.add(e.bean)
  }
}

A `Registry`

Plugins could be offered a custom Registry class for them to decide what extensions they want to register into the service. This pattern is a little more hands-on for plugin developers, and does tend to force extensions to be in-process, but there may be valid use cases when the other options will not work.

@Component
class MyExtensionPointRegistry {
  internal val extensionPoints: MutableList<MyExtensionPoint>

  fun register(extension: MyExtensionPoint) {
    extensionPoints.add(extension)
  }
}

class MyServiceComponent(
  private val registry: MyExtensionPointRegistry
) {

  fun doingSomeBusiness() {
    registry.extensions.forEach { it.doStuff() }
  }
}

Plugin code:

@SpinnakerExtension
class MyExtension(
  private val registry: MyExtensionPointRegistry
) : MyExtensionPoint {
  init {
    registry.register(this)
  }
}

Jackson Mixins

In many cases, serialization of extension point objects may be needed. Jackson (and similar serialization libraries) are illegal within the API module, but fortunately Jackson Mixins can be used to circumvent this limitation and still get full control over serialization via annotations.

As an example, we’ll use Keel’s ResourceKind type, as defined in keel-api:

data class ResourceKind(
  val group: String,
  val kind: String,
  val version: String
)

In keel-core, a ResourceKindMixin interface is defined:

@JsonSerialize(using = ToStringSerializer::class)
@JsonDeserialize(using = ResourceKindDeserializer::class)
interface ResourceKindMixin

And then finally linked together by a the KeelApiModule (a Jackson Module subtype):

object KeelApiModule : SimpleModule("Keel API") {
  override fun setupModule(context: SetupContext) {
    setMixInAnnotations<ResourceKind, ResourceKindMixin>()
  }
}

internal inline fun <reified TARGET, reified MIXIN> SetupContext.setMixInAnnotations() {
  setMixInAnnotations(TARGET::class.java, MIXIN::class.java)
}

While this specific example exhibits setting custom serializer / deserializer classes for the type, @JsonProperty and other annotations are also available for use on the interface mixin. Following this pattern, you will be able to fully customize serialization while keeping Jackson out of the API module classpath completely.

Testing Extension Points

There are four areas of testing when developing extension points:

Unit tests of extension types and supporting classes.
Development of Plugin TCKs (Technology Compatibility Kit)
Service Plugin Tests
Service Unit Tests

Of these, 1 and 4 should be immediately familiar: Firstly, we need to test the extension point code (if any exists) in the service API module’s test source set. And fourth, we need to ensure the service has tests around the areas where extension points are both loaded and invoked.

Plugin TCKs and Plugin Tests, however, are specific concepts for enabling stable plugin extension points.

Plugin TCKs (Technology Compatibility Kit)

Plugin developers need a way of asserting their plugin will work when installed into a service. Plugin TCKs are for this purpose: They are artifacts plugin developers use to unit test their plugins. TCKs can and should include tests as well as any test helpers and DSLs to reduce manual toil in writing tests.

Every service has a baseline suite of TCK tests that plugin developers can use, and also include a harness for starting the plugin under test within an in-memory version of the service. All TCK suites are found in {service}-api-tck (called “the TCK module”).

When building a new SpinnakerExtensionPoint, it is highly recommended to offer some baked-in tests developers can use to assert against a contract greater than just the API.

An example of some TCKs can be found in the plugin framework for validating enabled and disabled plugins via [PluginsTck](https://github.com/spinnaker/kork/blob/master/kork-plugins-tck/src/main/kotlin/com/netflix/spinnaker/kork/plugins/tck/PluginsTck.kt).

Service Plugin Tests

On the other side of Plugin TCKs, Service Plugin Tests allow you to write dummy plugins into the service for testing. These plugins are compiled at runtime, and can be constructed programmatically as needed. These suite of tests are particularly useful for performing integration tests of extension points, and testing for specific use cases / bug fixes.

These tests are located in {service}-plugin-tests modules.

There is currently no official support for multi-service plugin integration tests.

Docs: Frontend Plugin Development

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

Overview of Frontend plugins

Frontend plugins provide a way to change the behavior of Deck, Spinnaker’s UI service. You can add configuration and validation for new stages provided by Orca plugins, override existing components with your own implementation, or add new Kubernetes kind definitions for custom resources in your environment. Spinnaker loads plugins at runtime through Gate.

You can write plugins in any JavaScript-compatible language, but the development tooling is designed for JavaScript and TypeScript.

The following are examples of Deck features that you can override:

ApplicationIcon , replace the icon used to represent applications in Deck.
ServerGroupHeader , replace how pod status is reported in Deck.
SpinnakerHeader , replace the top navigation header.

The following projects demonstrate adding new stages to Spinnaker:

nomadPlugin , adding a Nomad provider to Spinnaker.
pf4jStagePlugin , adding a sample random wait stage to Spinnaker.

Before you begin

Make sure you have the following tools installed:

You also need access to a Spinnaker instance >= 1.20.6 running in a Kubernetes cluster.

This guide focuses on a frontend plugin, but if you need help configuring a backend plugin, see the Plugin Project Configuration and Backend Extension Points guides.

Plugin scaffolding

You can write a Frontend plugin as standalone or as part of a broader set of functionality. In both cases, you need the Gradle toolchain to build and release your plugin. The Deck project has the @spinnaker/pluginsdk NPM package that you can use to generate your new frontend plugin’s project structure and configuration files.

Create the plugin project structure

For a new plugin, create a top-level directory:

mkdir my-plugin

Then, from the root of the my-plugin directory, run the @spinnaker/pluginsdk scaffold script to create your frontend plugin:

npx -p @spinnaker/pluginsdk scaffold

The script asks a few questions about your plugin. Enter the requested information and wait for the command to complete:

npx: installed 117 in 6.229s
Enter the short name for your plugin (default: myplugin): my-plugin
Directory to scaffold into (default: my-plugin-deck):
Deck plugin scaffolded into my-plugin-deck
Installing dependencies using 'yarn' and 'npx check-peer-dependencies --install' ...

The script creates the following project structure:

my-plugin
├──  my-plugin-deck
    ├── .eslintrc.js
    ├── .prettierrc.js
    ├── package.json  
    ├── my-plugin-deck.gradle  
    ├── tsconfig.json  
    ├── rollup.config.js  
    ├── yarn.lock  
    ├── node_modules  
    └── src  
        ├── index.ts  
        ├── WidgetizeStage.less  
        └── WidgetizeStage.tsx

You may see this scaffold command fail to resolve dependencies initially. If this is the case, you can run the check-peerdependencies and check-plugin commands from the my-plugin-deck directory until these errors are resolved.

cd my-plugin-deck
npx check-peer-dependencies --install

npx check-plugin --fix

You should now be able to successfully build the plugin:

yarn && yarn build

Gradle Configuration

In order to build and release your plugin, you need to ensure that you have your Gradle environment configured correctly. Follow the advice in the Plugin Project Configuration document up to the UI-extension build.gradle section.

The development tooling uses this top-level Gradle file to create a simple plugin metadata file. See the Build and release section to learn how to configure the rest of this file to create release distributions and proper plugin manifest metadata.

Development workflow

The plugin resources created by the scaffold command include functionality to run your plugin locally, provided that you can connect to an external Spinnaker instance. The most common way to do this is to port-forward your running Deck instance to your local machine using kubectl.

kubectl port-forward service/spin-deck 90001:9000

This forwards Deck to your local machine on port 9001. Then you can run your plugin locally on port 9000 using yarn develop.

DEV_PROXY_HOST=http://localhost:9001 yarn develop

You should now be able to navigate to http://localhost:9000 and access the Deck UI. Create a new pipeline and search for the Widgetize stage to verify that Spinnaker loaded the frontend plugin correctly.

You can also verify your plugin loaded correctly by navigating to http://localhost:9000/plugin-manifest.json. You should see at least two plugins listed, the one with your pluginId as well as a plugindev.livereload plugin. The development tooling uses plugindev.livereload to reload Deck on each code change in your plugin directory.

Fix CORS errors when using a remote deck instance

During development, you may run into CORS -related errors if your Deck service runs on an address other than localhost. If you can, consider modifying your Gate instance to allow for CORS requests during development.

Add new stages

The plugin SDK enables the addition of new stages and kinds within Spinnaker. These additions are often accompanied by changes to Orca and related services. If you haven’t started work on these backend components, see the Backend Extension Points guide.

The scaffold command creates the most up-to-date schema example, which you should use as your template when you develop your plugin. If you are writing a plugin that targets an older version of Spinnaker, you may need to refer to existing stages for the Spinnaker release to ensure you’re following the correct schema.

In general, a Deck stage has these elements:

A StageConfig React component.
- This component wraps FormikStageComponent and refers to the React StageForm component.
A StageForm React component.
- This component provides a set of FormikFormField components that encapsulate the configuration options for your stage.
A (optional) validate function.
- The validate function validates a stage configuration. When added to a stage object, validate is called whenever input changes in the config form.
A Stage object that encapsulates the previous components.
- This object is passed to the plugin config object and registered when Deck starts.

You can define more than one stage per plugin. When you’re ready to register your plugin and test in Deck, add all your stages to the stage field in your plugin index.ts file like so:

import { IDeckPlugin } from '@spinnaker/core';
import { widgetizeStage } from './WidgetizeStage';

export const plugin: IDeckPlugin = {
  stages: [widgetizeStage],
};

Override existing components

You can also override existing components within Deck, so long as they have an Overridable annotation or are registered as an overridable component. In this use case, you define your replacement component and then leverage the initialize method of your plugin object to override the component when it is loaded.

For example, if you want to remove the ability to modify Application configuration in Deck, you define a component like this:

import React from 'react';

export const InvisibleConfig = () => {
  return <h1>No config here!</h1>;
}

In order to override the component, you need to know the Application configuration registration key. You can find its definition in the GitHub Deck project, ApplicationConfig.tsx . There, you find the Overridable annotation is applicationConfigView. Then, in your index.ts file where you define your plugin object, you override that component in the initialize method. For example:

import { IDeckPlugin, overrideRegistrationQueue } from '@spinnaker/core';
import { InvisibleConfig } from './InvisibleConfig';

export const plugin: IDeckPlugin = {
  initialize: () => {
    overrideRegistrationQueue.register(InvisibleConfig, 'applicationConfigView')
  }
};

Once installed, you see the Application configuration page now displays the h1 header.

Build and release

Building and releasing requires adding a distribution repository, building and committing changes for the plugin, and hosting the plugin.

Create plugin packages

Creating a plugin distribution starts from the root of your plugin project. The releaseBundle task is responsible for creating zip distributions of all plugin code and storing it in the build/distributions directory. Run the releaseBundle task to get started:

./gradlew releaseBundle

If you find the zip archive doesn’t contain all your plugin code, make sure that you’ve included each plugin sub-directory in the parent build. You can do that by editing the settings.gradle file and ensuring that each project is included. For example:

// file: my-plugin/settings.gradle

// other configuration ...

include "my-plugin-deck"

// other configuration ...

Create distribution files

Spinnaker needs a repositories.json file and a plugins.json file to install a plugin. repositories.json represents a set of pointers to plugin files, and plugins.json lists all versions of a particular plugin. See the Plugin Users Guide for more information.

The format of the repositories.json file looks like this:

[
    {
      "id": "myPluginRepo",
      "url": "https://raw.githubusercontent.com/my-org/my-plugin-repo/master/plugins.json"
    }
]

The id key uniquely identifies your plugin repository. The url points to where your keep your plugins.json file. This URL can be any URI so long as Spinnaker can reach it.

The releaseBundle command that generates the plugin packages also generates required metadata. You can find this metadata in the build/distributions/plugin-info.json file. You must provide the value for the url key. The value is the location of your plugin zip file. You can store the file in any location that Spinnaker can access.

Here is an example plugins.json file’s contents:

[
  {
    "id": "My.Plugin.Id",
    "description": "This a sample plugin.",
    "provider": "https://github.com/my-organization",
    "releases": [
      {
        "version": "0.1.0",
        "date": "2021-03-09T17:30:00.948341Z",
        "requires": "deck>=0.0.0",
        "sha512sum": "a91cb7d412a25ca5e1b2d72e14ab499986d5773ae8016721fbefd0adf430e33b75e8e61bac92244bbbe4811f118724ec6e2bb568fdd8181a9e11327a96b45da9",
        "url": "https://github.com/my-organization/my-plugin/blob/master/my-plugin-v0.1.0.zip?raw=true"
      }
    ]
  }
]

You can store the repositories.json and plugins.json in any location that Spinnaker can reach. Most developers store these files in a repository separate from the plugin code.

Create an installation README for your users

In addition to explaining what your plugin does, you should include a YAML snippet showing your plugin’s configuration. For example:

profiles:
  spinnaker:
    spinnaker:
      extensibility:
        plugins:
          # The plugin id you defined in your build.gradle
          My.Plugin.Id:
            enabled: true
            # This must be a SemVer-compatible string
            # (i.e. do not include a `v` in front of the version string)
            version: "0.1.0"
  gate:
    spinnaker:
      extensibility:
        # This snippet is necessary so that Gate can serve your plugin code to Deck
        deck-proxy:
          enabled: true
          plugins:
            My.Plugin.Id:
              enabled: true
        repositories:
          myPluginRepo:
            enabled: true
            url: https://raw.githubusercontent.com/my-organization/my-plugin-repo/master/repositories.json

Next steps

Note: If you use the open source Spinnaker Operator to install and manage Spinnaker, see that product’s documentation for how to deploy a plugin.

Docs: Plugin Compatibility Testing

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

A plugin can be executed inside of a Spinnaker version that is different than the version it was compiled against. For example, a plugin compiled against Spinnaker 1.20 might be compatible with Spinnaker versions up to 1.23.

This range is important for plugin developers so that they can support users across Spinnaker versions; it’s important for plugin consumers so that they can safely install and upgrade plugins. Fortunately, testing can resolve this compatibility range automatically.

Integration testing

To start, you should write Spring Boot-style integration tests using service test fixtures .

The Spinnaker plugin example repositories have examples of these kinds of tests.

These integration tests have good properties. They execute a service’s main and demonstrate that a plugin can be loaded into the service at runtime. You can inject Spring’s ApplicationContext into your test class and attempt to retrieve the beans defined by your plugin.

You can also use these tests to verify the end-to-end behavior of your plugin. For example, if you’re writing a new stage as a plugin, you can ask Orca’s /orchestrate endpoint to execute a pipeline that includes your new stage type.

Automated compatibility testing

These integration tests demonstrate that a compiled plugin can execute inside of a service at runtime. By executing a test multiple times but changing the underlying service version, we can resolve which versions of Spinnaker a plugin is compatible with.

Spinnaker’s Gradle compatibility-test-runner plugin does exactly this: you provide a list of Spinnaker versions; it runs your integration tests against those versions.

Before using this Gradle plugin, check that your integration tests depend on Spinnaker’s exported Gradle platforms, which take the form <service>-bom. For example, if your test relies on orca-api-tck, your plugin’s subproject build file should look something like this:

dependencies {
  // ...
  testImplementation("com.netflix.spinnaker.orca:orca-bom:<orca-version>")
  testImplementation("com.netflix.spinnaker.orca:orca-api-tck") // Don't specify a version here - it will be resolved by `orca-bom` above.
}

To use the test runner, configure your plugin’s build files:

// Inside root project
plugins {
  id("io.spinnaker.plugin.bundler").version("8.6.0") // Must be 8.6.0 or later.
}

spinnakerBundle {
  // ...
  compatibility {
    spinnaker = ["1.21.1", "1.22.0"] // Set of Spinnaker versions to test against.
  }
}

// Inside service extension subproject
apply plugin: "io.spinnaker.plugin.compatibility-test-runner"

The plugin will create a set of tasks: a set of compatibilityTest-<subproject-name>-<spinnaker-version> tasks, and a top-level compatibilityTest task that will run all of the compatibility test subtasks.

How does it work?

The test runner dynamically creates Gradle source sets for each top-level Spinnaker version you declare and re-writes your test dependencies to depend on the service Gradle platform version (e.g., com.spinnaker.netflix.orca:orca-bom) that corresponds to those Spinnaker versions. It does not alter your plugin’s compile or runtime classpaths. Your plugin compiles against version X; the test runner runs your plugin inside Spinnaker Y and Z.

Docs: Plugin Project Configuration

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

Plugins are an evolving feature. The easiest way to set up a new plugin project is to copy one of the spinnaker-plugin-examples projects that most closely resembles what you want to do.

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=8.10.1
pf4jVersion=3.2.0
korkVersion=7.99.1
orcaVersion=2.19.0-20210209140018
kotlinVersion=1.3.50

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

// file: my-plugin/build.gradle

buildscript {
  repositories {
    mavenCentral()
  }
}

// (1):
plugins {
  id("com.moowork.node").version("1.3.1").apply(false)
  id("io.spinnaker.plugin.bundler").version("$spinnakerGradleVersion")
  id("com.palantir.git-version").version("0.12.2")
  //... other plugins you might be using
}

// (2):
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
}

// (3):
version = normalizedVersion()

subprojects {
  group = "io.armory.plugin.manifest"
  version = rootProject.version
}

String normalizedVersion() {
  String fullVersion = gitVersion()
  String normalized = fullVersion.split("-").first()
  if (fullVersion.contains("dirty")) {
    return "$normalized-SNAPSHOT"
  } else {
    return normalized
  }
}

Notes:

The plugins block imports the node plugin but does not apply it. This plugin is needed by the ui-extension to build assets. It also imports the spinnaker-extensions gradle tooling.
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.
Utility methods for determining the latest version to use when building release distributions, derived from git tags.

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.

// file: my-plugin/my-plugin-deck/build.gradle
apply plugin: "io.spinnaker.plugin.ui-extension"

This plugin will provide tasks for assembling and creating release distributions that are automatically called from the parent Gradle file when creating release builds.

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.

// file: my-plugin/my-plugin-orca/build.gradle

// (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: Test a Pipeline Stage Plugin

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

Overview

This document is deprecated and out of date. Halyard is no longer supported but the document is being left as a useful reference

This guide explains how to set up a local Spinnaker environment on your Mac or Windows environment so you can test the pf4jStagePlugin, which has both Orca and Deck components. Spinnaker services running locally communicate with the other Spinnaker services running in a local VM. Although this guide is specific to the pf4jStagePlugin, you can adapt its contents to test your own plugin.

Software for development:

Java Development Kit , 11
Groovy , 3.0.3
Gradle
Yarn for building and running Deck
Multipass , 1.3.0
IntelliJ IDEA , 2020.1.2, with the JetBrains Kotlin plugin
Spinnaker installed using Minnaker

Specific to this guide:

Orca , branch release-2026.0.x
Deck , branch release-2026.0.x
pf4jStagePlugin , v1.1.14

Spinnaker setup used in this guide:

OSX or Windows using IP {my-workstation-ip} and the VM using {my-vm-ip}
Orca running on {my-workstation-ip}:8083
Deck running on {my-workstation-ip}:9000
All other services running in the VM on {my-vm-ip}

Before you begin

You have read the Plugin Creators Guide Overview
Your workstation has at least 16GB of RAM and 30GB of available storage
You have installed JDK 11; see AdoptOpenJDK for installation instructions or install using Homebrew
You have installed Groovy
You have installed Multipass
You have installed IntelliJ and the Kotlin plugin
You know how to run and debug an application using IntelliJ

Install Spinnaker in a Multipass VM

Launch a Multipass VM with 2 cores, 10GB of memory, 30GB of storage.
```
multipass launch -c 2 -m 10G -d 30G
```
Get the name of your VM.
```
multipass list
```
Access your VM.
```
multipass shell <vm-name>
```

Download and unpack Minnaker (an old image that has some spinnaker tooling)

curl -LO https://github.com/armory/minnaker/releases/download/0.0.20/minnaker.tgz
tar -xzvf minnaker.tgz

Install Spinnaker.

The minnaker/scripts directory contains multiple scripts. Use the no_auth_install script to install Spinnaker in no-auth mode so you can access Spinnaker without credentials. Be sure to use the -o option to install the open source version of Spinnaker rather than Armory Spinnaker.
```
./minnaker/scripts/no_auth_install.sh -o
```
If you accidentally forget the -o option, run ./minnaker/scripts/switch_to_oss.sh to install open source Spinnaker.

The script prints out the IP address of Minnaker after installation is complete.

Check pod status:
```
kubectl -n spinnaker get pods
```
Consult the Minnaker README for basic troubleshooting information if you run into issues.
Revert Spinnaker to 1.20.6.

Minnaker forwards hal commands to the Halyard pod so you don’t need to access the pod itself.
```
 hal config version edit --version 1.20.6
 hal deploy apply
```

Configure Minnaker to listen on all ports.

./minnaker/scripts/utils/expose_local.sh

This creates a load balancer for each service. Console output is similar to:

NAME                                READY   STATUS    RESTARTS   AGE
minio-0                             1/1     Running   0          18h
mariadb-0                           1/1     Running   0          18h
halyard-0                           1/1     Running   0          18h
spin-redis-664df6f896-b5px8         1/1     Running   0          18h
svclb-spin-clouddriver-lcmrq        1/1     Running   0          10m
svclb-spin-redis-24qf6              1/1     Running   0          10m
svclb-spin-front50-8hchk            1/1     Running   0          10m
svclb-spin-orca-9t89s               1/1     Running   0          10m
svclb-spin-gate-gn6g5               1/1     Running   0          10m
svclb-spin-deck-26vpf               1/1     Running   0          10m
svclb-spin-echo-s6zdv               1/1     Running   0          10m
svclb-spin-rosco-qwfhv              1/1     Running   0          10m
spin-deck-55b88d5fb9-v2ngf          1/1     Running   0          10m
spin-front50-8fd4f9459-fwpzc        1/1     Running   0          10m
spin-rosco-6885b6df45-jqkl9         1/1     Running   0          10m
spin-gate-75df95744b-7zvp5          1/1     Running   0          10m
spin-orca-766f9bbf7b-cw9f7          1/1     Running   0          10m
spin-echo-9bbcd9df8-td4rt           1/1     Running   0          10m
spin-clouddriver-55bc94ddcc-4d7cd   1/1     Running   0          10m

Configure Minnaker for local external services

Decide which Spinnaker services you want to run locally. This example uses Orca and Deck.

Configure Minnaker to expect the relevant services to be external:

./minnaker/scripts/utils/external_service_setup.sh orca deck

Output is similar to:

Generated deploymentConfigurations[0].deploymentEnvironment.customSizing:
spin-orca:
  replicas: 0
spin-deck:
  replicas: 0
Generated local /etc/spinnaker/.hal/default/profiles/spinnaker-local.yml:
--------------
services:
  orca:
    baseUrl: {my-vm-ip}:8083
  deck:
    baseUrl: {my-vm-ip}:9000
--------------
Place this file at '~/.spinnaker/spinnaker-local.yml' on your workstation
--------------
services:
  clouddriver:
    baseUrl: {my-workstation-ip}:7002
  redis:
    baseUrl: {my-workstation-ip}:6379
  front50:
    baseUrl: {my-workstation-ip}:8080
  orca:
    host: 0.0.0.0
  gate:
    baseUrl: {my-workstation-ip}:8084
  deck:
    host: 0.0.0.0
  echo:
    baseUrl: {my-workstation-ip}:8089
  rosco:
    baseUrl: {my-workstation-ip}:8087
--------------

This script creates a spinnaker-local.yml on the VM that indicates the IPs where Orca and Deck are running. Furthermore, the script generates Spinnaker configuration content that you need to copy on your OSX workstation. This content tells your locally running services where the rest of the Spinnaker services are running.

Note: external_service_setup.sh removes the previous configuration each time you run it.

Configure your workstation for the local services

Copy the services section between the dotted lines in the terminal output from the executing the external_service_setup.sh script. Create or edit the ~/.spinnaker/spinnaker-local.yml file on your workstation and paste the previously copied services snippet into it.

The spinnaker-local.yml has this content:

services:
  clouddriver:
    baseUrl: {my-workstation-ip}:7002
  redis:
    baseUrl: {my-workstation-ip}:6379
  front50:
    baseUrl: {my-workstation-ip}:8080
  orca:
    host: 0.0.0.0
  gate:
    baseUrl: {my-workstation-ip}:8084
  deck:
    host: 0.0.0.0
  echo:
    baseUrl: {my-workstation-ip}:8089
  rosco:
    baseUrl: {my-workstation-ip}:8087
--------------

Clone the plugin and required services

Clone the Orca and Deck release-1.20.x branches that correspond to the Spinnaker 1.20.6 version you installed using Minnaker. Then clone pf4jStagePlugin v1.1.14, which works with Spinnaker 1.20.6.

git clone --single-branch --branch v1.1.14 https://github.com/spinnaker-plugin-examples/pf4jStagePlugin.git
git clone --single-branch --branch release-1.20.x https://github.com/spinnaker/orca.git
git clone --single-branch --branch release-1.20.x https://github.com/spinnaker/deck.git

Run Orca in IntelliJ

Open the Orca project in IntelliJ.
- If you don’t have a project open, you see a Welcome to IntellJ IDEA window.
  1. Click Open or Import
  2. Navigate to your Orca directory
  3. Click on build.gradle and click Open
  4. Select Open as Project
- If you already have one or more projects open, do the following:
  1. Use the menu File > Open
  2. Navigate to your Orca directory
  3. Click on build.gradle and click Open
  4. Select Open as Project
Grab a beverage and snack while you wait for IntelliJ to finish indexing the project.
If you have multiple JDKs installed, configure the Orca project to use JDK 11.

Through the next few steps, if you see an Unable to find Main log message or fields are grayed out, reimport the project:

View > Tool Windows > Gradle
In the Gradle window, right click “Orca” and then click Reimport Gradle Project
Create a Run Configuration.

You can skip the following steps if IntelliJ automatically creates a “Main” Run Configuration. Rename “Main” to “RunOrca”.
1. Click the Add Configuration or Edit Configurations button to open the Run/Debug Configurations window.
2. Click the + button to create a new configuration.
3. Select Application.
4. Enter “RunOrca” in the Name field.
5. Main class Click the … button. Wait for the list to load and then select Main (com.netflix.spinnaker.orca). Alternately, click on Project and navigate to orca > orca-web > src > main > groovy > com.netflix.spinnaker > orca > Main.
6. In the dropdown for Use classpath of module, select orca-web_main
7. Click Apply and then OK.
Run orca using the RunOrca configuration.

Success output is similar to:
```
INFO 18111 --- [main] com.netflix.spinnaker.orca.Main: [] Started Main in 11.123 seconds (JVM running for 11.933)
```
If Orca can’t find Redis, make sure your Minnaker VM is running and that all the Spinnaker services are ready.

You can stop running Orca after you have verified that you can successfully run it.

Build the plugin

Navigate to the pf4jStagePlugin directory and execute:

./gradlew releaseBundle

The build process creates files you need in later steps:

random-wait-orca/build/Armory.RandomWaitPlugin-orca.plugin-ref
random-wait-deck/build/dist/index.js

Configure Orca for the plugin

Create a top-level plugins directory in your Orca project.
Copy the Armory.RandomWaitPlugin-orca.plugin-ref file to the plugins directory.

Create the orca-local.yml file in ~/.spinnaker/ with the following contents:

spinnaker:
  extensibility:
    plugins:
      Armory.RandomWaitPlugin:
       enabled: true
       version: 1.1.14
       extensions:
         armory.randomWaitStage:
           enabled: true
           config:
             defaultMaxWaitTime: 20

This tells Spinnaker to enable and use the plugin.

Import the pf4jStagePlugin project into IntelliJ

In IntelliJ, link the pf4jStagePlugin project to your Orca project.
1. Open the Gradle window in your Orca project if it’s not already open (View > Tool Windows > Gradle).
2. In the Gradle window, click the + sign to link your pf4jStagePlugin Gradle project.
3. Navigate to your pf4jStagePlugin directory , select the build.gradle file, and click Open.
In the Gradle window, right click orca and click Reimport Gradle Project.

You can now run or debug Orca and the plugin using IntelliJ.

Configure Deck for the plugin

Update the deck/plugin-manifest.json with the plugin information.

 [
 	{
 		"id": "Armory.RandomWaitPlugin",
 		"url": "./plugins/index.js",
 		"version": "1.1.14"
 	}
 ]

For development, the values in id and version can be any value.

Create a deck/plugins directory and symlink random-wait-deck/build/dist/index.js to deck/plugins/index.js. For example:
```
cd <path-to-deck>
ln -s <path-to-pf4jStagePlugin>/random-wait-deck/build/dist/index.js plugins/index.js
```

Run the plugin and Orca in IntelliJ

Create a new build configuration.
1. Click Edit Configurations…
2. In the Run/Debug Configurations window, click the + icon and then select Application.
3. Fill in fields 1-6 with the following:
  1. Name: “Build and Test Plugin”
  2. Main class: “com.netflix.spinnaker.orca.Main”
  3. VM options: “-Dpf4j.mode=development”
  4. Use classpath of module: “orca-web_main”
  5. JRE: 11
  6. Before launch Build Project (remove Build)
1. Click OK.

Run orca and the pf4jStagePlugin using the Build and Test Plugin configuration. On successful launch, you see a “Completed initialization” log statement in the console:

 020-05-12 16:03:44.274  INFO 6973 --- [0.0-8083-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : [] Initializing Spring DispatcherServlet 'dispatcherServlet'
INFO 6973 --- [0.0-8083-exec-1] o.s.web.servlet.DispatcherServlet        : [] Initializing Servlet 'dispatcherServlet'
INFO 6973 --- [0.0-8083-exec-1] o.s.web.servlet.DispatcherServlet        : [] Completed initialization in 16 ms

If you see error messages about Redis, make sure all the pods in your Spinnaker instance are READY. You can check the IP address and port for each service in ~/.spinnaker/spinnaker-local.yml.

Plugin loading messages appear near the top of the Orca log. You should see statements similar to:

INFO 90843 --- [main] org.pf4j.AbstractPluginManager: [] Plugin 'Armory.RandomWaitPlugin@unspecified' resolved
INFO 90843 --- [main] org.pf4j.AbstractPluginManager: [] Start plugin 'Armory.RandomWaitPlugin@unspecified'
INFO 90843 --- [main] i.a.p.s.wait.random.RandomWaitPlugin: [] RandomWaitPlugin.start()

Build and run Deck

The Deck project README has instructions for building and running Deck locally.

Build Deck by executing yarn from the deck directory.

Start Deck with the API_HOST argument, which is the Gate URL.

cd deck
yarn
API_HOST={my-workstation-ip}:8084 AUTH_ENABLED=false yarn start

Verify the plugin loads in Deck

Access the the Spinnaker UI at http://localhost:9000.
Go to Applications > spin > PIPELINES.
Create a new pipeline.
Add a new stage.
Look for “Random Wait” in the Type select list.

Troubleshooting

You can use the Developer Tools in your browser to troubleshoot Deck plugin issues.

Look for plugin-manifest.json and index.js. It’s normal to see 3 plugin-manifest.json HTTP requests. The first one is from Deck - you created this file in the Configure Deck for the plugin section above. The next two from Gate are not relevant for local development. If you don’t see the plugin-manifest.json and index.js HTTP requests, check the Console tab for errors. Also verify that the content in your plugin-manifest.json file is correct.

Debug the backend of the plugin

If you want to debug the backend component of the plugin without a working Deck component, you can create a new stage in the UI and configure it using JSON.

Start the Build and Test Plugin configuration in Debug mode.
Start Deck.
Access the the Spinnaker UI at http://localhost:9000.
Go to Applications > spin > PIPELINES.
Create a new pipeline.
Add a new stage.
Do not choose a stage from the Type select list. Instead, click Edit stage as JSON to open the Edit Stage JSON window.
Paste this content in the text box:
```
{
  "maxWaitTime": 15,
  "name": "Test RandomWait",
  "type": "randomWait"
 }
```
- maxWaitTime: number of seconds; you get the maxWaitTime field name from the variable passed into the RandomWaitInput primary constructor
- name: name of the new stage
- type: use the value returned by the <code>getName</code> function in RandomWaitStage
Click Update Stage.
Click Save Changes.
Go back to the PIPELINES screen.
Start Manual Execution and watch the stage wait for the specified number of seconds.

Resources

You can ask for help with plugins in the Spinnaker Slack ’s #plugins channel.

Spinnaker – Plugin Creator Guide

Docs: Backend Service Extension Points

Project Setup

API Module

Minimal transitive API module dependencies

Language Choices

Illegal Module Dependencies

Remote vs. In-Process Extension Points

Getting Started in Extension Point Development

Common Guidance

Limiting Exposure

Documentation

Null Safety

Stability Annotations

In-Process Extension Points

Remote Extension Points

API Design Considerations

In-Process Considerations

Remote Considerations

Integrating Service Extension Points

Dependency Injection

ObjectProvider

Events

A Registry

Jackson Mixins

Testing Extension Points

Plugin TCKs (Technology Compatibility Kit)

Service Plugin Tests

Docs: Frontend Plugin Development

Overview of Frontend plugins

Before you begin

Plugin scaffolding

Create the plugin project structure

Gradle Configuration

Development workflow

Fix CORS errors when using a remote deck instance

Add new stages

Override existing components

Build and release

Create plugin packages

Create distribution files

Create an installation README for your users

Next steps

Docs: Plugin Compatibility Testing

Integration testing

Automated compatibility testing

How does it work?

Docs: Plugin 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: Test a Pipeline Stage Plugin

Overview

This document is deprecated and out of date. Halyard is no longer supported but the document is being left as a useful reference

Before you begin

Install Spinnaker in a Multipass VM

Configure Minnaker for local external services

Configure your workstation for the local services

Clone the plugin and required services

Run Orca in IntelliJ

Build the plugin

Configure Orca for the plugin

Import the pf4jStagePlugin project into IntelliJ

Configure Deck for the plugin

Run the plugin and Orca in IntelliJ

Build and run Deck

Verify the plugin loads in Deck

Troubleshooting

Debug the backend of the plugin

Resources

`ObjectProvider`

A `Registry`