Protocol Documentation

Table of Contents

api.proto

Top

App

App describes the information of an app that's running in a pod.

FieldTypeLabelDescription
name string

Name of the app, required.

image Image

Image used by the app, required. However, this may only contain the image id if it is returned by ListPods().

state AppState

State of the app. optional, non-empty only if it's returned by InspectPod().

exit_code sint32

Exit code of the app. optional, only valid if it's returned by InspectPod() and the app has already exited.

annotations KeyValue repeated

Annotations for this app.

Event

Event describes the events that will be received via ListenEvents().

FieldTypeLabelDescription
type EventType

Type of the event, required.

id string

ID of the subject that causes the event, required. If the event is a pod or app event, the id is the pod's uuid. If the event is an image event, the id is the image's id.

from string

Name of the subject that causes the event, required. If the event is a pod event, the name is the pod's name. If the event is an app event, the name is the app's name. If the event is an image event, the name is the image's name.

time int64

Timestamp of when the event happens, it is the seconds since epoch, required.

data KeyValue repeated

Data of the event, in the form of key-value pairs, optional.

EventFilter

EventFilter defines the condition that the returned events needs to satisfy in ListImages().

The condition are combined by 'AND'.

FieldTypeLabelDescription
types EventType repeated

If not empty, then only returns the events that have the listed types.

ids string repeated

If not empty, then only returns the events whose 'id' is included in the listed ids.

names string repeated

If not empty, then only returns the events whose 'from' is included in the listed names.

since_time int64

If set, then only returns the events after this timestamp. If the server starts after since_time, then only the events happened after the start of the server will be returned. If since_time is a future timestamp, then no events will be returned until that time.

until_time int64

If set, then only returns the events before this timestamp. If it is a future timestamp, then the event stream will be closed at that moment.

GetInfoRequest

Request for GetInfo().

GetInfoResponse

Response for GetInfo().

FieldTypeLabelDescription
info Info

Required.

GetLogsRequest

Request for GetLogs().

FieldTypeLabelDescription
pod_id string

ID of the pod which we will get logs from, required.

app_name string

Name of the app within the pod which we will get logs from, optional. If not set, then the logs of all the apps within the pod will be returned.

lines int32

Number of most recent lines to return, optional.

follow bool

If true, then a response stream will not be closed, and new log response will be sent via the stream, default is false.

since_time int64

If set, then only the logs after the timestamp will be returned, optional.

until_time int64

If set, then only the logs before the timestamp will be returned, optional.

GetLogsResponse

Response for GetLogs().

FieldTypeLabelDescription
lines string repeated

List of the log lines that returned, optional as the response can contain no logs.

GlobalFlags

GlobalFlags describes the flags that passed to rkt api service when it is launched.

FieldTypeLabelDescription
dir string

Data directory.

system_config_dir string

System configuration directory.

local_config_dir string

Local configuration directory.

user_config_dir string

User configuration directory.

insecure_flags string

Insecure flags configurates what security features to disable.

trust_keys_from_https bool

Whether to automatically trust gpg keys fetched from https

Image

Image describes the image's information.

FieldTypeLabelDescription
base_format ImageFormat

Base format of the image, required. This indicates the original format for the image as nowadays all the image formats will be transformed to ACI.

id string

ID of the image, a string that can be used to uniquely identify the image, e.g. sha512 hash of the ACIs, required.

name string

Name of the image in the image manifest, e.g. 'coreos.com/etcd', optional.

version string

Version of the image, e.g. 'latest', '2.0.10', optional.

import_timestamp int64

Timestamp of when the image is imported, it is the seconds since epoch, optional.

manifest bytes

JSON-encoded byte array that represents the image manifest, optional.

size int64

Size is the size in bytes of this image in the store.

annotations KeyValue repeated

Annotations on this image.

labels KeyValue repeated

Labels of this image.

ImageFilter

ImageFilter defines the condition that the returned images need to satisfy in ListImages().

The conditions are combined by 'AND', and different filters are combined by 'OR'.

FieldTypeLabelDescription
ids string repeated

If not empty, the images that have any of the ids will be returned.

prefixes string repeated

if not empty, the images that have any of the prefixes in the name will be returned.

base_names string repeated

If not empty, the images that have any of the base names will be returned. For example, both 'coreos.com/etcd' and 'k8s.io/etcd' will be returned if 'etcd' is included, however 'k8s.io/etcd-backup' will not be returned.

keywords string repeated

If not empty, the images that have any of the keywords in the name will be returned. For example, both 'kubernetes-etcd', 'etcd:latest' will be returned if 'etcd' is included,

labels KeyValue repeated

If not empty, the images that have all of the labels will be returned.

imported_after int64

If set, the images that are imported after this timestamp will be returned.

imported_before int64

If set, the images that are imported before this timestamp will be returned.

annotations KeyValue repeated

If not empty, the images that have all of the annotations will be returned.

full_names string repeated

If not empty, the images that have any of the exact full names will be returned.

ImageFormat

ImageFormat defines the format of the image.

FieldTypeLabelDescription
type ImageType

Type of the image, required.

version string

Version of the image format, required.

Info

Info describes the information of rkt on the machine.

FieldTypeLabelDescription
rkt_version string

Version of rkt, required, in the form of Semantic Versioning 2.0.0 (http://semver.org/).

appc_version string

Version of appc, required, in the form of Semantic Versioning 2.0.0 (http://semver.org/).

api_version string

Latest version of the api that's supported by the service, required, in the form of Semantic Versioning 2.0.0 (http://semver.org/).

global_flags GlobalFlags

The global flags that passed to the rkt api service when it's launched.

InspectImageRequest

Request for InspectImage().

FieldTypeLabelDescription
id string

Required.

InspectImageResponse

Response for InspectImage().

FieldTypeLabelDescription
image Image

Required.

InspectPodRequest

Request for InspectPod().

FieldTypeLabelDescription
id string

ID of the pod which we are querying status for, required.

InspectPodResponse

Response for InspectPod().

FieldTypeLabelDescription
pod Pod

Required.

KeyValue

FieldTypeLabelDescription
Key string

Key part of the key-value pair.

value string

Value part of the key-value pair.

ListImagesRequest

Request for ListImages().

FieldTypeLabelDescription
filters ImageFilter repeated

Optional.

detail bool

Optional.

ListImagesResponse

Response for ListImages().

FieldTypeLabelDescription
images Image repeated

Required.

ListPodsRequest

Request for ListPods().

FieldTypeLabelDescription
filters PodFilter repeated

Optional.

detail bool

Optional.

ListPodsResponse

Response for ListPods().

FieldTypeLabelDescription
pods Pod repeated

Required.

ListenEventsRequest

Request for ListenEvents().

FieldTypeLabelDescription
filter EventFilter

Optional.

ListenEventsResponse

Response for ListenEvents().

FieldTypeLabelDescription
events Event repeated

Aggregate multiple events to reduce round trips, optional as the response can contain no events.

Network

Network describes the network information of a pod.

FieldTypeLabelDescription
name string

Name of the network that a pod belongs to, required.

ipv4 string

Pod's IPv4 address within the network, optional if IPv6 address is given.

ipv6 string

Pod's IPv6 address within the network, optional if IPv4 address is given.

Pod

Pod describes a pod's information.

If a pod is in Embryo, Preparing, AbortedPrepare state,

only id and state will be returned.

If a pod is in other states, the pod manifest and

apps will be returned when 'detailed' is true in the request.

A valid pid of the stage1 process of the pod will be returned

if the pod is Running has run once.

Networks are only returned when a pod is in Running.

FieldTypeLabelDescription
id string

ID of the pod, in the form of a UUID.

pid sint32

PID of the stage1 process of the pod.

state PodState

State of the pod.

apps App repeated

List of apps in the pod.

networks Network repeated

Network information of the pod. Note that a pod can be in multiple networks.

manifest bytes

JSON-encoded byte array that represents the pod manifest of the pod.

annotations KeyValue repeated

Annotations on this pod.

cgroup string

Cgroup of the pod, empty if the pod is not running.

created_at int64

Timestamp of when the pod is created, nanoseconds since epoch. Zero if the pod is not created.

started_at int64

Timestamp of when the pod is started, nanoseconds since epoch. Zero if the pod is not started.

gc_marked_at int64

Timestamp of when the pod is moved to exited-garbage/garbage, in nanoseconds since epoch. Zero if the pod is not moved to exited-garbage/garbage yet.

PodFilter

PodFilter defines the condition that the returned pods need to satisfy in ListPods().

The conditions are combined by 'AND', and different filters are combined by 'OR'.

FieldTypeLabelDescription
ids string repeated

If not empty, the pods that have any of the ids will be returned.

states PodState repeated

If not empty, the pods that have any of the states will be returned.

app_names string repeated

If not empty, the pods that all of the apps will be returned.

image_ids string repeated

If not empty, the pods that have all of the images(in the apps) will be returned

network_names string repeated

If not empty, the pods that are in all of the networks will be returned.

annotations KeyValue repeated

If not empty, the pods that have all of the annotations will be returned.

cgroups string repeated

If not empty, the pods whose cgroup are listed will be returned.

pod_sub_cgroups string repeated

If not empty, the pods whose these cgroup belong to will be returned. i.e. the pod's cgroup is a prefix of the specified cgroup

AppState

AppState defines the possible states of the app.

NameNumberDescription
APP_STATE_UNDEFINED 0

APP_STATE_RUNNING 1

APP_STATE_EXITED 2

EventType

EventType defines the type of the events that will be received via ListenEvents().

NameNumberDescription
EVENT_TYPE_UNDEFINED 0

EVENT_TYPE_POD_PREPARED 1

Pod events.

EVENT_TYPE_POD_PREPARE_ABORTED 2

EVENT_TYPE_POD_STARTED 3

EVENT_TYPE_POD_EXITED 4

EVENT_TYPE_POD_GARBAGE_COLLECTED 5

EVENT_TYPE_APP_STARTED 6

App events.

EVENT_TYPE_APP_EXITED 7

(XXX)yifan: Maybe also return exit code in the event object?

EVENT_TYPE_IMAGE_IMPORTED 8

Image events.

EVENT_TYPE_IMAGE_REMOVED 9

ImageType

ImageType defines the supported image type.

NameNumberDescription
IMAGE_TYPE_UNDEFINED 0

IMAGE_TYPE_APPC 1

IMAGE_TYPE_DOCKER 2

IMAGE_TYPE_OCI 3

PodState

PodState defines the possible states of the pod.

See https://github.com/rkt/rkt/blob/master/Documentation/devel/pod-lifecycle.md for a detailed

explanation of each state.

NameNumberDescription
POD_STATE_UNDEFINED 0

POD_STATE_EMBRYO 1

States before the pod is running. Pod is created, ready to entering 'preparing' state.

POD_STATE_PREPARING 2

Pod is being prepared. On success it will become 'prepared', otherwise it will become 'aborted prepared'.

POD_STATE_PREPARED 3

Pod has been successfully prepared, ready to enter 'running' state. it can also enter 'deleting' if it's garbage collected before running.

POD_STATE_RUNNING 4

State that indicates the pod is running. Pod is running, when it exits, it will become 'exited'.

POD_STATE_ABORTED_PREPARE 5

States that indicates the pod is exited, and will never run. Pod failed to prepare, it will only be garbage collected and will never run again.

POD_STATE_EXITED 6

Pod has exited, it now can be garbage collected.

POD_STATE_DELETING 7

Pod is being garbage collected, after that it will enter 'garbage' state.

POD_STATE_GARBAGE 8

Pod is marked as garbage collected, it no longer exists on the machine.

PublicAPI

PublicAPI defines the read-only APIs that will be supported.

These will be handled over TCP sockets.

Method NameRequest TypeResponse TypeDescription
GetInfo GetInfoRequest GetInfoResponse

GetInfo gets the rkt's information on the machine.

ListPods ListPodsRequest ListPodsResponse

ListPods lists rkt pods on the machine.

InspectPod InspectPodRequest InspectPodResponse

InspectPod gets detailed pod information of the specified pod.

ListImages ListImagesRequest ListImagesResponse

ListImages lists the images on the machine.

InspectImage InspectImageRequest InspectImageResponse

InspectImage gets the detailed image information of the specified image.

ListenEvents ListenEventsRequest ListenEventsResponse

ListenEvents listens for the events, it will return a response stream that will contain event objects.

GetLogs GetLogsRequest GetLogsResponse

GetLogs gets the logs for a pod, if the app is also specified, then only the logs of the app will be returned. If 'follow' in the 'GetLogsRequest' is set to 'true', then the response stream will not be closed after the first response, the future logs will be sent via the stream.

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str