api

type AttachVM ¶

type AttachVM struct {
	ContainerID string `json:"containerId"`
	// NumIOStreams asks for a number of I/O tokens. See RegisterVM for
	// some details on I/O tokens.
	NumIOStreams int `json:"numIOStreams,omitempty"`
}

The AttachVM payload can be used to associate clients to an already known VM. AttachVM cannot be issued if a RegisterVM for this container hasn't been issued beforehand.

{
  "containerId": "756535dc6e9ab9b560f84c8...".
  "numIOStreams: 1
}

type AttachVMResponse ¶

type AttachVMResponse struct {
	// IO contains the proxy answer when asking for I/O tokens.
	IO IOResponse `json:"io,omitempty"`
}

AttachVMResponse is the result from a successful AttachVM.

{
  "io": {
    "url": "unix:///run/clearcontainers/proxy.sock",
    "tokens": [
      "bwgxfmQj9uG3YCsFHrvontwDw41CJJ76Y7qVt4Bi9wc="
    ]
  }
}

type Command ¶

type Command int

Command is the kind of command being sent. In the frame header, Opcode must have one of these values when Type is api.TypeCommand.

const (
	// CmdRegisterVM registers a new VM/POD.
	CmdRegisterVM Command = iota
	// CmdUnregisterVM unregisters a VM/POD.
	CmdUnregisterVM
	// CmdAttachVM attaches to a registered VM.
	CmdAttachVM
	// CmdHyper sends a hyperstart command through the proxy.
	CmdHyper
	// CmdConnectShim identifies the client as a shim.
	CmdConnectShim
	// CmdDisconnectShim unregisters a shim. DisconnectShim is a bit
	// special and doesn't send a Response back but closes the connection.
	CmdDisconnectShim
	// CmdSignal sends a signal to the process inside the VM. A client
	// needs to be connected as a shim before it can issue that command.
	CmdSignal
	// CmdMax is the number of commands.
	CmdMax
)

func (t Command) String() string

type ConnectShim ¶

type ConnectShim struct {
	// Token is id corresponding to the process the shim wants to handle
	// the I/O streams, signals, exit status for. Tokens are allocated with
	// a call to RegisterVM or AttachVM.
	Token string `json:"token"`
}

ConnectShim identifies a shim against the proxy. A shim process is a process running on host shadowing a container process running inside the VM. A shim will forward stdin and signals to the process inside the VM and will receive stdout, stderr and the exit status.

type DisconnectShim ¶

type DisconnectShim struct {
}

DisconnectShim unregister a shim from the proxy.

type ErrorResponse ¶

type ErrorResponse struct {
	Message string `json:"msg"`
}

ErrorResponse is the payload send in Responses where the Error flag is set.

type Frame ¶

type Frame struct {
	Header  FrameHeader
	Payload []byte
}

Frame is the basic communication unit with the proxy.

func NewFrame(t FrameType, op int, payload []byte) *Frame

func NewFrameJSON(t FrameType, op int, payload interface{}) (*Frame, error)

func ReadFrame(r io.Reader) (*Frame, error)

type FrameHeader ¶

type FrameHeader struct {
	Version int
	// HeaderLength in the size of the header in bytes (the on-wire
	// HeaderLength is in number of 32-bits words tough).
	HeaderLength  int
	Type          FrameType
	Opcode        int
	PayloadLength int
	InError       bool
}

FrameHeader is the header of a Frame.

type FrameType ¶

type FrameType int

FrameType is the type of frame and is part of the frame header.

const (
	// TypeCommand is a command from a client to the proxy.
	TypeCommand FrameType = iota
	// TypeResponse is a command response back from the proxy to a client.
	TypeResponse
	// TypeStream is a stream of data from a client to the proxy. Streams
	// are to be forwarded onto the VM agent.
	TypeStream
	// TypeNotification is a notification sent by either the proxy or
	// clients. Notifications are one way only and do not prompt a
	// response.
	TypeNotification
	// TypeMax is the number of types.
	TypeMax
)

func (t FrameType) String() string

type Hyper ¶

type Hyper struct {
	HyperName string          `json:"hyperName"`
	Tokens    []string        `json:"tokens"`
	Data      json.RawMessage `json:"data,omitempty"`
}

The Hyper payload will forward an hyperstart command to hyperstart.

Note: the newcontainer and execmd hyperstart commands start one or more processes. When sending those commands, tokens acquired through either RegisterVM or AttachVM need to be sent along in the tokens array. The number of tokens sent has to match the number of processes to be started.

{
  "hyperName": "newcontainer",
  "tokens": [
    "bwgxfmQj9uG3YCsFHrvontwDw41CJJ76Y7qVt4Bi9wc="
  ],
  "data": {
    "id": "756535dc6e9ab9b560f84c8...",
    "rootfs": "/foo/bar",
    ...
    }
  }
}

type IOResponse ¶

type IOResponse struct {
	// URL is the URL a shim process should connect to in order to initiate
	// the I/O communication with the process inside the VM
	URL string
	// IOTokens is a array of I/O tokens of length NumIOStreams. See
	// RegisterVM for some details on I/O tokens.
	Tokens []string `json:"tokens"`
}

IOResponse is the response data in RegisterVMResponse and AttachVMResponse when the client is asking for I/O tokens from the proxy (NumIOStreams > 0).

type LogEntry ¶

type LogEntry struct {
	// Source is the source of the log entry. One of "shim" or "runtime".
	Source string `json:"source"`
	// ContainerID is the ID of the container the log entry is for (optional).
	ContainerID string `json:"containerId,omitempty"`
	// Level is the verbosity level of the log entry. One of "debug", "info", "warn"
	// or "error".
	Level string `json:"level"`
	// Message is the log message
	Message string `json:"msg"`
}

LogEntry is the payload for the StreamLog data.

type Notification ¶

type Notification int

Notification is the kind of notification being sent. In the frame header, Opcode must have one of the these values when Type is api.TypeNotification.

func (n Notification) String() string

type RegisterVM ¶

type RegisterVM struct {
	ContainerID string `json:"containerId"`
	CtlSerial   string `json:"ctlSerial"`
	IoSerial    string `json:"ioSerial"`
	Console     string `json:"console,omitempty"`
	// NumIOStreams asks for a number of I/O tokens. An I/O token
	// represents the communication between a container process inside
	// the VM and a shim process outside the VM. This communication
	// includes I/O streams (stdin, out, err) but also signals, exit
	// status, ...
	// The response frame will contain NumIOStreams I/O tokens.
	NumIOStreams int `json:"numIOStreams,omitempty"`
}

The RegisterVM payload is issued first after connecting to the proxy socket. It is used to let the proxy know about a new container on the system along with the paths go hyperstart's command and I/O channels (AF_UNIX sockets).

Console can be used to indicate the path of a socket linked to the VM console. The proxy can output this data when asked for verbose output.

{
  "containerId": "756535dc6e9ab9b560f84c8...",
  "ctlSerial": "/tmp/sh.hyper.channel.0.sock",
  "ioSerial": "/tmp/sh.hyper.channel.1.sock",
  "numIOStreams: 1
}

type RegisterVMResponse ¶

type RegisterVMResponse struct {
	// IO contains the proxy answer when asking for I/O tokens.
	IO IOResponse `json:"io,omitempty"`
}

RegisterVMResponse is the result from a successful RegisterVM.

{
  "io": {
    "url": "unix:///run/clearcontainers/proxy.sock",
    "tokens": [
      "bwgxfmQj9uG3YCsFHrvontwDw41CJJ76Y7qVt4Bi9wc="
    ]
  }
}

type Request ¶

type Request struct {
	ID   string          `json:"id"`
	Data json.RawMessage `json:"data,omitempty"`
}

A Request is a JSON message sent from a client to the proxy. This message embed a payload identified by "id". A payload can have data associated with it. It's useful to think of Request as an RPC call with "id" as function name and "data" as arguments.

The list of possible payloads are documented in this package.

Each Request has a corresponding Response message sent back from the proxy.

type Response ¶

type Response struct {
	Success bool                   `json:"success"`
	Error   string                 `json:"error,omitempty"`
	Data    map[string]interface{} `json:"data,omitempty"`
}

A Response is a JSON message sent back from the proxy to a client after a Request has been issued. The Response holds the result of the Request, including its success state and optional data. It's useful to think of Response as the result of an RPC call with ("success", "error") describing if the call has been successful and "data" holding the optional results.

type Signal ¶

type Signal struct {
	SignalNumber int `json:"signalNumber"`
	// Columns is only valid for SIGWINCH and is the new number of columns of
	// the terminal.
	Columns int `json:"columns,omitempty"`
	// Rows is only valid for SIGWINCH and is the new number of rows of the
	// terminal.
	Rows int `json:"rows,omitempty"`
}

Signal is used to send signals to the container process inside the VM. This payload is only valid after a successful ConnectShim.

type Stream ¶

type Stream int

Stream is the kind of stream being sent. In the frame header, Opcode must have one of the these values when Type is api.TypeStream.

const (
	// StreamStdin is a stream conveying stdin data.
	StreamStdin Stream = iota
	// StreamStdout is a stream conveying stdout data.
	StreamStdout
	// StreamStderr is a stream conveying stderr data.
	StreamStderr
	// StreamLog is a stream conveying structured logs messages. Each Log frame
	// contains a JSON object which fields are the structured log. By convention
	// it would be nice to have a few common fields in log entries to ease
	// post-processing. See the LogEntry payload for details.
	StreamLog
	// StreamMax is the number of stream types.
	StreamMax
)

func (s Stream) String() string

type UnregisterVM ¶

type UnregisterVM struct {
	ContainerID string `json:"containerId"`
}

The UnregisterVM payload does the opposite of what RegisterVM does, indicating to the proxy it should release resources created by RegisterVM for the container identified by containerId.

{
  "containerId": "756535dc6e9ab9b560f84c8..."
}