Derrick Plugin SDK

This repository is a Go library that enables users to write custom Derrick plugins. Derrick supports plugins for builders, deployment platforms, release managers, and more. Derrick plugins enable Derrick to utilize any popular service providers as well as custom in-house solutions.

Plugins in Derrick are separate binaries which communicate with the Derrick application; the plugin communicates using gRPC, and while it is theoretically possible to build a plugin in any language supported by the gRPC framework. We recommend that the developers leverage the Derrick SDK.

Simple Plugin Overview

To initialize the plugin SDK you use the Main function in the sdk package and register Components which provide callbacks for Derrick during the various parts of the lifecycle.

package main

import (
  sdk "github.com/nomatronio/derrick-plugin-sdk"
)

func main() {

  sdk.Main(sdk.WithComponents(
    // Comment out any components which are not
    // required for your plugin
    &builder.Builder{},
  ))

}

Components are Go structs which implement the various lifecycle interfaces in the Derrick SDK. The following example shows a plugin which Derrick can use for the build lifecycle. Creating a build plugin is as simple as implementing the interface component.Builder on a struct as shown in the following example.

package builder

import (
  "context"
  "fmt"

  "github.com/nomatronio/derrick-plugin-sdk/terminal"
)

type Builder struct {}

func (b *Builder) BuildFunc() interface{} {
  // return a function which will be called by Derrick
  return func(ctx context.Context, ui terminal.UI) (*Binary, error) {
  u := ui.Status()
  defer u.Close()
  u.Update("Building application")

  return &Binary{}, nil
  }
}

To pass values from one Derrick component to another Derrick component you return structs which implement proto.Message, generally these structs are not manually created but generated by defining a Protocol Buffer message template and then using the protoc and associated Go plugin to generate the Go structs.

The following example shows the Protocol Buffer message template which is used to define the Binary struct which is returned from the previous example.

syntax = "proto3";

package platform;

option go_package = "github.com/hashicorp/derrick-plugin-examples/template/builder";

message Binary {
  string location = 1;
}

For more information on Protocol Buffers and Go, please see the documentation on the Google Developers website.

https://developers.google.com/protocol-buffers/docs/gotutorial

For full walkthrough for creating a Derrick Plugin and reference documentation, please see the Extending Derrick section of the Derrick website.

Example Plugins

Please see the following Plugins for examples of real world implementations of the Derrick SDK.

Build

Docker Build Packs

Registry

Amazon ECR Docker Files

Deploy

Nomad Nomad Jobspec Kubernetes kubectl Apply Helm Docker Azure Container Interface Google Cloud Run Amazon EC2 Amazon ECS

Release

Kubernetes Google Cloud Run Amazon ALB

Config Sourcers

Terraform Cloud Vault

Contributing

Thank you for your interest in contributing! Please refer to CONTRIBUTING.md for guidance.

Installing Dependencies

To automate installing the required Golang packages needed to build Derrick locally, run make tools.

Regenerating protobufs

Install dockern and run make docker/gen