diff options
Diffstat (limited to 'vendor/github.com/hashicorp/go-plugin/README.md')
-rw-r--r-- | vendor/github.com/hashicorp/go-plugin/README.md | 49 |
1 files changed, 28 insertions, 21 deletions
diff --git a/vendor/github.com/hashicorp/go-plugin/README.md b/vendor/github.com/hashicorp/go-plugin/README.md index 2058cfb..e4558db 100644 --- a/vendor/github.com/hashicorp/go-plugin/README.md +++ b/vendor/github.com/hashicorp/go-plugin/README.md | |||
@@ -1,10 +1,9 @@ | |||
1 | # Go Plugin System over RPC | 1 | # Go Plugin System over RPC |
2 | 2 | ||
3 | `go-plugin` is a Go (golang) plugin system over RPC. It is the plugin system | 3 | `go-plugin` is a Go (golang) plugin system over RPC. It is the plugin system |
4 | that has been in use by HashiCorp tooling for over 3 years. While initially | 4 | that has been in use by HashiCorp tooling for over 4 years. While initially |
5 | created for [Packer](https://www.packer.io), it has since been used by | 5 | created for [Packer](https://www.packer.io), it is additionally in use by |
6 | [Terraform](https://www.terraform.io) and [Otto](https://www.ottoproject.io), | 6 | [Terraform](https://www.terraform.io), [Nomad](https://www.nomadproject.io), and |
7 | with plans to also use it for [Nomad](https://www.nomadproject.io) and | ||
8 | [Vault](https://www.vaultproject.io). | 7 | [Vault](https://www.vaultproject.io). |
9 | 8 | ||
10 | While the plugin system is over RPC, it is currently only designed to work | 9 | While the plugin system is over RPC, it is currently only designed to work |
@@ -24,6 +23,11 @@ interface as if it were going to run in the same process. For a plugin user: | |||
24 | you just use and call functions on an interface as if it were in the same | 23 | you just use and call functions on an interface as if it were in the same |
25 | process. This plugin system handles the communication in between. | 24 | process. This plugin system handles the communication in between. |
26 | 25 | ||
26 | **Cross-language support.** Plugins can be written (and consumed) by | ||
27 | almost every major language. This library supports serving plugins via | ||
28 | [gRPC](http://www.grpc.io). gRPC-based plugins enable plugins to be written | ||
29 | in any language. | ||
30 | |||
27 | **Complex arguments and return values are supported.** This library | 31 | **Complex arguments and return values are supported.** This library |
28 | provides APIs for handling complex arguments and return values such | 32 | provides APIs for handling complex arguments and return values such |
29 | as interfaces, `io.Reader/Writer`, etc. We do this by giving you a library | 33 | as interfaces, `io.Reader/Writer`, etc. We do this by giving you a library |
@@ -37,7 +41,10 @@ and the plugin can call back into the host process. | |||
37 | **Built-in Logging.** Any plugins that use the `log` standard library | 41 | **Built-in Logging.** Any plugins that use the `log` standard library |
38 | will have log data automatically sent to the host process. The host | 42 | will have log data automatically sent to the host process. The host |
39 | process will mirror this output prefixed with the path to the plugin | 43 | process will mirror this output prefixed with the path to the plugin |
40 | binary. This makes debugging with plugins simple. | 44 | binary. This makes debugging with plugins simple. If the host system |
45 | uses [hclog](https://github.com/hashicorp/go-hclog) then the log data | ||
46 | will be structured. If the plugin also uses hclog, logs from the plugin | ||
47 | will be sent to the host hclog and be structured. | ||
41 | 48 | ||
42 | **Protocol Versioning.** A very basic "protocol version" is supported that | 49 | **Protocol Versioning.** A very basic "protocol version" is supported that |
43 | can be incremented to invalidate any previous plugins. This is useful when | 50 | can be incremented to invalidate any previous plugins. This is useful when |
@@ -62,13 +69,18 @@ This requires the host/plugin to know this is possible and daemonize | |||
62 | properly. `NewClient` takes a `ReattachConfig` to determine if and how to | 69 | properly. `NewClient` takes a `ReattachConfig` to determine if and how to |
63 | reattach. | 70 | reattach. |
64 | 71 | ||
72 | **Cryptographically Secure Plugins.** Plugins can be verified with an expected | ||
73 | checksum and RPC communications can be configured to use TLS. The host process | ||
74 | must be properly secured to protect this configuration. | ||
75 | |||
65 | ## Architecture | 76 | ## Architecture |
66 | 77 | ||
67 | The HashiCorp plugin system works by launching subprocesses and communicating | 78 | The HashiCorp plugin system works by launching subprocesses and communicating |
68 | over RPC (using standard `net/rpc`). A single connection is made between | 79 | over RPC (using standard `net/rpc` or [gRPC](http://www.grpc.io)). A single |
69 | any plugin and the host process, and we use a | 80 | connection is made between any plugin and the host process. For net/rpc-based |
70 | [connection multiplexing](https://github.com/hashicorp/yamux) | 81 | plugins, we use a [connection multiplexing](https://github.com/hashicorp/yamux) |
71 | library to multiplex any other connections on top. | 82 | library to multiplex any other connections on top. For gRPC-based plugins, |
83 | the HTTP2 protocol handles multiplexing. | ||
72 | 84 | ||
73 | This architecture has a number of benefits: | 85 | This architecture has a number of benefits: |
74 | 86 | ||
@@ -76,8 +88,8 @@ This architecture has a number of benefits: | |||
76 | panic the plugin user. | 88 | panic the plugin user. |
77 | 89 | ||
78 | * Plugins are very easy to write: just write a Go application and `go build`. | 90 | * Plugins are very easy to write: just write a Go application and `go build`. |
79 | Theoretically you could also use another language as long as it can | 91 | Or use any other language to write a gRPC server with a tiny amount of |
80 | communicate the Go `net/rpc` protocol but this hasn't yet been tried. | 92 | boilerplate to support go-plugin. |
81 | 93 | ||
82 | * Plugins are very easy to install: just put the binary in a location where | 94 | * Plugins are very easy to install: just put the binary in a location where |
83 | the host will find it (depends on the host but this library also provides | 95 | the host will find it (depends on the host but this library also provides |
@@ -85,8 +97,8 @@ This architecture has a number of benefits: | |||
85 | 97 | ||
86 | * Plugins can be relatively secure: The plugin only has access to the | 98 | * Plugins can be relatively secure: The plugin only has access to the |
87 | interfaces and args given to it, not to the entire memory space of the | 99 | interfaces and args given to it, not to the entire memory space of the |
88 | process. More security features are planned (see the coming soon section | 100 | process. Additionally, go-plugin can communicate with the plugin over |
89 | below). | 101 | TLS. |
90 | 102 | ||
91 | ## Usage | 103 | ## Usage |
92 | 104 | ||
@@ -97,10 +109,9 @@ high-level steps that must be done. Examples are available in the | |||
97 | 1. Choose the interface(s) you want to expose for plugins. | 109 | 1. Choose the interface(s) you want to expose for plugins. |
98 | 110 | ||
99 | 2. For each interface, implement an implementation of that interface | 111 | 2. For each interface, implement an implementation of that interface |
100 | that communicates over an `*rpc.Client` (from the standard `net/rpc` | 112 | that communicates over a `net/rpc` connection or other a |
101 | package) for every function call. Likewise, implement the RPC server | 113 | [gRPC](http://www.grpc.io) connection or both. You'll have to implement |
102 | struct this communicates to which is then communicating to a real, | 114 | both a client and server implementation. |
103 | concrete implementation. | ||
104 | 115 | ||
105 | 3. Create a `Plugin` implementation that knows how to create the RPC | 116 | 3. Create a `Plugin` implementation that knows how to create the RPC |
106 | client/server for a given plugin type. | 117 | client/server for a given plugin type. |
@@ -125,10 +136,6 @@ improvements we can make. | |||
125 | 136 | ||
126 | At this point in time, the roadmap for the plugin system is: | 137 | At this point in time, the roadmap for the plugin system is: |
127 | 138 | ||
128 | **Cryptographically Secure Plugins.** We'll implement signing plugins | ||
129 | and loading signed plugins in order to allow Vault to make use of multi-process | ||
130 | in a secure way. | ||
131 | |||
132 | **Semantic Versioning.** Plugins will be able to implement a semantic version. | 139 | **Semantic Versioning.** Plugins will be able to implement a semantic version. |
133 | This plugin system will give host processes a system for constraining | 140 | This plugin system will give host processes a system for constraining |
134 | versions. This is in addition to the protocol versioning already present | 141 | versions. This is in addition to the protocol versioning already present |