From 18790a2b82fa3e7cdc04f1d73f566656f7b93b49 Mon Sep 17 00:00:00 2001 From: Luiz Aoqui Date: Wed, 12 Feb 2020 21:07:05 -0500 Subject: [PATCH] improve documentation --- .gitignore | 1 + GNUmakefile | 11 ++++ README.md | 89 ++++++++++++++++++-------- config/client.hcl => example/agent.hcl | 2 +- {config => example}/example.nomad | 0 go.mod | 1 + main.go | 2 + 7 files changed, 78 insertions(+), 28 deletions(-) create mode 100644 GNUmakefile rename config/client.hcl => example/agent.hcl (58%) rename {config => example}/example.nomad (100%) diff --git a/.gitignore b/.gitignore index 9c066b0..dd66f8f 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ nomad-skeleton-driver-plugin +hello-driver diff --git a/GNUmakefile b/GNUmakefile new file mode 100644 index 0000000..6d84e6b --- /dev/null +++ b/GNUmakefile @@ -0,0 +1,11 @@ +PLUGIN_BINARY=hello-driver +export GO111MODULE=on + +default: build + +.PHONY: clean +clean: ## Remove build artifacts + rm -rf ${PLUGIN_BINARY} + +build: + go build -o ${PLUGIN_BINARY} . diff --git a/README.md b/README.md index 7174829..5b87aaa 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,84 @@ -nomad-skeleton-driver-plugin +Nomad Skeleton Driver Plugin ========== -This project is a [Hashicorp Nomad](https://www.nomadproject.io/) [task driver -plugin](https://www.nomadproject.io/docs/drivers/index.html) skeleton -implementation. You can clone and modify this to get started writing your own -task driver plugin. +Skeleton project for +[Nomad task driver plugins](https://www.nomadproject.io/docs/drivers/index.html). + +This project is intended for bootstrapping development of a new task driver +plugin. + +- Website: [https://www.nomadproject.io](https://www.nomadproject.io) +- Mailing list: [Google Groups](http://groups.google.com/group/nomad-tool) Requirements ------------------- -- [Nomad](https://www.nomadproject.io/downloads.html) v0.9.5+ -- [Go](https://golang.org/doc/install) v1.12.x (to build the plugin) +- [Nomad](https://www.nomadproject.io/downloads.html) v0.9+ +- [Go](https://golang.org/doc/install) v1.11 or later (to build the plugin) -Get Started +Building the Skeleton Plugin ------------------- -Download the project module: +[Generate](https://github.com/hashicorp/nomad-skeleton-driver-plugin/generate) +a new repository in your account from this template by clicking the `Use this +template` button above. + +Clone the repository somewhere in your computer. This project uses +[Go modules](https://blog.golang.org/using-go-modules) so you will need to set +the environment variable `GO111MODULE=on` or work outside your `GOPATH` if it +is set to `auto` or not declared. ```sh -go get github.com/hashicorp/nomad-skeleton-driver-plugin +$ git clone git@github.com:/git ``` -Follow the comments marked with a `TODO` tag to implement your driver's logic. -For more information consult the Nomad documentation on -[plugins](https://www.nomadproject.io/docs/internals/plugins/index.html). +Enter the plugin directory and update the paths in `go.mod` and `main.go` to +match your repository path. -The initial state of the skeleton is a simple task that outputs a greeting. You -can try it out by starting a Nomad server and client and running the job -provided in the `config` folder: +```diff +// go.mod + +- module github.com/hashicorp/nomad-skeleton-driver-plugin ++ module github.com// +... +``` + +```diff +// main.go + +package main + +import ( + log "github.com/hashicorp/go-hclog" +- "github.com/hashicorp/nomad-skeleton-driver-plugin/hello" ++ "github.com///hello" +... + +``` + +Build the skeleton plugin. ```sh -go build -nomad agent -dev -config=./config/client.hcl -plugin-dir=$(PWD) +$ make build +``` + +## Deploying Driver Plugins in Nomad + +The initial version of the skeleton is a simple task that outputs a greeting. +You can try it out by starting a Nomad agent and running the job provided in +the `example` folder: + +```sh +$ make build +$ nomad agent -dev -config=./example/agent.hcl -plugin-dir=$(pwd) # in another shell -nomad run ./config/example.nomad +$ nomad run ./example/example.nomad +$ nomad logs ``` -You should rename the project's root folder and the `hello` module to fit your -own driver. - Code Organization ------------------- -The skeleton driver comes with an in memory task state store (see -`hello/state.go`). This in-memory map is for storing runtime details (like a -process id). The details of what to store is left to the implementation of the -task driver. Fields stored in the base implementation in this skeleton can be -found in the `taskHandle` struct. +Follow the comments marked with a `TODO` tag to implement your driver's logic. +For more information check the +[Nomad documentation on plugins](https://www.nomadproject.io/docs/internals/plugins/index.html). diff --git a/config/client.hcl b/example/agent.hcl similarity index 58% rename from config/client.hcl rename to example/agent.hcl index 47b0b2d..c9dd670 100644 --- a/config/client.hcl +++ b/example/agent.hcl @@ -1,6 +1,6 @@ log_level = "TRACE" -plugin "nomad-skeleton-driver-plugin" { +plugin "hello-driver" { config { shell = "bash" } diff --git a/config/example.nomad b/example/example.nomad similarity index 100% rename from config/example.nomad rename to example/example.nomad diff --git a/go.mod b/go.mod index 7d864f8..c0cbd07 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,4 @@ +// TODO: update the module path below to match your own repository module github.com/hashicorp/nomad-skeleton-driver-plugin go 1.12 diff --git a/main.go b/main.go index d8b7641..bf721a6 100644 --- a/main.go +++ b/main.go @@ -2,6 +2,8 @@ package main import ( log "github.com/hashicorp/go-hclog" + + // TODO: update the path below to match your own repository "github.com/hashicorp/nomad-skeleton-driver-plugin/hello" "github.com/hashicorp/nomad/plugins"