Skip to content

Commit

Permalink
Rationalise documentation
Browse files Browse the repository at this point in the history 
Move the protobufs/REST docs to the Go interfaces which are now deemed
to be the canonical API to garden and minimise the REST API docs (so
that they are sufficient for anyone kicking the tyres, but not much
else).

[#86190072]
  • Loading branch information
@glyn
glyn committed Jan 15, 2015
1 parent 8bacbad commit e12fd8b
Show file tree
Hide file tree
Showing 4 changed files with 251 additions and 227 deletions.
120 changes: 114 additions & 6 deletions client.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,50 @@ import (
)

type Client interface {
// Pings the garden server.
//
// Errors:
// * None.
Ping() error

// Capacity returns the physical capacity of the server's machine.
//
// Errors:
// * None.
Capacity() (Capacity, error)

// Create creates a new container.
//
// Errors:
// * When the handle, if specified, is already taken.
// * When one of the bind_mount paths does not exist.
// * When resource allocations fail (subnet, user ID, etc).
Create(ContainerSpec) (Container, error)

// Destroy destroys a container.
//
// When a container is destroyed, its resource allocations are released,
// its filesystem is removed, and all references to its handle are removed.
//
// All resources that have been acquired during the lifetime of the container are released.
// Examples of these resources are its subnet, its UID, and ports that were redirected to the container.
//
// TODO: list the resources that can be acquired during the lifetime of a container.
//
// Errors:
// * TODO.
Destroy(handle string) error

// Containers lists all containers filtered by Properties (which are ANDed together).
//
// Errors:
// * None.
Containers(Properties) ([]Container, error)

// Lookup returns the container with the specified handle.
//
// Errors:
// * Container not found.
Lookup(handle string) (Container, error)
}

Expand All @@ -24,22 +61,93 @@ func (err ContainerNotFoundError) Error() string {
return fmt.Sprintf("unknown handle: %s", err.Handle)
}

// ContainerSpec specifies the parameters for creating a container. All parameters are optional.
type ContainerSpec struct {
Handle string
GraceTime time.Duration

// Handle, if specified, is used to refer to the
// container in future requests. If it is not specified,
// garden uses its internal container ID as the container handle.
Handle string

// GraceTime can be used to specify how long a container can go
// unreferenced by any client connection. After this time, the container will
// automatically be destroyed. If not specified, the container will be
// subject to the globally configured grace time.
GraceTime time.Duration

// TODO
RootFSPath string

// * bind_mounts: a list of mount point descriptions which will result in corresponding mount
// points being created in the container's file system.
//
// An error is returned if:
// * one or more of the mount points has a non-existent source directory, or
// * one or more of the mount points cannot be created.
BindMounts []BindMount
Network string

// Network determines the subnet and IP address of a container.
//
// If not specified, a /30 subnet is allocated from a default network pool.
//
// If specified, it takes the form a.b.c.d/n where a.b.c.d is an IP address and n is the number of
// bits in the network prefix. a.b.c.d masked by the first n bits is the network address of a subnet
// called the subnet address. If the remaining bits are zero (i.e. a.b.c.d *is* the subnet address),
// the container is allocated an unused IP address from the subnet. Otherwise, the container is given
// the IP address a.b.c.d.
//
// The container IP address cannot be the subnet address or the broadcast address of the subnet
// (all non prefix bits set) or the address one less than the broadcast address (which is reserved).
//
// Multiple containers may share a subnet by passing the same subnet address on the corresponding
// create calls. Containers on the same subnet can communicate with each other over IP
// without restriction. In particular, they are not affected by packet filtering.
//
// An error is returned if:
// * the IP address cannot be allocated or is already in use,
// * the subnet specified overlaps the default network pool, or
// * the subnet specified overlaps (but does not equal) a subnet that has
// already had a container allocated from it.
Network string

// Properties is a sequence of string key/value pairs providing arbitrary
// data about the container. The keys are assumed to be unique but this is not
// enforced via the protocol.
Properties Properties
Env []string

// TODO
Env []string

// If Privileged is true the container does not have a user namespace and the root user in the container
// is the same as the root user in the host. Otherwise, the container has a user namespace and the root
// user in the container is mapped to a non-root user in the host. Defaults to false.
Privileged bool
}

// BindMount specifies parameters for a single mount point.
//
// Each mount point is mounted (with the bind option) into the container's file system.
// The effective permissions of the mount point are the permissions of the source directory if the mode
// is read-write and the permissions of the source directory with the write bits turned off if the mode
// of the mount point is read-only.
type BindMount struct {
// SrcPath contains the path of the directory to be mounted.
SrcPath string

// DstPath contains the path of the mount point in the container. If the
// directory does not exist, it is created.
DstPath string
Mode BindMountMode
Origin BindMountOrigin

// Mode must be either "RO" or "RW". Alternatively, mode may be omitted and defaults to RO.
// If mode is "RO", a read-only mount point is created.
// If mode is "RW", a read-write mount point is created.
Mode BindMountMode

// BindMountOrigin must be either "Host" or "Container". Alternatively, origin may be omitted and
// defaults to "Host".
// If origin is "Host", src_path denotes a path in the host.
// If origin is "Container", src_path denotes a path in the container.
Origin BindMountOrigin
}

type Capacity struct {
Expand Down
161 changes: 136 additions & 25 deletions container.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,138 @@ import (
type Container interface {
Handle() string

// Stop stops a container.
//
// If kill is false, garden stops a container by sending the processes running inside it the SIGTERM signal.
// It then waits for the processes to terminate before returning a response.
// If one or more processes do not terminate within 10 seconds,
// garden sends these processes the SIGKILL signal, killing them ungracefully.
//
// If kill is true, garden stops a container by sending the processing running inside it a SIGKILL signal.
//
// Once a container is stopped, garden does not allow spawning new processes inside the container.
// It is possible to copy files in to and out of a stopped container.
// It is only when a container is destroyed that its filesystem is cleaned up.
//
// Errors:
// * None.
Stop(kill bool) error

// Returns information about a container.
Info() (ContainerInfo, error)

// StreamIn streams data into a file in a container.
//
// Errors:
// * TODO.
StreamIn(dstPath string, tarStream io.Reader) error

// StreamOut streams a file out of a container.
//
// Errors:
// * TODO.
StreamOut(srcPath string) (io.ReadCloser, error)

// Limits the network bandwidth for a container.
LimitBandwidth(limits BandwidthLimits) error

CurrentBandwidthLimits() (BandwidthLimits, error)

// Limits the CPU shares for a container.
LimitCPU(limits CPULimits) error

CurrentCPULimits() (CPULimits, error)

// Limits the disk usage for a container.
//
// The disk limits that are set by this command only have effect for the container's unprivileged user.
// Files/directories created by its privileged user are not subject to these limits.
//
// TODO: explain how disk management works.
LimitDisk(limits DiskLimits) error
CurrentDiskLimits() (DiskLimits, error)

// Limits the memory usage for a container.
//
// The limit applies to all process in the container. When the limit is
// exceeded, the container will be automatically stopped.
//
// Errors:
// * The kernel does not support setting memory.memsw.limit_in_bytes.
LimitMemory(limits MemoryLimits) error

CurrentMemoryLimits() (MemoryLimits, error)

// Map a port on the host to a port in the container so that traffic to the
// host port is forwarded to the container port.
//
// If a host port is not given, a port will be acquired from the server's port
// pool.
//
// If a container port is not given, the port will be the same as the
// container port.
//
// The two resulting ports are returned in the response.
//
// Errors:
// * When no port can be acquired from the server's port pool.
NetIn(hostPort, containerPort uint32) (uint32, uint32, error)

// Whitelist outbound network traffic.
//
// If the configuration directive deny_networks is not used,
// all networks are already whitelisted and this command is effectively a no-op.
//
// * network: Network to whitelist (in the form 1.2.3.4/8) or a range of IP
// addresses to whitelist (separated by -)
//
// * port: Port to whitelist.
//
// * portRange: Colon separated port range (in the form 8080:9080).
//
// * protocol : the protocol to be whitelisted (default TCP)
//
// * icmpType: the ICMP type value to be whitelisted when protocol=ICMP (a
// value of -1 means all types and is the default)
//
// * icmpCode: the ICMP code value to be whitelisted when protocol=ICMP (a
// value of -1 means all codes and is the default)
//
// Errors:
// * None.
NetOut(network string, port uint32, portRange string, protocol Protocol, icmpType int32, icmpCode int32) error

// Run a script inside a container.
//
// The 'privileged' flag remains for backwards compatibility, but the 'user' flag is preferred.
// The root user will be mapped to a non-root UID in the host unless the container (not this process) was created with 'privileged' true.
//
// Errors:
// * TODO.
Run(ProcessSpec, ProcessIO) (Process, error)
Attach(uint32, ProcessIO) (Process, error)

// Attach starts streaming the output back to the client from a specified process.
//
// Errors:
// * processID does not refer to a running process.
Attach(processID uint32, io ProcessIO) (Process, error)

// GetProperty returns the value of the property with the specified name.
//
// Errors:
// * When the property does not exist on the container.
GetProperty(name string) (string, error)

// Set a named property on a container to a specified value.
//
// Errors:
// * None.
SetProperty(name string, value string) error

// Remove a property with the specified name from a container.
//
// Errors:
// * None.
RemoveProperty(name string) error
}

Expand All @@ -47,17 +152,18 @@ const (
ProtocolAll Protocol = (1 << iota) - 1
)

// ProcessSpec contains parameters for running a script inside a container.
type ProcessSpec struct {
Path string
Args []string
Env []string
Dir string
Path string // Path to command to execute.
Args []string // Arguments to pass to command.
Env []string // Environment variables.
Dir string // Working directory (default: home directory).

Privileged bool
User string
Privileged bool // Whether to run the script as root or not. Can be overriden by 'user', if specified.
User string // The name of a user in the container to run the process as. If not specified defaults to 'root' for privileged processes, and 'vcap' for unprivileged processes.

Limits ResourceLimits
TTY *TTYSpec
Limits ResourceLimits // Resource limits
TTY *TTYSpec // Execute with a TTY for stdio.
}

type TTYSpec struct {
Expand Down Expand Up @@ -94,20 +200,21 @@ type PortMapping struct {
ContainerPort uint32
}

// ContainerInfo holds information about a container.
type ContainerInfo struct {
State string
Events []string
HostIP string
ContainerIP string
ExternalIP string
ContainerPath string
ProcessIDs []uint32
MemoryStat ContainerMemoryStat
CPUStat ContainerCPUStat
DiskStat ContainerDiskStat
BandwidthStat ContainerBandwidthStat
Properties Properties
MappedPorts []PortMapping
State string // Either "active" or "stopped".
Events []string // List of events that occurred for the container. It currently includes only "oom" (Out Of Memory) event if it occurred.
HostIP string // The IP address of the gateway which controls the host side of the container's virtual ethernet pair.
ContainerIP string // The IP address of the container side of the container's virtual ethernet pair.
ExternalIP string //
ContainerPath string // The path to the directory holding the container's files (both its control scripts and filesystem).
ProcessIDs []uint32 // List of running processes.
MemoryStat ContainerMemoryStat //
CPUStat ContainerCPUStat //
DiskStat ContainerDiskStat //
BandwidthStat ContainerBandwidthStat //
Properties Properties // List of properties defined for the container.
MappedPorts []PortMapping //
}

type ContainerMemoryStat struct {
Expand Down Expand Up @@ -171,18 +278,22 @@ type DiskLimits struct {
InodeSoft uint64
InodeHard uint64

ByteSoft uint64
ByteHard uint64
ByteSoft uint64 // New soft block limit specified in bytes. Only has effect when BlockSoft is not specified.
ByteHard uint64 // New hard block limit specified in bytes. Only has effect when BlockHard is not specified.
}

type MemoryLimits struct {
LimitInBytes uint64
LimitInBytes uint64 // Memory usage limit in bytes.
}

type CPULimits struct {
LimitInShares uint64
}

// Resource limits.
//
// Please refer to the manual page of getrlimit for a description of the individual fields:
// http://www.kernel.org/doc/man-pages/online/pages/man2/getrlimit.2.html
type ResourceLimits struct {
As *uint64
Core *uint64
Expand Down
Loading

0 comments on commit e12fd8b

Please sign in to comment.