Waypoint Plugin SDK

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

Plugins in Waypoint are separate binaries which communicate with the Waypoint 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 Waypoint 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 Waypoint during the various parts of the lifecycle.

package main

import (
  sdk "github.com/hashicorp/waypoint-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 Waypoint SDK. The following example shows a plugin which Waypoint 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/hashicorp/waypoint-plugin-sdk/terminal"
)

type Builder struct {}

func (b *Builder) BuildFunc() interface{} {
	// return a function which will be called by Waypoint
	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 Waypoint component to another Waypoint 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/waypoint-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 Waypoint Plugin and reference documentation, please see the Extending Waypoint section of the Waypoint website.

Example Plugins

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

Build

Docker
Build Packs

Registry

Docker
Files

Deploy

Nomad
Kubernetes
Docker
Azure Container Interface
Google Cloud Run
Netlify
Amazon EC2

Release

Kubernetes
Google Cloud Run
Amazon ALB

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 Waypoint locally, run make tools.