Skip to content
This repository was archived by the owner on Jan 21, 2020. It is now read-only.

Commit 1519d12

Browse files
wfarnerwfarner
authored
Docs: extract a page dedicated to plugins (#303)
Signed-off-by: Bill Farner <[email protected]>
1 parent 18de651 commit 1519d12

File tree

2 files changed

+107
-102
lines changed

2 files changed

+107
-102
lines changed

‎README.md‎

Lines changed: 3 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -22,99 +22,13 @@ As a result, it is a low-level tool intended to be used by infrastructure operat
2222
environments while using shared components and consistent interfaces.
2323

2424
## Plugins
25-
_InfraKit_ leverages _Plugins_ to manage arbitrary systems in diverse environments, which can be composed to meet
26-
different needs. Technically, a Plugin is an HTTP server with a well-defined API, listening on a unix socket.
25+
_InfraKit_ makes extensive use of _Plugins_ to manage arbitrary systems in diverse environments, which can be composed
26+
to meet different needs.
2727

28-
[Utilities](pkg/rpc) are provided as libraries to simplify Plugin development in Go.
29-
30-
### Plugin types
31-
#### Group
32-
When managing infrastructure like computing clusters, Groups make good abstraction, and working with groups is easier
33-
than managing individual instances. For example, a group can be made up of a collection
34-
of machines as individual instances. The machines in a group can have identical configurations (replicas, or cattle).
35-
They can also have slightly different properties like identity and ordering (as members of a quorum or pets).
36-
37-
_InfraKit_ provides primitives to manage Groups: a group has a given size and can shrink or grow based on some
38-
specification, whether it's human generated or machine computed.
39-
Group members can also be updated in a rolling fashion so that the configuration of the instance members reflect a new
40-
desired state. Operators can focus on Groups while _InfraKit_ handles the necessary coordination of Instances.
41-
42-
Since _InfraKit_ emphasizes on declarative infrastructure, there are no operations to move machines or Groups from one
43-
state to another. Instead, you _declare_ your desired state of the infrastructure. _InfraKit_ is responsible
44-
for converging towards, and maintaining, that desired state.
45-
46-
Therefore, a [group plugin](pkg/spi/group/spi.go) manages Groups of Instances and exposes the operations that are of
47-
interest to a user:
48-
49-
+ commit a group configuration, to start managing a group
50-
+ inspect a group
51-
+ destroy a group
52-
53-
##### Default Group plugin
54-
_InfraKit_ provides a default Group plugin implementation, intended to suit common use cases. The default Group plugin
55-
manages Instances of a specific Flavor. Instance and Flavor plugins can be composed to manage different types of
56-
services on different infrastructure providers.
57-
58-
While it's generally simplest to use the default Group plugin, custom implementations may be valuable to adapt another
59-
infrastructure management system. This would allow you to use _InfraKit_ tooling to perform basic operations on widely
60-
different infrastructure using the same interface.
61-
62-
#### Instance
63-
Instances are members of a group. An [instance plugin](pkg/spi/instance/spi.go) manages some physical resource instances.
64-
It knows only about individual instances and nothing about Groups. Instance is technically defined by the plugin, and
65-
need not be a physical machine at all.
66-
67-
For compute, for example, instances can be VM instances of identical spec. Instances
68-
support the notions of attachment to auxiliary resources. Instances may be tagged, and tags are assumed to be
69-
persistent which allows the state of the cluster to be inferred and computed.
70-
71-
In some cases, instances can be identical, while in other cases the members of a group require stronger identities and
72-
persistent, stable state. These properties are captured via the _flavors_ of the instances.
73-
74-
#### Flavor
75-
Flavors help distinguish members of one group from another by describing how these members should be treated.
76-
A [flavor plugin](pkg/spi/flavor/spi.go) can be thought of as defining what runs on an Instance.
77-
It is responsible for dictating commands to run services, and check the health of those services.
78-
79-
Flavors allow a group of instances to have different characteristics. In a group of cattle,
80-
all members are treated identically and individual members do not have strong identity. In a group of pets,
81-
however, the members may require special handling and demand stronger notions of identity and state.
82-
83-
84-
#### Reference implementations
85-
This repository contains several Plugins which should be considered reference implementations for demonstration purposes
86-
and development aides. With the exception of those listed as
87-
[supported](#supported-implementations), Plugins in this repository should be considered **not** to be under active
88-
development and for use at your own risk.
89-
90-
Over time, we would prefer to phase out reference Plugins that appear to provide real value for implementations that
91-
are developed independently. For this reason, please [file an issue](https://github.com/docker/infrakit/issues/new)
92-
to start a discussion before contributing to these plugins with non-trivial code.
93-
94-
| plugin | type | description |
95-
|:---------------------------------------------------|:---------|:----------------------------------------|
96-
| [swarm](pkg/example/flavor/swarm) | flavor | runs Docker in Swarm mode |
97-
| [vanilla](pkg/example/flavor/vanilla) | flavor | manual specification of instance fields |
98-
| [zookeeper](pkg/example/flavor/zookeeper) | flavor | run an Apache ZooKeeper ensemble |
99-
| [infrakit/file](pkg/example/instance/file) | instance | useful for development and testing |
100-
| [infrakit/terraform](pkg/example/instance/terraform) | instance | creates instances using Terraform |
101-
| [infrakit/vagrant](pkg/example/instance/vagrant) | instance | creates Vagrant VMs |
102-
103-
104-
#### Supported implementations
105-
The following Plugins are supported for active development. Note that these Plugins may not be part of the InfraKit
106-
project, so please double-check where the code lives before filing InfraKit issues.
107-
108-
| plugin | type | description |
109-
|:--------------------------------------------------------------|:---------|:------------------------------------------------------|
110-
| [infrakit/group](cmd/group) | group | supports Instance and Flavor plugins, rolling updates |
111-
| [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances |
112-
113-
Have a Plugin you'd like to share? Submit a Pull Request to add yourself to the list!
28+
See the [plugins](docs/plugins.md) documentation for more details.
11429

11530

11631
## Building
117-
11832
### Your Environment
11933

12034
Make sure you check out the project following a convention for building Go projects. For example,
@@ -280,19 +194,6 @@ Updating the group tells the Group plugin that your configuration may have chang
280194
then determine the changes necessary to ensure the state of the infrastructure matches the new
281195
specification.
282196

283-
## Plugin Discovery
284-
285-
Multiple _InfraKit_ plugins are typically used together to support a declared configuration. These plugins discover
286-
each other by looking for socket files in a common plugin directory, and communicate via HTTP.
287-
288-
The default plugin directory is `~/.infrakit/plugins`, and can be overridden with the environment variable
289-
`INFRAKIT_PLUGINS_DIR`.
290-
291-
Note that multiple instances of a plugin may run, provided they have different names for discovery. This may be useful,
292-
for example, if a plugin can be configured to behave differently. For example:
293-
294-
The CLI shows which plugins are [discoverable](cmd/cli/README.md#list-plugins).
295-
296197
## Docs
297198

298199
Additional documentation can be found [here](docs).

‎docs/plugins.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Plugins
2+
3+
Much of the behavior in _InfraKit_ is defined by Plugins. Technically, a Plugin is an HTTP server with a well-defined
4+
API, listening on a unix socket.
5+
6+
[Utilities](pkg/rpc) are available as libraries to simplify Plugin development in Go.
7+
8+
## Plugin Discovery
9+
10+
Multiple _InfraKit_ plugins are typically used together to support a declared configuration. These plugins discover
11+
each other by looking for socket files in a common plugin directory, and communicate via HTTP.
12+
13+
The default plugin directory is `~/.infrakit/plugins`, and can be overridden with the environment variable
14+
`INFRAKIT_PLUGINS_DIR`.
15+
16+
Note that multiple instances of a plugin may run, provided they have different names for discovery. This may be useful,
17+
for example, if a plugin can be configured to behave differently. For example:
18+
19+
The CLI shows which plugins are [discoverable](cmd/cli/README.md#list-plugins).
20+
21+
## Plugin types
22+
### Group
23+
When managing infrastructure like computing clusters, Groups make good abstraction, and working with groups is easier
24+
than managing individual instances. For example, a group can be made up of a collection
25+
of machines as individual instances. The machines in a group can have identical configurations (replicas, or cattle).
26+
They can also have slightly different properties like identity and ordering (as members of a quorum or pets).
27+
28+
_InfraKit_ provides primitives to manage Groups: a group has a given size and can shrink or grow based on some
29+
specification, whether it's human generated or machine computed.
30+
Group members can also be updated in a rolling fashion so that the configuration of the instance members reflect a new
31+
desired state. Operators can focus on Groups while _InfraKit_ handles the necessary coordination of Instances.
32+
33+
Since _InfraKit_ emphasizes on declarative infrastructure, there are no operations to move machines or Groups from one
34+
state to another. Instead, you _declare_ your desired state of the infrastructure. _InfraKit_ is responsible
35+
for converging towards, and maintaining, that desired state.
36+
37+
Therefore, a [group plugin](pkg/spi/group/spi.go) manages Groups of Instances and exposes the operations that are of
38+
interest to a user:
39+
40+
+ commit a group configuration, to start managing a group
41+
+ inspect a group
42+
+ destroy a group
43+
44+
#### Default Group plugin
45+
_InfraKit_ provides a default Group plugin implementation, intended to suit common use cases. The default Group plugin
46+
manages Instances of a specific Flavor. Instance and Flavor plugins can be composed to manage different types of
47+
services on different infrastructure providers.
48+
49+
While it's generally simplest to use the default Group plugin, custom implementations may be valuable to adapt another
50+
infrastructure management system. This would allow you to use _InfraKit_ tooling to perform basic operations on widely
51+
different infrastructure using the same interface.
52+
53+
### Instance
54+
Instances are members of a group. An [instance plugin](pkg/spi/instance/spi.go) manages some physical resource instances.
55+
It knows only about individual instances and nothing about Groups. Instance is technically defined by the plugin, and
56+
need not be a physical machine at all.
57+
58+
For compute, for example, instances can be VM instances of identical spec. Instances
59+
support the notions of attachment to auxiliary resources. Instances may be tagged, and tags are assumed to be
60+
persistent which allows the state of the cluster to be inferred and computed.
61+
62+
In some cases, instances can be identical, while in other cases the members of a group require stronger identities and
63+
persistent, stable state. These properties are captured via the _flavors_ of the instances.
64+
65+
### Flavor
66+
Flavors help distinguish members of one group from another by describing how these members should be treated.
67+
A [flavor plugin](pkg/spi/flavor/spi.go) can be thought of as defining what runs on an Instance.
68+
It is responsible for dictating commands to run services, and check the health of those services.
69+
70+
Flavors allow a group of instances to have different characteristics. In a group of cattle,
71+
all members are treated identically and individual members do not have strong identity. In a group of pets,
72+
however, the members may require special handling and demand stronger notions of identity and state.
73+
74+
75+
### Reference implementations
76+
This repository contains several Plugins which should be considered reference implementations for demonstration purposes
77+
and development aides. With the exception of those listed as
78+
[supported](#supported-implementations), Plugins in this repository should be considered **not** to be under active
79+
development and for use at your own risk.
80+
81+
Over time, we would prefer to phase out reference Plugins that appear to provide real value for implementations that
82+
are developed independently. For this reason, please [file an issue](https://github.com/docker/infrakit/issues/new)
83+
to start a discussion before contributing to these plugins with non-trivial code.
84+
85+
| plugin | type | description |
86+
|:---------------------------------------------------|:---------|:----------------------------------------|
87+
| [swarm](pkg/example/flavor/swarm) | flavor | runs Docker in Swarm mode |
88+
| [vanilla](pkg/example/flavor/vanilla) | flavor | manual specification of instance fields |
89+
| [zookeeper](pkg/example/flavor/zookeeper) | flavor | run an Apache ZooKeeper ensemble |
90+
| [infrakit/file](pkg/example/instance/file) | instance | useful for development and testing |
91+
| [infrakit/terraform](pkg/example/instance/terraform) | instance | creates instances using Terraform |
92+
| [infrakit/vagrant](pkg/example/instance/vagrant) | instance | creates Vagrant VMs |
93+
94+
95+
### Supported implementations
96+
The following Plugins are supported for active development. Note that these Plugins may not be part of the InfraKit
97+
project, so please double-check where the code lives before filing InfraKit issues.
98+
99+
| plugin | type | description |
100+
|:--------------------------------------------------------------|:---------|:------------------------------------------------------|
101+
| [infrakit/group](cmd/group) | group | supports Instance and Flavor plugins, rolling updates |
102+
| [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances |
103+
104+
Have a Plugin you'd like to share? Submit a Pull Request to add yourself to the list!

0 commit comments

Comments
 (0)