# Protocol Documentation

## Table of Contents

## api.proto

Top

### App

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

Field | Type | Label | Description
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().

Field | Type | Label | Description
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'.

Field | Type | Label | Description
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().

Field | Type | Label | Description
info | Info |  | Required.

### GetLogsRequest

Request for GetLogs().

Field | Type | Label | Description
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().

Field | Type | Label | Description
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.

Field | Type | Label | Description
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.

Field | Type | Label | Description
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'.

Field | Type | Label | Description
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.

Field | Type | Label | Description
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.

Field | Type | Label | Description
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().

Field | Type | Label | Description
id | string |  | Required.

### InspectImageResponse

Response for InspectImage().

Field | Type | Label | Description
image | Image |  | Required.

### InspectPodRequest

Request for InspectPod().

Field | Type | Label | Description
id | string |  | ID of the pod which we are querying status for, required.

### InspectPodResponse

Response for InspectPod().

Field | Type | Label | Description
pod | Pod |  | Required.

### KeyValue

Field | Type | Label | Description
Key | string |  | Key part of the key-value pair.
value | string |  | Value part of the key-value pair.

### ListImagesRequest

Request for ListImages().

Field | Type | Label | Description
filters | ImageFilter | repeated | Optional.
detail | bool |  | Optional.

### ListImagesResponse

Response for ListImages().

Field | Type | Label | Description
images | Image | repeated | Required.

### ListPodsRequest

Request for ListPods().

Field | Type | Label | Description
filters | PodFilter | repeated | Optional.
detail | bool |  | Optional.

### ListPodsResponse

Response for ListPods().

Field | Type | Label | Description
pods | Pod | repeated | Required.

### ListenEventsRequest

Request for ListenEvents().

Field | Type | Label | Description
filter | EventFilter |  | Optional.

### ListenEventsResponse

Response for ListenEvents().

Field | Type | Label | Description
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.

Field | Type | Label | Description
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.

Field | Type | Label | Description
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'.

Field | Type | Label | Description
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.

Name | Number | Description
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().

Name | Number | Description
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.

Name | Number | Description
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.

Name | Number | Description
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 Name | Request Type | Response Type | Description
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 Type | Notes | C++ Type | Java Type | Python 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