Update readme

This moves the scope table out into a separate doc and adds a few
examples to the readme to show the feature set of containerd.

Signed-off-by: Michael Crosby <crosbymichael@gmail.com>

README.md

@@ -4,24 +4,143 @@
 [![Build Status](https://travis-ci.org/containerd/containerd.svg?branch=master)](https://travis-ci.org/containerd/containerd)
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fcontainerd%2Fcontainerd.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fcontainerd%2Fcontainerd?ref=badge_shield)
 
-containerd is an industry-standard container runtime with an emphasis on simplicity, robustness and portability. It is available as a daemon for Linux and Windows, which can manage the complete container lifecycle of its host system: image transfer and storage, container execution and supervision, low-level storage and network attachments, etc..
+containerd is an industry-standard container runtime with an emphasis on simplicity, robustness and portability. It is available as a daemon for Linux and Windows, which can manage the complete container lifecycle of its host system: image transfer and storage, container execution and supervision, low-level storage and network attachments, etc.
 
 containerd is designed to be embedded into a larger system, rather than being used directly by developers or end-users.
 
-### State of the Project
+## Features
 
-containerd currently has two active branches.
+### Client
-There is a [v0.2.x](https://github.com/containerd/containerd/tree/v0.2.x) branch for the current release of containerd that is being consumed by Docker and others and the master branch is the development branch for the 1.0 roadmap and feature set.
-Any PR or issue that is intended for the current v0.2.x release should be tagged with the same `v0.2.x` tag.
 
-### Communication
+containerd offers a full client package to help you integrate containerd into your platform.
 
-For async communication and long running discussions please use issues and pull requests on the github repo.
+```go
-This will be the best place to discuss design and implementation.
 
-For sync communication we have a community slack with a #containerd channel that everyone is welcome to join and chat about development.
+import "github.com/containerd/containerd"
 
-**Slack:** https://dockr.ly/community
+func main() {
+	client, err := containerd.New("/run/containerd/containerd.sock")
+	defer client.Close()
+}
+
+```
+
+### Namespaces
+
+Namespaces allow multiple consumers to use the same containerd without conflicting with each other.  It has the benefit of sharing content but still having separation with containers and images.
+
+To set a namespace for requests to the API:
+
+```go
+context    = context.Background()
+// create a context for docker
+docker = namespaces.WithNamespace(context, "docker")
+
+containerd, err := client.NewContainer(docker, "id")
+```
+
+To set a default namespace on the client:
+
+```go
+client, err := containerd.New(address, containerd.WithDefaultNamespace("docker"))
+```
+
+### Distribution
+
+```go
+// pull an image
+image, err := client.Pull(context, "docker.io/library/redis:latest")
+
+// push an image
+err := client.Push(context, "docker.io/library/redis:latest", image.Target())
+```
+
+### OCI Runtime Specification
+
+containerd fully supports the OCI runtime specification for running containers.  We have built in functions to help you generate runtime specifications based on images as well as custom parameters.
+
+```go
+spec, err := containerd.GenerateSpec(containerd.WithImageConfig(context, image))
+```
+
+### Containers
+
+In containerd, a container is a metadata object.  Resources such as an OCI runtime specification, image, root filesystem, and other metadata can be attached to a container.
+
+```go
+redis, err := client.NewContainer(context, "redis-master",
+	containerd.WithSpec(spec),
+)
+defer redis.Delete(context)
+```
+
+## Root Filesystems
+
+containerd allows you to use overlay or snapshot filesystems with your containers.  It comes with builtin support for overlayfs and btrfs.
+
+```go
+// pull an image and unpack it into the configured snapshotter
+image, err := client.Pull(context, "docker.io/library/redis:latest", containerd.WithPullUnpack)
+
+// allocate a new RW root filesystem for a container based on the image
+redis, err := client.NewContainer(context, "redis-master",
+	containerd.WithSpec(spec),
+	containerd.WithNewRootFS("redis-rootfs", image),
+)
+
+// use a readonly filesystem with multiple containers
+for i := 0; i < 10; i++ {
+	id := fmt.Sprintf("id-%s", i)
+	container, err := client.NewContainer(ctx, id,
+		containerd.WithSpec(spec),
+		containerd.WithNewReadonlyRootFS(id, image),
+	)
+}
+```
+
+### Tasks
+
+Taking a container object and turning it into a runnable process on a system is done by creating a new `Task` from the container.  A task represents the runnable object within containerd.
+
+```go
+// create a new task
+task, err := redis.NewTask(context, containerd.Stdio)
+defer task.Delete(context)
+
+// the task is now running and has a pid that can be use to setup networking
+// or other runtime settings outside of containerd
+pid := task.Pid()
+
+// start the redis-server process inside the container
+err := task.Start(context)
+
+// wait for the task to exit and get the exit status
+status, err := task.Wait(context)
+```
+
+### Checkpoint and Restore
+
+If you have [criu](https://criu.org/Main_Page) installed on your machine you can checkpoint and restore containers and their tasks.  This allow you to clone and/or live migrate containers to other machines.
+
+```go
+// checkpoint the task then push it to a registry
+checkpoint, err := task.Checkpoint(context, containerd.WithExit)
+
+err := client.Push(context, "myregistry/checkpoints/redis:master", checkpoint)
+
+// on a new machine pull the checkpoint and restore the redis container
+image, err := client.Pull(context, "myregistry/checkpoints/redis:master")
+
+checkpoint := image.Target()
+
+redis, err = client.NewContainer(context, "redis-master", containerd.WithCheckpoint(checkpoint, "redis-rootfs"))
+defer container.Delete(context)
+
+task, err = redis.NewTask(context, containerd.Stdio, containerd.WithTaskCheckpoint(checkpoint))
+defer task.Delete(context)
+
+err := task.Start(context)
+```
 
 ### Developer Quick-Start
 
@@ -48,44 +167,6 @@ Vendoring of external imports uses the [`vndr` tool](https://github.com/LK4D4/vn
 
 Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd.
 
-## Features
-
-* OCI Image Spec support
-* OCI Runtime Spec support
-* Image push and pull support
-* Container runtime and lifecycle support
-* Management of network namespaces containers to join existing namespaces
-* Multi-tenant supported with CAS storage for global images
-
-## Scope and Principles
-
-Having a clearly defined scope of a project is important for ensuring consistency and focus.
-These following criteria will be used when reviewing pull requests, features, and changes for the project before being accepted.
-
-### Components
-
-Components should not have tight dependencies on each other so that they are able to be used independently.
-The APIs for images and containers should be designed in a way that when used together the components have a natural flow but still be useful independently.
-
-An example for this design can be seen with the overlay filesystems and the container execution layer.
-The execution layer and overlay filesystems can be used independently but if you were to use both, they share a common `Mount` struct that the filesystems produce and the execution layer consumes.
-
-### Primitives
-
-containerd should expose primitives to solve problems instead of building high level abstractions in the API.
-A common example of this is how build would be implemented.
-Instead of having a build API in containerd we should expose the lower level primitives that allow things required in build to work.
-Breaking up the filesystem APIs to allow snapshots, copy functionality, and mounts allow people implementing build at the higher levels more flexibility.
-
-### Extensibility and Defaults
-
-For the various components in containerd there should be defined extension points where implementations can be swapped for alternatives.
-The best example of this is that containerd will use `runc` from OCI as the default runtime in the execution layer but other runtimes conforming to the OCI Runtime specification they can be easily added to containerd.
-
-containerd will come with a default implementation for the various components.
-These defaults will be chosen by the maintainers of the project and should not change unless better tech for that component comes out.
-Additional implementations will not be accepted into the core repository and should be developed in a separate repository not maintained by the containerd maintainers.
-
 ### Releases
 
 containerd will be released with a 1.0 when feature complete and this version will be supported for 1 year with security and bug fixes applied and released.
@@ -97,45 +178,23 @@ There is no compatibility guarantees with upgrades from two minor releases. i.e.
 There are not backwards compatibility guarantees with upgrades to major versions. i.e 1.0.0 to 2.0.0.
 Each major version will be supported for 1 year with bug fixes and security patches.
 
-### Scope
-
-The following table specifies the various components of containerd and general features of container runtimes.
-The table specifies whether or not the feature/component is in or out of scope.
-
-| Name | Description | In/Out | Reason |
-|------------------------------|--------------------------------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| execution | Provide an extensible execution layer for executing a container | in | Create,start, stop pause, resume exec, signal, delete |
-| cow filesystem | Built in functionality for overlay, aufs, and other copy on write filesystems for containers | in |  |
-| distribution | Having the ability to push and pull images as well as operations on images as a first class API object | in | containerd will fully support the management and retrieval of images |
-| metrics | container-level metrics, cgroup stats, and OOM events | in |
-| networking | creation and management of network interfaces | out | Networking will be handled and provided to containerd via higher level systems. |
-| build | Building images as a first class API | out | Build is a higher level tooling feature and can be implemented in many different ways on top of containerd |
-| volumes | Volume management for external data | out | The API supports mounts, binds, etc where all volumes type systems can be built on top of containerd. |
-| logging | Persisting container logs | out | Logging can be build on top of containerd because the container’s STDIO will be provided to the clients and they can persist any way they see fit. There is no io copying of container STDIO in containerd. |
-
-
-containerd is scoped to a single host and makes assumptions based on that fact.
-It can be used to build things like a node agent that launches containers but does not have any concepts of a distributed system.
-
-containerd is designed to be embedded into a larger system, hence it only includes a barebone CLI (`ctr`) specifically for development and debugging purpose, with no mandate to be human-friendly, and no guarantee of interface stability over time.
-
-Also things like service discovery are out of scope even though networking is in scope.
-containerd should provide the primitives to create, add, remove, or manage network interfaces and network namespaces for a container but IP allocation, discovery, and DNS should be handled at higher layers.
-
-### How is the scope changed?
-
-The scope of this project is a whitelist.
-If it's not mentioned as being in scope, it is out of scope.  
-For the scope of this project to change it requires a 100% vote from all maintainers of the project.
-
 ### Development reports.
 
 Weekly summary on the progress and what is being worked on.
 https://github.com/containerd/containerd/tree/master/reports
 
+### Communication
+
+For async communication and long running discussions please use issues and pull requests on the github repo.
+This will be the best place to discuss design and implementation.
+
+For sync communication we have a community slack with a #containerd channel that everyone is welcome to join and chat about development.
+
+**Slack:** https://dockr.ly/community
+
 ## Copyright and license
 
-Copyright © 2016 Docker, Inc. All rights reserved, except as follows. Code
+Copyright ©2016-2017 Docker, Inc. All rights reserved, except as follows. Code
 is released under the Apache 2.0 license. The README.md file, and files in the
 "docs" folder are licensed under the Creative Commons Attribution 4.0
 International License under the terms and conditions set forth in the file

SCOPE.md

@@ -0,0 +1,57 @@
+# Scope and Principles
+
+Having a clearly defined scope of a project is important for ensuring consistency and focus.
+These following criteria will be used when reviewing pull requests, features, and changes for the project before being accepted.
+
+### Components
+
+Components should not have tight dependencies on each other so that they are able to be used independently.
+The APIs for images and containers should be designed in a way that when used together the components have a natural flow but still be useful independently.
+
+An example for this design can be seen with the overlay filesystems and the container execution layer.
+The execution layer and overlay filesystems can be used independently but if you were to use both, they share a common `Mount` struct that the filesystems produce and the execution layer consumes.
+
+### Primitives
+
+containerd should expose primitives to solve problems instead of building high level abstractions in the API.
+A common example of this is how build would be implemented.
+Instead of having a build API in containerd we should expose the lower level primitives that allow things required in build to work.
+Breaking up the filesystem APIs to allow snapshots, copy functionality, and mounts allow people implementing build at the higher levels with more flexibility.
+
+### Extensibility and Defaults
+
+For the various components in containerd there should be defined extension points where implementations can be swapped for alternatives.
+The best example of this is that containerd will use `runc` from OCI as the default runtime in the execution layer but other runtimes conforming to the OCI Runtime specification can be easily added to containerd.
+
+containerd will come with a default implementation for the various components.
+These defaults will be chosen by the maintainers of the project and should not change unless better tech for that component comes out.
+Additional implementations will not be accepted into the core repository and should be developed in a separate repository not maintained by the containerd maintainers.
+
+
+## Scope
+
+The following table specifies the various components of containerd and general features of container runtimes.
+The table specifies whether or not the feature/component is in or out of scope.
+
+| Name | Description | In/Out | Reason |
+|------------------------------|--------------------------------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| execution | Provide an extensible execution layer for executing a container | in | Create,start, stop pause, resume exec, signal, delete |
+| cow filesystem | Built in functionality for overlay, aufs, and other copy on write filesystems for containers | in |  |
+| distribution | Having the ability to push and pull images as well as operations on images as a first class API object | in | containerd will fully support the management and retrieval of images |
+| metrics | container-level metrics, cgroup stats, and OOM events | in |
+| networking | creation and management of network interfaces | out | Networking will be handled and provided to containerd via higher level systems. |
+| build | Building images as a first class API | out | Build is a higher level tooling feature and can be implemented in many different ways on top of containerd |
+| volumes | Volume management for external data | out | The API supports mounts, binds, etc where all volumes type systems can be built on top of containerd. |
+| logging | Persisting container logs | out | Logging can be build on top of containerd because the container’s STDIO will be provided to the clients and they can persist any way they see fit. There is no io copying of container STDIO in containerd. |
+
+
+containerd is scoped to a single host and makes assumptions based on that fact.
+It can be used to build things like a node agent that launches containers but does not have any concepts of a distributed system.
+
+containerd is designed to be embedded into a larger system, hence it only includes a barebone CLI (`ctr`) specifically for development and debugging purpose, with no mandate to be human-friendly, and no guarantee of interface stability over time.
+
+### How is the scope changed?
+
+The scope of this project is a whitelist.
+If it's not mentioned as being in scope, it is out of scope.
+For the scope of this project to change it requires a 100% vote from all maintainers of the project.