New Interested in participating in the HCP Waypoint Private Beta Program? Apply here
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0
      • Upgrade to 0.3.0
      • Upgrade to 0.4.0
      • Upgrade to 0.5.0
      • Upgrade to 0.6.0
      • Upgrade to 0.7.0
      • Upgrade to 0.8.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Tokens
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • ConfigSourcer
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap
Type '/' to Search

»Creating Waypoint Plugins

In this guide, you will learn how to create a simple plugin that can build Go applications; we will walkthrough all the steps needed to make a Waypoint plugin.

»Requirements

To follow this guide, you will need the following tools:

  • Go version 1.14+
  • Protocol Buffer Compiler
  • Protocol Buffer compile plugin for Go
  • Example Code

The plugin you are going create will implement the Builder component and will be able to compile Go applications from source and create a compiled binary. In addition to implementing Builder, you will see how to implement the optional Configurable and ConfigurableNotify interfaces, and how to define output values used in other phases of the life cycle.

»Setting Up the Project

To scaffold the new plugin, you can use the template in the example code repository. Open a terminal at this location; you will see the following structure.

├── Makefile
├── README.md
├── bin
│   └── waypoint-plugin-template
├── builder
│   ├── builder.go
│   ├── output.pb.go
│   └── output.proto
├── clone.sh
├── go.mod
├── go.sum
├── main.go
├── platform
│   ├── auth.go
│   ├── deploy.go
│   ├── destroy.go
│   ├── output.pb.go
│   └── output.proto
├── registry
│   ├── auth.go
│   ├── output.pb.go
│   ├── output.proto
│   └── registry.go
└── release
    ├── destroy.go
    ├── output.pb.go
    ├── output.proto
    └── release.go
├── Makefile
├── README.md
├── bin
│   └── waypoint-plugin-template
├── builder
│   ├── builder.go
│   ├── output.pb.go
│   └── output.proto
├── clone.sh
├── go.mod
├── go.sum
├── main.go
├── platform
│   ├── auth.go
│   ├── deploy.go
│   ├── destroy.go
│   ├── output.pb.go
│   └── output.proto
├── registry
│   ├── auth.go
│   ├── output.pb.go
│   ├── output.proto
│   └── registry.go
└── release
    ├── destroy.go
    ├── output.pb.go
    ├── output.proto
    └── release.go

The template implements all components and interfaces for Waypoint plugins; it creates a vanilla base from which you can build your plugins. Let's copy this template and create a new plugin. To do that, you can use the clone.sh script in the template folder.

clone.sh requires you to provide three parameters: the name of the new plugin, the destination and the Go module name; let's create a new plugin called gobuilder in the current repo.

./clone.sh gobuilder ../gobuilder github.com/hashicorp/waypoint-plugin-examples/gobuilder

Created new plugin in ../gobuilder
You can build this plugin by running the following command

cd ../gobuilder && make
./clone.sh gobuilder ../gobuilder github.com/hashicorp/waypoint-plugin-examples/gobuilder

Created new plugin in ../gobuilder
You can build this plugin by running the following command

cd ../gobuilder && make

The clone script creates the new plugin at the requested path ../gobuilder, let's change to this path to build the plugin.

cd ../gobuilder
cd ../gobuilder

The gobuilder folder is an exact copy of the template, but all the Go module paths have changed to the package name you provided to the command. Before starting to modify the plugin, let's check you can build it. When you run the make command, all the Protocol Buffers used to exchange values between plugin components, and the main plugin binary are compiled.

Build Protos
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./builder/output.proto
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./registry/output.proto
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./platform/output.proto
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./release/output.proto

Compile Plugin
go build -o ./bin/waypoint-plugin-template ./main.go
Build Protos
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./builder/output.proto
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./registry/output.proto
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./platform/output.proto
protoc -I . --go_opt=plugins=grpc --go_out=../../../../ ./release/output.proto

Compile Plugin
go build -o ./bin/waypoint-plugin-template ./main.go

If you received an error when trying to build your plugin, double-check that you have all the required pre-requisites installed.

Next - Registering Plugin Components

github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

Build, deploy, and release applications to a Kubernetes cluster.

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal