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

Commit 7b7ded8

Browse files
author
David Chung
authored
Docs update (#566)
Signed-off-by: David Chung <david.chung@docker.com>
1 parent 0ccd281 commit 7b7ded8

3 files changed

Lines changed: 78 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 71 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,34 +5,82 @@ InfraKit
55
[![Go Report Card](https://goreportcard.com/badge/github.com/docker/infrakit)](https://goreportcard.com/report/github.com/docker/infrakit)
66
[![codecov.io](https://codecov.io/github/docker/infrakit/coverage.svg?branch=master&token=z08ZKeIJfA)](https://codecov.io/github/docker/infrakit?branch=master)
77

8-
_InfraKit_ is a toolkit for creating and managing declarative, self-healing infrastructure.
9-
It breaks infrastructure automation down into simple, pluggable components.
8+
_InfraKit_ is a toolkit for infrastructure orchestration.
9+
With an emphasis on immutable infrastructure, it breaks down infrastructure automation and management processes into small, pluggable components.
1010
These components work together to actively ensure the infrastructure state matches the user's specifications.
11+
InfraKit therefore provides infrastructure support for higher-level container orchestration systems and can make your infrastructure self-managing and self-healing.
1112

1213
To get started, try the [tutorial](docs/tutorial.md), or check out the video below:
1314

1415
### InfraKit + [LinuxKit](https://github.com/linuxkit/linuxkit) POC
1516

1617
[![infrakit+linuxkit](./docs/images/infrakit_linuxkit_screencap.png)](https://www.youtube.com/watch?v=j50ovfRWpZM "InfraKit + LinuxKit")
1718

18-
In this video, InfraKit is used to build a custom linux operating system (based on [linuxkit](https://github.com/linuxkit/linuxkit))
19-
and deploy a cluster of virtual machine instances from a local Mac laptop to a bare-metal ARM server running on [Packet.net](https://packet.net).
20-
It demonstrates some of the key concepts and components in InfraKit and shows how InfraKit can be used to implement an integrated
21-
workflow from custom OS image creation to cluster deployment and Day N management.
19+
In this video, InfraKit was used to build a custom linux operating system (based on [linuxkit](https://github.com/linuxkit/linuxkit)).
20+
We then deployed a cluster of virtual machine instances on a local Mac laptop using the Mac Xhyve hypervisor (HyperKit). A cluster
21+
of 3 servers booted up in seconds. Later, after the custom OS image has been updated with a new public key, InfraKit detects the
22+
change and orchestrates a rolling update of the nodes.
23+
We then deploy the same OS image to a bare-metal ARM server running on [Packet.net](https://packet.net), where the server uses
24+
custom ipxe boot directly from the localhost. It demonstrates some of the key concepts and components in InfraKit and shows how
25+
InfraKit can be used to implement an integrated workflow from custom OS image creation to cluster deployment and Day N management.
26+
The entire demo is published as a [playbook](docs/playbooks/README.md), and you can create your own playbooks too.
2227

23-
### Who InfraKit is for
28+
### Use Cases
29+
30+
_InfraKit_ is designed to automate setup and management of infrastructure in support of distributed systems and higher-level
31+
container orchestration systems. Some of the use cases we are working on include:
32+
33+
+ Bootstrap / installation of container orchestration systems like Docker Swarm and Kubernetes
34+
+ Cluster autoscaler that can work across a variety of platforms from public clouds (like AWS autoscaling groups) to
35+
bare-metal hosts.
36+
+ GPU cluster provisioning
37+
+ Integration with LinuxKit for building and deploying immutable infrastructure from declarative specifications of the entire stack:
38+
from infrastructure resources to os / kernel and applications.
39+
+ Day-N management and automation of infrastructure - from provisioning to rolling updates and capacity scaling.
40+
41+
InfraKit has a modular architecture with a set of interfaces which define the interactions of these 'plugin objects'.
42+
Plugins are active daemons that cooperate with one another to ensure the infrastructure state matches your specifications.
2443

25-
_InfraKit_ is designed to support setup and management of base infrastructure. For example, it can help you manage a
26-
system like a cluster or container orchestrator, ideally relieving you of building custom release and maintenance tools.
27-
As a result, it is a low-level tool intended to be used by infrastructure operators directly or indirectly
28-
(as a toolkit) through a higher-level tool. Since _InfraKit_ is pluggable, it allows you to manage resources in diverse
29-
environments while using shared components and consistent interfaces.
3044

3145
## Plugins
3246
_InfraKit_ makes extensive use of _Plugins_ to manage arbitrary systems in diverse environments, which can be composed
33-
to meet different needs.
47+
to meet different needs. See the [plugins](docs/plugins) documentation for more technical details.
48+
49+
Here is a list of plugins:
50+
51+
### Core Implementations
52+
53+
| plugin | type | description |
54+
|:--------------------------------------------------------|:---------|:----------------------------------------|
55+
| [infrakit/group](./cmd/group) | group | core group controller for rolling updates, scale group, etc. |
56+
| [swarm](./examples/flavor/swarm) | flavor | runs Docker in Swarm mode |
57+
| [kubernetes](./examples/flavor/kubernetes) | flavor | bootstraps a single master kubernetes cluster |
58+
| [vanilla](./examples/flavor/vanilla) | flavor | manual specification of instance fields |
59+
| [zookeeper](./examples/flavor/zookeeper) | flavor | run an Apache ZooKeeper ensemble |
60+
| [infrakit/file](./examples/instance/file) | instance | useful for development and testing |
61+
| [infrakit/docker](./examples/instance/docker) | instance | provisions container via Docker |
62+
| [infrakit/terraform](./examples/instance/terraform) | instance | creates resources using Terraform |
63+
| [infrakit/maas](./examples/instance/maas) | instance | bare-metal provisioning using Ubuntu MAAS |
64+
| [infrakit/vagrant](./examples/instance/vagrant) | instance | creates Vagrant VMs |
65+
| [infrakit/hyperkit](./examples/instance/hyperkit) | instance | creates Xhyve VMs on Mac OSX |
66+
| [infrakit/packet](./examples/instance/packet) | instance | provisions bare metal hosts on Packet |
67+
| [infrakit/libvirt](./examples/instance/libvirt) | instance | provisions KVM vms via libvirt |
68+
| [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances and other resource types |
69+
| [docker/infrakit.gcp](https://github.com/docker/infrakit.gcp) | instance | creates Google Cloud Platform compute instances |
70+
| [docker/infrakit.digitalocean](https://github.com/docker/infrakit.digitalocean) | instance | creates DigitalOcean droplets |
71+
72+
### Community Implementations
73+
74+
| plugin | type | description |
75+
|:--------------------------------------------------------|:---------|:----------------------------------------|
76+
| [HewlettPackard/infrakit-instance-oneview](https://github.com/HewlettPackard/infrakit-instance-oneview) | instance | bare-metal server provisioning via HP-OneView |
77+
| [codedellemc/infrakit.rackhd](https://github.com/codedellemc/infrakit.rackhd) | instance | bare-metal server provisioning via RackHD |
78+
| [IBM Bluemix / SoftLayer](./examples/instance/terraform) | instance | SoftLayer via terraform |
79+
| [AliyunContainerService/infrakit.aliyun](https://github.com/AliyunContainerService/infrakit.aliyun) | instance | Provisions instances on Alibaba Cloud |
80+
| [1and1/infrakit-instance-oneandone](https://github.com/1and1/infrakit-instance-oneandone) | instance | Provisions instances on 1&1 Cloud Server |
81+
3482

35-
See the [plugins](docs/plugins) documentation for more details.
83+
Have a Plugin you'd like to share? Submit a Pull Request to add yourself to the list!
3684

3785

3886
## Building
@@ -82,8 +130,16 @@ This will produce binaries for tools and several reference Plugin implementation
82130
an Instance plugin integrating [Terraform](https://www.terraform.io)
83131
+ [`infrakit-instance-vagrant`](examples/instance/vagrant):
84132
an Instance plugin using [Vagrant](https://www.vagrantup.com/)
133+
+ [`infrakit-instance-docker`](examples/instance/docker):
134+
an Instance plugin for provisioning Docker containers via the Docker API
85135
+ [`infrakit-instance-maas`](examples/instance/maas):
86-
an Instance plugin using [MaaS](https://maas.io)
136+
an Instance plugin using [MaaS](https://maas.io) to provision bare metal servers
137+
+ [`infrakit-instance-hyperkit`](pkg/plugin/instance/hyperkit):
138+
an Instance plugin using [HyperKit](https://github.com/docker/hyperkit) to provision Xhyve-based guest vm's on Mac OSX
139+
+ [`infrakit-instance-libvirt`](pkg/plugin/instance/libvirt):
140+
an Instance plugin using libvirt to provision KVM / QEMU vm instances
141+
+ [`infrakit-instance-packet`](pkg/plugin/instance/packet):
142+
an Instance plugin for provisioning bare-metal servers from [Packet.net](https://packet.net)
87143
+ [`infrakit-flavor-vanilla`](examples/flavor/vanilla):
88144
a Flavor plugin for plain vanilla set up with user data and labels
89145
+ [`infrakit-flavor-zookeeper`](examples/flavor/zookeeper):

‎docs/plugins/README.md‎

Lines changed: 6 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,11 @@ API, listening on a unix socket.
88
Multiple _InfraKit_ plugins are typically used together to support a declared configuration. These plugins discover
99
each other by looking for socket files in a common plugin directory, and communicate via HTTP.
1010

11-
The default plugin directory is `~/.infrakit/plugins`, and can be overridden with the environment variable
12-
`INFRAKIT_PLUGINS_DIR`.
11+
InfraKit stores a number of files (for configurations, plugin socket files, etc.) in a directory tree. Typically
12+
the environment variable `INFRAKIT_HOME` designates where the directory is. It is typically `~/.infrakit`.
13+
For plugin discovery, the default directory is `~/.infrakit/plugins`, and can be overridden with the environment variable
14+
`INFRAKIT_PLUGINS_DIR`. This is the directory where the unix sockets are found. The name of a socket file corresponds
15+
to the name the plugin is referenced throughout the system. For example, a
1316

1417
Note that multiple instances of a plugin may run, provided they have different names for discovery. This may be useful,
1518
for example, if a plugin can be configured to behave differently. For example:
@@ -69,42 +72,10 @@ Flavors allow a group of instances to have different characteristics. In a grou
6972
all members are treated identically and individual members do not have strong identity. In a group of pets,
7073
however, the members may require special handling and demand stronger notions of identity and state.
7174

72-
73-
### Reference implementations
74-
This repository contains several Plugins which should be considered reference implementations for demonstration purposes
75-
and development aides. With the exception of those listed as
76-
[supported](#supported-implementations), Plugins in this repository should be considered **not** to be under active
77-
development and for use at your own risk.
78-
79-
Over time, we would prefer to phase out reference Plugins that appear to provide real value for implementations that
80-
are developed independently. For this reason, please [file an issue](https://github.com/docker/infrakit/issues/new)
81-
to start a discussion before contributing to these plugins with non-trivial code.
82-
83-
| plugin | type | description |
84-
|:--------------------------------------------------------|:---------|:----------------------------------------|
85-
| [swarm](../../examples/flavor/swarm) | flavor | runs Docker in Swarm mode |
86-
| [vanilla](../../examples/flavor/vanilla) | flavor | manual specification of instance fields |
87-
| [zookeeper](../../examples/flavor/zookeeper) | flavor | run an Apache ZooKeeper ensemble |
88-
| [infrakit/file](../../examples/instance/file) | instance | useful for development and testing |
89-
| [infrakit/terraform](../../examples/instance/terraform) | instance | creates instances using Terraform |
90-
| [infrakit/vagrant](../../examples/instance/vagrant) | instance | creates Vagrant VMs |
91-
92-
93-
### Supported implementations
94-
The following Plugins are supported for active development. Note that these Plugins may not be part of the InfraKit
95-
project, so please double-check where the code lives before filing InfraKit issues.
96-
97-
| plugin | type | description |
98-
|:--------------------------------------------------------------------|:---------|:------------------------------------------------------|
99-
| [infrakit/group](../../cmd/group) | group | supports Instance and Flavor plugins, rolling updates |
100-
| [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances |
101-
102-
Have a Plugin you'd like to share? Submit a Pull Request to add yourself to the list!
103-
10475
### Creating a plugin
10576
A plugin must be an HTTP server that implements one of the plugin [APIs](#apis), listening on a Unix socket. While
10677
a plugin can be written in any programming language, [utilities](../../pkg/rpc) are available as libraries to simplify Plugin
107-
development in Go. Our [reference implementations](#reference-implementations) should provide a good starting point
78+
development in Go. Our [reference implementations](../../examples/instance) should provide a good starting point
10879
for building a new plugin using these utilities.
10980

11081
#### APIs

‎docs/tutorial.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@ To illustrate the concept of working with Group, Flavor, and Instance plugins, w
55
+ The `file` instance plugin - to provision instances by writing files to disk
66
+ The `vanilla` flavor plugin - to provide context/ flavor to the configuration of the instances
77

8-
It may be helpful to familiarize yourself with [plugin discovery](../README.md#plugin-discovery) if you have not already
9-
done so.
8+
For more information on plugins and how they work, please see the [docs](./plugins/README.md).
109

1110
## Building the binaries
1211

0 commit comments

Comments
 (0)