sdk

README

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

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

Regenerating protobufs

Install dockern and run make docker/gen

Documentation

Index

• func Debug(ctx context.Context, pluginAddr string, opts ...Option) error
• func Main(opts ...Option)
• type Option
  • func WithComponents(cs ...interface{}) Option
  • func WithMappers(ms ...interface{}) Option
• type ReattachConfig
  • func DebugServe(ctx context.Context, opts ...Option) (ReattachConfig, <-chan struct{}, error)
• type ReattachConfigAddr

Functions

func Debug

func Debug(ctx context.Context, pluginAddr string, opts ...Option) error

Debug starts a debug server and controls its lifecycle, printing the information needed for Waypoint to connect to the plugin to stdout. os.Interrupt will be captured and used to stop the server.

func Main

func Main(opts ...Option)

Main is the primary entrypoint for plugins serving components. This function never returns; it blocks until the program is exited. This should be called immediately in main() in your plugin binaries, no prior setup should be done.

Types

type Option

type Option func(*config)

Option modifies config. Zero or more can be passed to Main.

func WithComponents

func WithComponents(cs ...interface{}) Option

WithComponents specifies a list of components to serve from the plugin binary. This will append to the list of components to serve. You can currently only serve at most one of each type of plugin.

func WithMappers

func WithMappers(ms ...interface{}) Option

WithMappers specifies a list of mappers to apply to the plugin.

Mappers are functions that take zero or more arguments and return one result (optionally with an error). These can be used to convert argument types as needed for your plugin functions. For example, you can convert a proto type to a richer Go struct.

Mappers must take zero or more arguments and return exactly one or two values where the second return type must be an error. Example:

func() *Value
func() (*Value, error)
-- the above with any arguments

This will append the mappers to the list of available mappers. A set of default mappers is always included to convert from SDK proto types to richer Go structs.

type ReattachConfig

type ReattachConfig struct {
	Protocol        string
	ProtocolVersion int
	Pid             int
	Test            bool
	Addr            ReattachConfigAddr
}

ReattachConfig holds the information Waypoint needs to be able to attach itself to a plugin process, so it can drive the process.

func DebugServe

func DebugServe(ctx context.Context, opts ...Option) (ReattachConfig, <-chan struct{}, error)

DebugServe starts a plugin server in debug mode; this should only be used when the plugin will manage its own lifecycle. It is not recommended for normal usage; Serve is the correct function for that.

type ReattachConfigAddr

type ReattachConfigAddr struct {
	Network string
	String  string
}

ReattachConfigAddr is a JSON-encoding friendly version of net.Addr.