# Protocol Documentation

## Table of Contents

- [api.proto](#api.proto)
    - [App](#v1alpha.App)
    - [Event](#v1alpha.Event)
    - [EventFilter](#v1alpha.EventFilter)
    - [GetInfoRequest](#v1alpha.GetInfoRequest)
    - [GetInfoResponse](#v1alpha.GetInfoResponse)
    - [GetLogsRequest](#v1alpha.GetLogsRequest)
    - [GetLogsResponse](#v1alpha.GetLogsResponse)
    - [GlobalFlags](#v1alpha.GlobalFlags)
    - [Image](#v1alpha.Image)
    - [ImageFilter](#v1alpha.ImageFilter)
    - [ImageFormat](#v1alpha.ImageFormat)
    - [Info](#v1alpha.Info)
    - [InspectImageRequest](#v1alpha.InspectImageRequest)
    - [InspectImageResponse](#v1alpha.InspectImageResponse)
    - [InspectPodRequest](#v1alpha.InspectPodRequest)
    - [InspectPodResponse](#v1alpha.InspectPodResponse)
    - [KeyValue](#v1alpha.KeyValue)
    - [ListImagesRequest](#v1alpha.ListImagesRequest)
    - [ListImagesResponse](#v1alpha.ListImagesResponse)
    - [ListPodsRequest](#v1alpha.ListPodsRequest)
    - [ListPodsResponse](#v1alpha.ListPodsResponse)
    - [ListenEventsRequest](#v1alpha.ListenEventsRequest)
    - [ListenEventsResponse](#v1alpha.ListenEventsResponse)
    - [Network](#v1alpha.Network)
    - [Pod](#v1alpha.Pod)
    - [PodFilter](#v1alpha.PodFilter)
  
    - [AppState](#v1alpha.AppState)
    - [EventType](#v1alpha.EventType)
    - [ImageType](#v1alpha.ImageType)
    - [PodState](#v1alpha.PodState)
  
  
    - [PublicAPI](#v1alpha.PublicAPI)
  

- [Scalar Value Types](#scalar-value-types)

Top

## api.proto

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

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| name | [string](#string) |  | Name of the app, required. |
| image | [Image](#v1alpha.Image) |  | Image used by the app, required. However, this may only contain the image id if it is returned by ListPods(). |
| state | [AppState](#v1alpha.AppState) |  | State of the app. optional, non-empty only if it's returned by InspectPod(). |
| exit_code | [sint32](#sint32) |  | Exit code of the app. optional, only valid if it's returned by InspectPod() and the app has already exited. |
| annotations | [KeyValue](#v1alpha.KeyValue) | repeated | Annotations for this app. |

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

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [EventType](#v1alpha.EventType) |  | Type of the event, required. |
| id | [string](#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](#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](#int64) |  | Timestamp of when the event happens, it is the seconds since epoch, required. |
| data | [KeyValue](#v1alpha.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](#v1alpha.EventType) | repeated | If not empty, then only returns the events that have the listed types. |
| ids | [string](#string) | repeated | If not empty, then only returns the events whose 'id' is included in the listed ids. |
| names | [string](#string) | repeated | If not empty, then only returns the events whose 'from' is included in the listed names. |
| since_time | [int64](#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](#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](#v1alpha.Info) |  | Required. |

### GetLogsRequest
Request for GetLogs().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| pod_id | [string](#string) |  | ID of the pod which we will get logs from, required. |
| app_name | [string](#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](#int32) |  | Number of most recent lines to return, optional. |
| follow | [bool](#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](#int64) |  | If set, then only the logs after the timestamp will be returned, optional. |
| until_time | [int64](#int64) |  | If set, then only the logs before the timestamp will be returned, optional. |

### GetLogsResponse
Response for GetLogs().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| lines | [string](#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](#string) |  | Data directory. |
| system_config_dir | [string](#string) |  | System configuration directory. |
| local_config_dir | [string](#string) |  | Local configuration directory. |
| user_config_dir | [string](#string) |  | User configuration directory. |
| insecure_flags | [string](#string) |  | Insecure flags configurates what security features to disable. |
| trust_keys_from_https | [bool](#bool) |  | Whether to automatically trust gpg keys fetched from https |

### Image
Image describes the image's information.

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| base_format | [ImageFormat](#v1alpha.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](#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](#string) |  | Name of the image in the image manifest, e.g. 'coreos.com/etcd', optional. |
| version | [string](#string) |  | Version of the image, e.g. 'latest', '2.0.10', optional. |
| import_timestamp | [int64](#int64) |  | Timestamp of when the image is imported, it is the seconds since epoch, optional. |
| manifest | [bytes](#bytes) |  | JSON-encoded byte array that represents the image manifest, optional. |
| size | [int64](#int64) |  | Size is the size in bytes of this image in the store. |
| annotations | [KeyValue](#v1alpha.KeyValue) | repeated | Annotations on this image. |
| labels | [KeyValue](#v1alpha.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](#string) | repeated | If not empty, the images that have any of the ids will be returned. |
| prefixes | [string](#string) | repeated | if not empty, the images that have any of the prefixes in the name will be returned. |
| base_names | [string](#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](#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](#v1alpha.KeyValue) | repeated | If not empty, the images that have all of the labels will be returned. |
| imported_after | [int64](#int64) |  | If set, the images that are imported after this timestamp will be returned. |
| imported_before | [int64](#int64) |  | If set, the images that are imported before this timestamp will be returned. |
| annotations | [KeyValue](#v1alpha.KeyValue) | repeated | If not empty, the images that have all of the annotations will be returned. |
| full_names | [string](#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](#v1alpha.ImageType) |  | Type of the image, required. |
| version | [string](#string) |  | Version of the image format, required. |

### Info
Info describes the information of rkt on the machine.

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| rkt_version | [string](#string) |  | Version of rkt, required, in the form of Semantic Versioning 2.0.0 (http://semver.org/). |
| appc_version | [string](#string) |  | Version of appc, required, in the form of Semantic Versioning 2.0.0 (http://semver.org/). |
| api_version | [string](#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](#v1alpha.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](#string) |  | Required. |

### InspectImageResponse
Response for InspectImage().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| image | [Image](#v1alpha.Image) |  | Required. |

### InspectPodRequest
Request for InspectPod().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | [string](#string) |  | ID of the pod which we are querying status for, required. |

### InspectPodResponse
Response for InspectPod().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| pod | [Pod](#v1alpha.Pod) |  | Required. |

### KeyValue

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| Key | [string](#string) |  | Key part of the key-value pair. |
| value | [string](#string) |  | Value part of the key-value pair. |

### ListImagesRequest
Request for ListImages().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| filters | [ImageFilter](#v1alpha.ImageFilter) | repeated | Optional. |
| detail | [bool](#bool) |  | Optional. |

### ListImagesResponse
Response for ListImages().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| images | [Image](#v1alpha.Image) | repeated | Required. |

### ListPodsRequest
Request for ListPods().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| filters | [PodFilter](#v1alpha.PodFilter) | repeated | Optional. |
| detail | [bool](#bool) |  | Optional. |

### ListPodsResponse
Response for ListPods().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| pods | [Pod](#v1alpha.Pod) | repeated | Required. |

### ListenEventsRequest
Request for ListenEvents().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| filter | [EventFilter](#v1alpha.EventFilter) |  | Optional. |

### ListenEventsResponse
Response for ListenEvents().

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| events | [Event](#v1alpha.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](#string) |  | Name of the network that a pod belongs to, required. |
| ipv4 | [string](#string) |  | Pod's IPv4 address within the network, optional if IPv6 address is given. |
| ipv6 | [string](#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](#string) |  | ID of the pod, in the form of a UUID. |
| pid | [sint32](#sint32) |  | PID of the stage1 process of the pod. |
| state | [PodState](#v1alpha.PodState) |  | State of the pod. |
| apps | [App](#v1alpha.App) | repeated | List of apps in the pod. |
| networks | [Network](#v1alpha.Network) | repeated | Network information of the pod. Note that a pod can be in multiple networks. |
| manifest | [bytes](#bytes) |  | JSON-encoded byte array that represents the pod manifest of the pod. |
| annotations | [KeyValue](#v1alpha.KeyValue) | repeated | Annotations on this pod. |
| cgroup | [string](#string) |  | Cgroup of the pod, empty if the pod is not running. |
| created_at | [int64](#int64) |  | Timestamp of when the pod is created, nanoseconds since epoch. Zero if the pod is not created. |
| started_at | [int64](#int64) |  | Timestamp of when the pod is started, nanoseconds since epoch. Zero if the pod is not started. |
| gc_marked_at | [int64](#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](#string) | repeated | If not empty, the pods that have any of the ids will be returned. |
| states | [PodState](#v1alpha.PodState) | repeated | If not empty, the pods that have any of the states will be returned. |
| app_names | [string](#string) | repeated | If not empty, the pods that all of the apps will be returned. |
| image_ids | [string](#string) | repeated | If not empty, the pods that have all of the images(in the apps) will be returned |
| network_names | [string](#string) | repeated | If not empty, the pods that are in all of the networks will be returned. |
| annotations | [KeyValue](#v1alpha.KeyValue) | repeated | If not empty, the pods that have all of the annotations will be returned. |
| cgroups | [string](#string) | repeated | If not empty, the pods whose cgroup are listed will be returned. |
| pod_sub_cgroups | [string](#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](#v1alpha.GetInfoRequest) | [GetInfoResponse](#v1alpha.GetInfoRequest) | GetInfo gets the rkt's information on the machine. |
| ListPods | [ListPodsRequest](#v1alpha.ListPodsRequest) | [ListPodsResponse](#v1alpha.ListPodsRequest) | ListPods lists rkt pods on the machine. |
| InspectPod | [InspectPodRequest](#v1alpha.InspectPodRequest) | [InspectPodResponse](#v1alpha.InspectPodRequest) | InspectPod gets detailed pod information of the specified pod. |
| ListImages | [ListImagesRequest](#v1alpha.ListImagesRequest) | [ListImagesResponse](#v1alpha.ListImagesRequest) | ListImages lists the images on the machine. |
| InspectImage | [InspectImageRequest](#v1alpha.InspectImageRequest) | [InspectImageResponse](#v1alpha.InspectImageRequest) | InspectImage gets the detailed image information of the specified image. |
| ListenEvents | [ListenEventsRequest](#v1alpha.ListenEventsRequest) | [ListenEventsResponse](#v1alpha.ListenEventsRequest) | ListenEvents listens for the events, it will return a response stream that will contain event objects. |
| GetLogs | [GetLogsRequest](#v1alpha.GetLogsRequest) | [GetLogsResponse](#v1alpha.GetLogsRequest) | 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 |

