Merge pull request #853 from mheon/libpod_state

Add skeletons for libpod container, pod, state

libpod/container.go

@@ -1,19 +1,71 @@
-package ctr
+package libpod
 
 import (
-	"fmt"
+	"sync"
 
 	"github.com/containers/storage"
-)
+	"github.com/docker/docker/pkg/stringid"
-
+	spec "github.com/opencontainers/runtime-spec/specs-go"
-var (
+	"github.com/pkg/errors"
-	// ErrNotImplemented indicates that functionality is not yet implemented
+	"github.com/ulule/deepcopier"
-	ErrNotImplemented = fmt.Errorf("NOT IMPLEMENTED")
 )
 
 // Container is a single OCI container
 type Container struct {
-	// TODO populate
+	id   string
+	name string
+
+	spec *spec.Spec
+	pod  *Pod
+
+	valid bool
+	lock  sync.RWMutex
+}
+
+// ID returns the container's ID
+func (c *Container) ID() string {
+	// No locking needed, ID will never mutate after a container is created
+	return c.id
+}
+
+// Name returns the container's name
+func (c *Container) Name() string {
+	// Name can potentially be changed while a container is running
+	// So lock access to it
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+
+	return c.name
+}
+
+// Spec returns the container's OCI runtime spec
+func (c *Container) Spec() *spec.Spec {
+	// The spec can potentially be altered when storage is configured and to
+	// add annotations at container create time
+	// As such, access to it is locked
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+
+	spec := new(spec.Spec)
+	deepcopier.Copy(c.spec).To(spec)
+
+	return spec
+}
+
+// Make a new container
+func newContainer(rspec *spec.Spec) (*Container, error) {
+	if rspec == nil {
+		return nil, errors.Wrapf(ErrInvalidArg, "must provide a valid runtime spec to create container")
+	}
+
+	ctr := new(Container)
+	ctr.id = stringid.GenerateNonCryptoID()
+	ctr.name = ctr.id // TODO generate unique human-readable names
+
+	ctr.spec = new(spec.Spec)
+	deepcopier.Copy(rspec).To(ctr.spec)
+
+	return ctr, nil
 }
 
 // Create creates a container in the OCI runtime

libpod/errors.go

@@ -0,0 +1,53 @@
+package libpod
+
+import (
+	"errors"
+)
+
+var (
+	// ErrNoSuchCtr indicates the requested container does not exist
+	ErrNoSuchCtr = errors.New("no such container")
+	// ErrNoSuchPod indicates the requested pod does not exist
+	ErrNoSuchPod = errors.New("no such pod")
+	// ErrNoSuchImage indicates the requested image does not exist
+	ErrNoSuchImage = errors.New("no such image")
+
+	// ErrCtrExists indicates a container with the same name or ID already
+	// exists
+	ErrCtrExists = errors.New("container already exists")
+	// ErrPodExists indicates a pod with the same name or ID already exists
+	ErrPodExists = errors.New("pod already exists")
+	// ErrImageExists indicated an image with the same ID already exists
+	ErrImageExists = errors.New("image already exists")
+
+	// ErrRuntimeFinalized indicates that the runtime has already been
+	// created and cannot be modified
+	ErrRuntimeFinalized = errors.New("runtime has been finalized")
+	// ErrCtrFinalized indicates that the container has already been created
+	// and cannot be modified
+	ErrCtrFinalized = errors.New("container has been finalized")
+	// ErrPodFinalized indicates that the pod has already been created and
+	// cannot be modified
+	ErrPodFinalized = errors.New("pod has been finalized")
+
+	// ErrInvalidArg indicates that an invalid argument was passed
+	ErrInvalidArg = errors.New("invalid argument")
+
+	// ErrRuntimeStopped indicates that the runtime has already been shut
+	// down and no further operations can be performed on it
+	ErrRuntimeStopped = errors.New("runtime has already been stopped")
+	// ErrCtrStopped indicates that the requested container is not running
+	// and the requested operation cannot be performed until it is started
+	ErrCtrStopped = errors.New("container is stopped")
+
+	// ErrCtrRemoved indicates that the container has already been removed
+	// and no further operations can be performed on it
+	ErrCtrRemoved = errors.New("container has already been removed")
+	// ErrPodRemoved indicates that the pod has already been removed and no
+	// further operations can be performed on it
+	ErrPodRemoved = errors.New("pod has already been removed")
+
+	// ErrNotImplemented indicates that the requested functionality is not
+	// yet present
+	ErrNotImplemented = errors.New("not yet implemented")
+)

libpod/image.go

@@ -18,7 +18,6 @@ import (
 	"github.com/containers/storage"
 	"github.com/containers/storage/pkg/archive"
 	"github.com/kubernetes-incubator/cri-o/libpod/common"
-	"github.com/kubernetes-incubator/cri-o/libpod/ctr"
 	"github.com/kubernetes-incubator/cri-o/libpod/images"
 	"github.com/pkg/errors"
 )
@@ -354,10 +353,10 @@ func (r *Runtime) GetImageRef(image string) (types.Image, error) {
 // output. Multiple filters are handled by ANDing their output, so only images
 // matching all filters are included
 func (r *Runtime) GetImages(filter ...ImageFilter) ([]*storage.Image, error) {
-	return nil, ctr.ErrNotImplemented
+	return nil, ErrNotImplemented
 }
 
 // ImportImage imports an OCI format image archive into storage as an image
 func (r *Runtime) ImportImage(path string) (*storage.Image, error) {
-	return nil, ctr.ErrNotImplemented
+	return nil, ErrNotImplemented
 }

libpod/options.go

@@ -5,13 +5,11 @@ import (
 
 	"github.com/containers/storage"
 	"github.com/containers/storage/pkg/idtools"
-	"github.com/kubernetes-incubator/cri-o/libpod/ctr"
+	"github.com/pkg/errors"
-	"github.com/kubernetes-incubator/cri-o/libpod/pod"
 )
 
 var (
-	errRuntimeFinalized = fmt.Errorf("runtime has already been finalized")
+	ctrNotImplemented = func(c *Container) error {
-	ctrNotImplemented   = func(c *ctr.Container) error {
 		return fmt.Errorf("NOT IMPLEMENTED")
 	}
 )
@@ -39,7 +37,7 @@ const (
 func WithStorageConfig(config storage.StoreOptions) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.StorageConfig.RunRoot = config.RunRoot
@@ -65,7 +63,7 @@ func WithStorageConfig(config storage.StoreOptions) RuntimeOption {
 func WithImageConfig(defaultTransport string, insecureRegistries, registries []string) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.ImageDefaultTransport = defaultTransport
@@ -87,7 +85,7 @@ func WithImageConfig(defaultTransport string, insecureRegistries, registries []s
 func WithSignaturePolicy(path string) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.SignaturePolicyPath = path
@@ -100,7 +98,7 @@ func WithSignaturePolicy(path string) RuntimeOption {
 func WithOCIRuntime(runtimePath string) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.RuntimePath = runtimePath
@@ -114,7 +112,7 @@ func WithOCIRuntime(runtimePath string) RuntimeOption {
 func WithConmonPath(path string) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.ConmonPath = path
@@ -127,7 +125,7 @@ func WithConmonPath(path string) RuntimeOption {
 func WithConmonEnv(environment []string) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.ConmonEnvVars = make([]string, len(environment))
@@ -142,7 +140,7 @@ func WithConmonEnv(environment []string) RuntimeOption {
 func WithCgroupManager(manager string) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.CgroupManager = manager
@@ -155,7 +153,7 @@ func WithCgroupManager(manager string) RuntimeOption {
 func WithSELinux() RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.SelinuxEnabled = true
@@ -169,7 +167,7 @@ func WithSELinux() RuntimeOption {
 func WithPidsLimit(limit int64) RuntimeOption {
 	return func(rt *Runtime) error {
 		if rt.valid {
-			return errRuntimeFinalized
+			return ErrRuntimeFinalized
 		}
 
 		rt.config.PidsLimit = limit
@@ -198,13 +196,36 @@ func WithRootFSFromImage(image string, useImageConfig bool) CtrCreateOption {
 // be added to the pod.
 // By default no namespaces are shared. To share a namespace, add the Namespace
 // string constant to the map as a key
-func WithSharedNamespaces(from *ctr.Container, namespaces map[string]string) CtrCreateOption {
+func WithSharedNamespaces(from *Container, namespaces map[string]string) CtrCreateOption {
 	return ctrNotImplemented
 }
 
 // WithPod adds the container to a pod
-func WithPod(pod *pod.Pod) CtrCreateOption {
+func (r *Runtime) WithPod(pod *Pod) CtrCreateOption {
-	return ctrNotImplemented
+	return func(ctr *Container) error {
+		if !ctr.valid {
+			return ErrCtrFinalized
+		}
+
+		if ctr.pod != nil {
+			return fmt.Errorf("container has already been added to a pod")
+		}
+
+		exists, err := r.state.HasPod(pod.ID())
+		if err != nil {
+			return errors.Wrapf(err, "error searching state for pod %s", pod.ID())
+		} else if !exists {
+			return errors.Wrapf(ErrNoSuchPod, "pod %s cannot be found in state", pod.ID())
+		}
+
+		if err := pod.addContainer(ctr); err != nil {
+			return errors.Wrapf(err, "error adding container to pod")
+		}
+
+		ctr.pod = pod
+
+		return nil
+	}
 }
 
 // WithLabels adds labels to the pod
@@ -219,10 +240,33 @@ func WithAnnotations(annotations map[string]string) CtrCreateOption {
 
 // WithName sets the container's name
 func WithName(name string) CtrCreateOption {
-	return ctrNotImplemented
+	return func(ctr *Container) error {
+		if !ctr.valid {
+			return ErrCtrFinalized
+		}
+
+		ctr.name = name
+
+		return nil
+	}
 }
 
 // WithStopSignal sets the signal that will be sent to stop the container
 func WithStopSignal(signal uint) CtrCreateOption {
 	return ctrNotImplemented
 }
+
+// Pod Creation Options
+
+// WithPodName sets the name of the pod
+func WithPodName(name string) PodCreateOption {
+	return func(pod *Pod) error {
+		if pod.valid {
+			return ErrPodFinalized
+		}
+
+		pod.name = name
+
+		return nil
+	}
+}

libpod/pod.go

@@ -0,0 +1,117 @@
+package libpod
+
+import (
+	"sync"
+
+	"github.com/docker/docker/pkg/stringid"
+	"github.com/pkg/errors"
+)
+
+// Pod represents a group of containers that may share namespaces
+type Pod struct {
+	id   string
+	name string
+
+	containers map[string]*Container
+
+	valid bool
+	lock  sync.RWMutex
+}
+
+// ID retrieves the pod's ID
+func (p *Pod) ID() string {
+	return p.id
+}
+
+// Name retrieves the pod's name
+func (p *Pod) Name() string {
+	return p.name
+}
+
+// Creates a new pod
+func newPod() (*Pod, error) {
+	pod := new(Pod)
+	pod.id = stringid.GenerateNonCryptoID()
+	pod.name = pod.id // TODO generate human-readable name here
+
+	pod.containers = make(map[string]*Container)
+
+	return pod, nil
+}
+
+// Adds a container to the pod
+// Does not check that container's pod ID is set correctly, or attempt to set
+// pod ID after adding
+func (p *Pod) addContainer(ctr *Container) error {
+	p.lock.Lock()
+	defer p.lock.Unlock()
+
+	if !p.valid {
+		return ErrPodRemoved
+	}
+
+	if _, ok := p.containers[ctr.id]; ok {
+		return errors.Wrapf(ErrCtrExists, "container with ID %s already exists in pod %s", ctr.id, p.id)
+	}
+
+	p.containers[ctr.id] = ctr
+
+	return nil
+}
+
+// Removes a container from the pod
+// Does not perform any checks on the container
+func (p *Pod) removeContainer(ctr *Container) error {
+	p.lock.Lock()
+	defer p.lock.Unlock()
+
+	if !p.valid {
+		return ErrPodRemoved
+	}
+
+	if _, ok := p.containers[ctr.id]; !ok {
+		return errors.Wrapf(ErrNoSuchCtr, "no container with id %s in pod %s", ctr.id, p.id)
+	}
+
+	delete(p.containers, ctr.id)
+
+	return nil
+}
+
+// Start starts all containers within a pod that are not already running
+func (p *Pod) Start() error {
+	return ErrNotImplemented
+}
+
+// Stop stops all containers within a pod that are not already stopped
+func (p *Pod) Stop() error {
+	return ErrNotImplemented
+}
+
+// Kill sends a signal to all running containers within a pod
+func (p *Pod) Kill(signal uint) error {
+	return ErrNotImplemented
+}
+
+// GetContainers retrieves the containers in the pod
+func (p *Pod) GetContainers() ([]*Container, error) {
+	p.lock.RLock()
+	defer p.lock.RUnlock()
+
+	if !p.valid {
+		return nil, ErrPodRemoved
+	}
+
+	ctrs := make([]*Container, 0, len(p.containers))
+	for _, ctr := range p.containers {
+		ctrs = append(ctrs, ctr)
+	}
+
+	return ctrs, nil
+}
+
+// Status gets the status of all containers in the pod
+// TODO This should return a summary of the states of all containers in the pod
+func (p *Pod) Status() error {
+	return ErrNotImplemented
+}

libpod/pod/pod.go

@@ -1,36 +0,0 @@
-package pod
-
-import (
-	"github.com/kubernetes-incubator/cri-o/libpod/ctr"
-)
-
-// Pod represents a group of containers that may share namespaces
-type Pod struct {
-	// TODO populate
-}
-
-// Start starts all containers within a pod that are not already running
-func (p *Pod) Start() error {
-	return ctr.ErrNotImplemented
-}
-
-// Stop stops all containers within a pod that are not already stopped
-func (p *Pod) Stop() error {
-	return ctr.ErrNotImplemented
-}
-
-// Kill sends a signal to all running containers within a pod
-func (p *Pod) Kill(signal uint) error {
-	return ctr.ErrNotImplemented
-}
-
-// GetContainers retrieves the containers in the pod
-func (p *Pod) GetContainers() ([]*ctr.Container, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// Status gets the status of all containers in the pod
-// TODO This should return a summary of the states of all containers in the pod
-func (p *Pod) Status() error {
-	return ctr.ErrNotImplemented
-}

libpod/runtime.go

@@ -1,16 +1,12 @@
 package libpod
 
 import (
-	"fmt"
 	"sync"
 
 	"github.com/containers/image/types"
 	"github.com/containers/storage"
-	"github.com/kubernetes-incubator/cri-o/libpod/ctr"
-	"github.com/kubernetes-incubator/cri-o/libpod/pod"
 	"github.com/kubernetes-incubator/cri-o/server/apparmor"
 	"github.com/kubernetes-incubator/cri-o/server/seccomp"
-	spec "github.com/opencontainers/runtime-spec/specs-go"
 	"github.com/pkg/errors"
 	"github.com/ulule/deepcopier"
 )
@@ -22,6 +18,7 @@ type RuntimeOption func(*Runtime) error
 // Runtime is the core libpod runtime
 type Runtime struct {
 	config          *RuntimeConfig
+	state           State
 	store           storage.Store
 	imageContext    *types.SystemContext
 	apparmorEnabled bool
@@ -125,90 +122,11 @@ func (r *Runtime) Shutdown(force bool) error {
 	defer r.lock.Unlock()
 
 	if !r.valid {
-		return fmt.Errorf("runtime has already been shut down")
+		return ErrRuntimeStopped
 	}
 
+	r.valid = false
+
 	_, err := r.store.Shutdown(force)
 	return err
 }
-
-// Container API
-
-// A CtrCreateOption is a functional option which alters the Container created
-// by NewContainer
-type CtrCreateOption func(*ctr.Container) error
-
-// ContainerFilter is a function to determine whether a container is included
-// in command output. Containers to be outputted are tested using the function.
-// A true return will include the container, a false return will exclude it.
-type ContainerFilter func(*ctr.Container) bool
-
-// NewContainer creates a new container from a given OCI config
-func (r *Runtime) NewContainer(spec *spec.Spec, options ...CtrCreateOption) (*ctr.Container, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// RemoveContainer removes the given container
-// If force is specified, the container will be stopped first
-// Otherwise, RemoveContainer will return an error if the container is running
-func (r *Runtime) RemoveContainer(c *ctr.Container, force bool) error {
-	return ctr.ErrNotImplemented
-}
-
-// GetContainer retrieves a container by its ID
-func (r *Runtime) GetContainer(id string) (*ctr.Container, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// LookupContainer looks up a container by its name or a partial ID
-// If a partial ID is not unique, an error will be returned
-func (r *Runtime) LookupContainer(idOrName string) (*ctr.Container, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// GetContainers retrieves all containers from the state
-// Filters can be provided which will determine what containers are included in
-// the output. Multiple filters are handled by ANDing their output, so only
-// containers matching all filters are returned
-func (r *Runtime) GetContainers(filters ...ContainerFilter) ([]*ctr.Container, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// Pod API
-
-// PodFilter is a function to determine whether a pod is included in command
-// output. Pods to be outputted are tested using the function. A true return
-// will include the pod, a false return will exclude it.
-type PodFilter func(*pod.Pod) bool
-
-// NewPod makes a new, empty pod
-func (r *Runtime) NewPod() (*pod.Pod, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// RemovePod removes a pod and all containers in it
-// If force is specified, all containers in the pod will be stopped first
-// Otherwise, RemovePod will return an error if any container in the pod is running
-// Remove acts atomically, removing all containers or no containers
-func (r *Runtime) RemovePod(p *pod.Pod, force bool) error {
-	return ctr.ErrNotImplemented
-}
-
-// GetPod retrieves a pod by its ID
-func (r *Runtime) GetPod(id string) (*pod.Pod, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// LookupPod retrieves a pod by its name or a partial ID
-// If a partial ID is not unique, an error will be returned
-func (r *Runtime) LookupPod(idOrName string) (*pod.Pod, error) {
-	return nil, ctr.ErrNotImplemented
-}
-
-// GetPods retrieves all pods
-// Filters can be provided which will determine which pods are included in the
-// output. Multiple filters are handled by ANDing their output, so only pods
-// matching all filters are returned
-func (r *Runtime) GetPods(filters ...PodFilter) ([]*pod.Pod, error) {
-	return nil, ctr.ErrNotImplemented
-}

libpod/runtime_ctr.go

@@ -0,0 +1,133 @@
+package libpod
+
+import (
+	spec "github.com/opencontainers/runtime-spec/specs-go"
+	"github.com/pkg/errors"
+)
+
+// Contains the public Runtime API for containers
+
+// A CtrCreateOption is a functional option which alters the Container created
+// by NewContainer
+type CtrCreateOption func(*Container) error
+
+// ContainerFilter is a function to determine whether a container is included
+// in command output. Containers to be outputted are tested using the function.
+// A true return will include the container, a false return will exclude it.
+type ContainerFilter func(*Container) bool
+
+// NewContainer creates a new container from a given OCI config
+func (r *Runtime) NewContainer(spec *spec.Spec, options ...CtrCreateOption) (*Container, error) {
+	r.lock.Lock()
+	defer r.lock.Unlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	ctr, err := newContainer(spec)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, option := range options {
+		if err := option(ctr); err != nil {
+			return nil, errors.Wrapf(err, "error running container create option")
+		}
+	}
+
+	ctr.valid = true
+
+	if err := r.state.AddContainer(ctr); err != nil {
+		// If we joined a pod, remove ourself from it
+		if ctr.pod != nil {
+			if err2 := ctr.pod.removeContainer(ctr); err2 != nil {
+				return nil, errors.Wrapf(err, "error adding new container to state, container could not be removed from pod %s", ctr.pod.ID())
+			}
+		}
+
+		// TODO: Might be worth making an effort to detect duplicate IDs
+		// We can recover from that by generating a new ID for the
+		// container
+		return nil, errors.Wrapf(err, "error adding new container to state")
+	}
+
+	return ctr, nil
+}
+
+// RemoveContainer removes the given container
+// If force is specified, the container will be stopped first
+// Otherwise, RemoveContainer will return an error if the container is running
+func (r *Runtime) RemoveContainer(c *Container, force bool) error {
+	return ErrNotImplemented
+}
+
+// GetContainer retrieves a container by its ID
+func (r *Runtime) GetContainer(id string) (*Container, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	return r.state.GetContainer(id)
+}
+
+// HasContainer checks if a container with the given ID is present
+func (r *Runtime) HasContainer(id string) (bool, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return false, ErrRuntimeStopped
+	}
+
+	return r.state.HasContainer(id)
+}
+
+// LookupContainer looks up a container by its name or a partial ID
+// If a partial ID is not unique, an error will be returned
+func (r *Runtime) LookupContainer(idOrName string) (*Container, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	return r.state.LookupContainer(idOrName)
+}
+
+// Containers retrieves all containers from the state
+// Filters can be provided which will determine what containers are included in
+// the output. Multiple filters are handled by ANDing their output, so only
+// containers matching all filters are returned
+func (r *Runtime) Containers(filters ...ContainerFilter) ([]*Container, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	ctrs, err := r.state.GetAllContainers()
+	if err != nil {
+		return nil, err
+	}
+
+	ctrsFiltered := make([]*Container, 0, len(ctrs))
+
+	for _, ctr := range ctrs {
+		include := true
+		for _, filter := range filters {
+			include = include && filter(ctr)
+		}
+
+		if include {
+			ctrsFiltered = append(ctrsFiltered, ctr)
+		}
+	}
+
+	return ctrsFiltered, nil
+}

libpod/runtime_pod.go

@@ -0,0 +1,122 @@
+package libpod
+
+import (
+	"github.com/pkg/errors"
+)
+
+// Contains the public Runtime API for pods
+
+// A PodCreateOption is a functional option which alters the Pod created by
+// NewPod
+type PodCreateOption func(*Pod) error
+
+// PodFilter is a function to determine whether a pod is included in command
+// output. Pods to be outputted are tested using the function. A true return
+// will include the pod, a false return will exclude it.
+type PodFilter func(*Pod) bool
+
+// NewPod makes a new, empty pod
+func (r *Runtime) NewPod(options ...PodCreateOption) (*Pod, error) {
+	r.lock.Lock()
+	defer r.lock.Unlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	pod, err := newPod()
+	if err != nil {
+		return nil, errors.Wrapf(err, "error creating pod")
+	}
+
+	for _, option := range options {
+		if err := option(pod); err != nil {
+			return nil, errors.Wrapf(err, "error running pod create option")
+		}
+	}
+
+	pod.valid = true
+
+	if err := r.state.AddPod(pod); err != nil {
+		return nil, errors.Wrapf(err, "error adding pod to state")
+	}
+
+	return nil, ErrNotImplemented
+}
+
+// RemovePod removes a pod and all containers in it
+// If force is specified, all containers in the pod will be stopped first
+// Otherwise, RemovePod will return an error if any container in the pod is running
+// Remove acts atomically, removing all containers or no containers
+func (r *Runtime) RemovePod(p *Pod, force bool) error {
+	return ErrNotImplemented
+}
+
+// GetPod retrieves a pod by its ID
+func (r *Runtime) GetPod(id string) (*Pod, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	return r.state.GetPod(id)
+}
+
+// HasPod checks to see if a pod with the given ID exists
+func (r *Runtime) HasPod(id string) (bool, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return false, ErrRuntimeStopped
+	}
+
+	return r.state.HasPod(id)
+}
+
+// LookupPod retrieves a pod by its name or a partial ID
+// If a partial ID is not unique, an error will be returned
+func (r *Runtime) LookupPod(idOrName string) (*Pod, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	return r.state.LookupPod(idOrName)
+}
+
+// Pods retrieves all pods
+// Filters can be provided which will determine which pods are included in the
+// output. Multiple filters are handled by ANDing their output, so only pods
+// matching all filters are returned
+func (r *Runtime) Pods(filters ...PodFilter) ([]*Pod, error) {
+	r.lock.RLock()
+	defer r.lock.RUnlock()
+
+	if !r.valid {
+		return nil, ErrRuntimeStopped
+	}
+
+	pods, err := r.state.GetAllPods()
+	if err != nil {
+		return nil, err
+	}
+
+	podsFiltered := make([]*Pod, 0, len(pods))
+	for _, pod := range pods {
+		include := true
+		for _, filter := range filters {
+			include = include && filter(pod)
+		}
+
+		if include {
+			podsFiltered = append(podsFiltered, pod)
+		}
+	}
+
+	return podsFiltered, nil
+}

libpod/state.go

@@ -0,0 +1,37 @@
+package libpod
+
+// State is a storage backend for libpod's current state
+type State interface {
+	// Accepts full ID of container
+	GetContainer(id string) (*Container, error)
+	// Accepts full or partial IDs (as long as they are unique) and names
+	LookupContainer(idOrName string) (*Container, error)
+	// Checks if a container with the given ID is present in the state
+	HasContainer(id string) (bool, error)
+	// Adds container to state
+	// If the container belongs to a pod, that pod must already be present
+	// in the state when the container is added
+	AddContainer(ctr *Container) error
+	// Removes container from state
+	// If the container belongs to a pod, it will be removed from the pod
+	// as well
+	RemoveContainer(ctr *Container) error
+	// Retrieves all containers presently in state
+	GetAllContainers() ([]*Container, error)
+
+	// Accepts full ID of pod
+	GetPod(id string) (*Pod, error)
+	// Accepts full or partial IDs (as long as they are unique) and names
+	LookupPod(idOrName string) (*Pod, error)
+	// Checks if a pod with the given ID is present in the state
+	HasPod(id string) (bool, error)
+	// Adds pod to state
+	// Any containers within the pod not already in the state will be added
+	// with it
+	AddPod(pod *Pod) error
+	// Removes pod from state
+	// All containers within the pod will also be removed
+	RemovePod(pod *Pod) error
+	// Retrieves all pods presently in state
+	GetAllPods() ([]*Pod, error)
+}