Understanding the applications.edgelq.com service APIv1, in proto package ntt.applications.v1.

Service applications.edgelq.com in version v1, proto package ntt.applications.v1

Here is the list of resources supported in Applications service APIv1:

ConfigMap Resource

ConfigMap Resource

Name patterns:

  • projects/{project}/regions/{region}/configMaps/{config_map}

Parent resources:

This section covers the methods and messages to interact with ConfigMap resource.

ConfigMap Methods

Here is the list of ConfigMap resource methods:

GetConfigMap Method

GetConfigMap

rpc GetConfigMap(GetConfigMapRequest) returns (ConfigMap)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.get

The equivalent REST API is:

GET /v1/{name=projects/*/regions/*/configMaps/*}

BatchGetConfigMaps Method

BatchGetConfigMaps

rpc BatchGetConfigMaps(BatchGetConfigMapsRequest) returns (BatchGetConfigMapsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.batchGet

The equivalent REST API is:

GET /v1/configMaps:batchGet

ListConfigMaps Method

ListConfigMaps

rpc ListConfigMaps(ListConfigMapsRequest) returns (ListConfigMapsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.list

The equivalent REST API is:

GET /v1/{parent=projects/*/regions/*}/configMaps

WatchConfigMap Method

WatchConfigMap

rpc WatchConfigMap(WatchConfigMapRequest) returns (WatchConfigMapResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.watch

The equivalent REST API is:

POST /v1/{name=projects/*/regions/*/configMaps/*}:watch

WatchConfigMaps Method

WatchConfigMaps

rpc WatchConfigMaps(WatchConfigMapsRequest) returns (WatchConfigMapsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.watch

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/configMaps:watch

CreateConfigMap Method

CreateConfigMap

rpc CreateConfigMap(CreateConfigMapRequest) returns (ConfigMap)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.create

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/configMaps (BODY: config_map)

UpdateConfigMap Method

UpdateConfigMap

rpc UpdateConfigMap(UpdateConfigMapRequest) returns (ConfigMap)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.update

The equivalent REST API is:

PUT /v1/{config_map.name=projects/*/regions/*/configMaps/*} (BODY: config_map)

DeleteConfigMap Method

DeleteConfigMap

rpc DeleteConfigMap(DeleteConfigMapRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/configMaps.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/regions/*/configMaps/*}

ConfigMap Messages

Here is the list of ConfigMap resource messages:

ConfigMap Message

Name Type Description
name string (name of ConfigMap) Name of ConfigMap When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
display_name string Display name of ConfigMap
description string Optional. Description of the ConfigMap.
data map<string, string> Data contains the configuration data. Each key must consist of alphanumeric characters, ‘-’, ‘_’ or ‘.’. Values with non-UTF-8 byte sequences must use the BinaryData field. The keys stored in Data must not overlap with the keys in the BinaryData field, this is enforced during validation process. +optional
binary_data map<string, bytes> BinaryData contains the binary data. Each key must consist of alphanumeric characters, ‘-’, ‘_’ or ‘.’. BinaryData can contain byte sequences that are not in the UTF-8 range. The keys stored in BinaryData must not overlap with the ones in the Data field, this is enforced during validation process. Using this field will require 1.10+ apiserver and kubelet. +optional

GetConfigMapRequest Message

A request message of the GetConfigMap method.

Name Type Description
name string (name of ConfigMap) Name of ntt.applications.v1.ConfigMap
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConfigMapsRequest Message

A request message of the BatchGetConfigMaps method.

Name Type Description
names repeated string (name of ConfigMap) Names of ConfigMaps
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetConfigMapsResponse Message

A response message of the BatchGetConfigMaps method.

Name Type Description
config_maps repeated ConfigMap found ConfigMaps
missing repeated string (name of ConfigMap) list of not found ConfigMaps

ListConfigMapsRequest Message

A request message of the ListConfigMaps method.

Name Type Description
parent string (parent name of ConfigMap) Parent name of ntt.applications.v1.ConfigMap
page_size int32 Requested page size. Server may return fewer ConfigMaps than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of ConfigMap) A token identifying a page of results the server should return. Typically, this is the value of ListConfigMapsResponse.next_page_token.
order_by string (orderBy of ConfigMap) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of ConfigMap) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListConfigMapsResponse Message

A response message of the ListConfigMaps method.

Name Type Description
config_maps repeated ConfigMap The list of ConfigMaps
prev_page_token string (cursor of ConfigMap) A token to retrieve previous page of results. Pass this value in the ListConfigMapsRequest.page_token.
next_page_token string (cursor of ConfigMap) A token to retrieve next page of results. Pass this value in the ListConfigMapsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total ConfigMaps across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchConfigMapRequest Message

A request message of the WatchConfigMap method.

Name Type Description
name string (name of ConfigMap) Name of ntt.applications.v1.ConfigMap
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchConfigMapResponse Message

A response message of the WatchConfigMap method.

Name Type Description
change ConfigMapChange

WatchConfigMapsRequest Message

A request message of the WatchConfigMaps method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of ConfigMap) Parent name of ntt.applications.v1.ConfigMap
page_size int32 Requested page size. Server may return fewer ConfigMaps than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of ConfigMap) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of ConfigMap) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of ConfigMap) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to ConfigMap that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to ConfigMap that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchConfigMapsResponse Message

A response message of the WatchConfigMaps method.

Name Type Description
config_map_changes repeated ConfigMapChange Changes of ConfigMaps
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All ConfigMaps will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchConfigMapsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (ConfigMaps will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchConfigMapsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of ConfigMap) New token to retrieve previous page of results.
next_page_token string (cursor of ConfigMap) New token to retrieve next page of results.

CreateConfigMapRequest Message

A request message of the CreateConfigMap method.

Name Type Description
parent string (parent name of ConfigMap) Parent name of ntt.applications.v1.ConfigMap
config_map ConfigMap ConfigMap resource body
response_mask CreateConfigMapRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateConfigMapRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateConfigMapRequest Message

A request message of the UpdateConfigMap method.

Name Type Description
config_map ConfigMap ConfigMap resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateConfigMapRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateConfigMapRequest.ResponseMask reduce message response size.

UpdateConfigMapRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state ConfigMap Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateConfigMapRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteConfigMapRequest Message

A request message of the DeleteConfigMap method.

Name Type Description
name string (name of ConfigMap) Name of ntt.applications.v1.ConfigMap

Distribution Resource

Distribution Resource

Name patterns:

  • projects/{project}/distributions/{distribution}

Parent resources:

This section covers the methods and messages to interact with Distribution resource.

Distribution Methods

Here is the list of Distribution resource methods:

GetDistribution Method

GetDistribution

rpc GetDistribution(GetDistributionRequest) returns (Distribution)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.get

The equivalent REST API is:

GET /v1/{name=projects/*/distributions/*}

BatchGetDistributions Method

BatchGetDistributions

rpc BatchGetDistributions(BatchGetDistributionsRequest) returns (BatchGetDistributionsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.batchGet

The equivalent REST API is:

GET /v1/distributions:batchGet

ListDistributions Method

ListDistributions

rpc ListDistributions(ListDistributionsRequest) returns (ListDistributionsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.list

The equivalent REST API is:

GET /v1/{parent=projects/*}/distributions

WatchDistribution Method

WatchDistribution

rpc WatchDistribution(WatchDistributionRequest) returns (WatchDistributionResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.watch

The equivalent REST API is:

POST /v1/{name=projects/*/distributions/*}:watch

WatchDistributions Method

WatchDistributions

rpc WatchDistributions(WatchDistributionsRequest) returns (WatchDistributionsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.watch

The equivalent REST API is:

POST /v1/{parent=projects/*}/distributions:watch

CreateDistribution Method

CreateDistribution

rpc CreateDistribution(CreateDistributionRequest) returns (Distribution)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.create

The equivalent REST API is:

POST /v1/{parent=projects/*}/distributions (BODY: distribution)

UpdateDistribution Method

UpdateDistribution

rpc UpdateDistribution(UpdateDistributionRequest) returns (Distribution)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.update

The equivalent REST API is:

PUT /v1/{distribution.name=projects/*/distributions/*} (BODY: distribution)

DeleteDistribution Method

DeleteDistribution

rpc DeleteDistribution(DeleteDistributionRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/distributions.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/distributions/*}

Distribution Messages

Here is the list of Distribution resource messages:

Distribution Message

Name Type Description
name string (name of Distribution) Name of Distribution When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
display_name string Display name of Distribution
description string Optional. Description of the Distribution.
spec Distribution.Spec
status Distribution.Status

Distribution.Spec Message

Spec defines the configuration of a Distribution

Name Type Description
selector LabelSelector
template Distribution.Spec.Template template defines the probing config to be distributed.
pod_display_name_format string Template for distribution name.

Distribution.Status Message

Name Type Description
none none none

Distribution.Spec.Template Message

Name Type Description
metadata Meta
spec PodSpec

GetDistributionRequest Message

A request message of the GetDistribution method.

Name Type Description
name string (name of Distribution) Name of ntt.applications.v1.Distribution
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetDistributionsRequest Message

A request message of the BatchGetDistributions method.

Name Type Description
names repeated string (name of Distribution) Names of Distributions
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetDistributionsResponse Message

A response message of the BatchGetDistributions method.

Name Type Description
distributions repeated Distribution found Distributions
missing repeated string (name of Distribution) list of not found Distributions

ListDistributionsRequest Message

A request message of the ListDistributions method.

Name Type Description
parent string (parent name of Distribution) Parent name of ntt.applications.v1.Distribution
page_size int32 Requested page size. Server may return fewer Distributions than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Distribution) A token identifying a page of results the server should return. Typically, this is the value of ListDistributionsResponse.next_page_token.
order_by string (orderBy of Distribution) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Distribution) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListDistributionsResponse Message

A response message of the ListDistributions method.

Name Type Description
distributions repeated Distribution The list of Distributions
prev_page_token string (cursor of Distribution) A token to retrieve previous page of results. Pass this value in the ListDistributionsRequest.page_token.
next_page_token string (cursor of Distribution) A token to retrieve next page of results. Pass this value in the ListDistributionsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Distributions across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchDistributionRequest Message

A request message of the WatchDistribution method.

Name Type Description
name string (name of Distribution) Name of ntt.applications.v1.Distribution
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchDistributionResponse Message

A response message of the WatchDistribution method.

Name Type Description
change DistributionChange

WatchDistributionsRequest Message

A request message of the WatchDistributions method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of Distribution) Parent name of ntt.applications.v1.Distribution
page_size int32 Requested page size. Server may return fewer Distributions than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Distribution) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Distribution) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Distribution) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Distribution that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Distribution that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchDistributionsResponse Message

A response message of the WatchDistributions method.

Name Type Description
distribution_changes repeated DistributionChange Changes of Distributions
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Distributions will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchDistributionsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Distributions will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchDistributionsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Distribution) New token to retrieve previous page of results.
next_page_token string (cursor of Distribution) New token to retrieve next page of results.

CreateDistributionRequest Message

A request message of the CreateDistribution method.

Name Type Description
parent string (parent name of Distribution) Parent name of ntt.applications.v1.Distribution
distribution Distribution Distribution resource body
response_mask CreateDistributionRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateDistributionRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateDistributionRequest Message

A request message of the UpdateDistribution method.

Name Type Description
distribution Distribution Distribution resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateDistributionRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateDistributionRequest.ResponseMask reduce message response size.

UpdateDistributionRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Distribution Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateDistributionRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteDistributionRequest Message

A request message of the DeleteDistribution method.

Name Type Description
name string (name of Distribution) Name of ntt.applications.v1.Distribution

Pod Resource

Pod Resource

Name patterns:

  • projects/{project}/regions/{region}/pods/{pod}

Parent resources:

This section covers the methods and messages to interact with Pod resource.

Pod Methods

Here is the list of Pod resource methods:

GetPod Method

GetPod

rpc GetPod(GetPodRequest) returns (Pod)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.get

The equivalent REST API is:

GET /v1/{name=projects/*/regions/*/pods/*}

BatchGetPods Method

BatchGetPods

rpc BatchGetPods(BatchGetPodsRequest) returns (BatchGetPodsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.batchGet

The equivalent REST API is:

GET /v1/pods:batchGet

ListPods Method

ListPods

rpc ListPods(ListPodsRequest) returns (ListPodsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.list

The equivalent REST API is:

GET /v1/{parent=projects/*/regions/*}/pods

WatchPod Method

WatchPod

rpc WatchPod(WatchPodRequest) returns (WatchPodResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.watch

The equivalent REST API is:

POST /v1/{name=projects/*/regions/*/pods/*}:watch

WatchPods Method

WatchPods

rpc WatchPods(WatchPodsRequest) returns (WatchPodsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.watch

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/pods:watch

CreatePod Method

CreatePod

rpc CreatePod(CreatePodRequest) returns (Pod)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.create

The equivalent REST API is:

POST /v1/{parent=projects/*/regions/*}/pods (BODY: pod)

UpdatePod Method

UpdatePod

rpc UpdatePod(UpdatePodRequest) returns (Pod)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.update

The equivalent REST API is:

PUT /v1/{pod.name=projects/*/regions/*/pods/*} (BODY: pod)

DeletePod Method

DeletePod

rpc DeletePod(DeletePodRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/pods.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*/regions/*/pods/*}

Pod Messages

Here is the list of Pod resource messages:

Pod Message

Name Type Description
name string (name of Pod) Name of Pod When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
display_name string Display name of Pod
description string Optional. Description of the Pod.
spec PodSpec
distribution string (reference to Distribution) Optional managing distribution.
status Pod.Status

Pod.Status Message

Status defines the status of a Pod

Name Type Description
phase Pod.Status.Phase Phase is the state of the entire Pod.
container_statuses repeated Pod.Status.Container container_statuses lists individual status of the containers.
error string Error message if Status.Phase is one of the failure phases.
failure_count int32 Some of the Pod UP errors are retried and the failure count is reported here
health_status Pod.Status.HealthStatus This is a consolidated summary of all containers health UNHEALTHY as long as one container is UNHEALTHY HEALTHY as long as atleast one container has health status

Pod.Status.Container Message

Container defines status of a Container.

Name Type Description
name string name is the name of the container
state Pod.Status.Container.State
waiting Pod.Status.Container.StateWaiting
running Pod.Status.Container.StateRunning
terminated Pod.Status.Container.StateTerminated
health_status Pod.Status.HealthStatus
service_name string service name in case of compose pod
container_ip string
container_id string

Pod.Status.Container.StateWaiting Message

Name Type Description
reason string reason explains why the container is waiting now.
message string message gives a human readable message that explains the state.

Pod.Status.Container.StateRunning Message

Name Type Description
started_at .google.protobuf.Timestamp started_at indicates when the container started at.

Pod.Status.Container.StateTerminated Message

Name Type Description
exit_code int32 exit_code is the exist code that the process returns at the end.
signal int32 signal is the signal used to kill the process.
reason string reason explains why the container is terminated.
message string message has detailed human readable message.
started_at .google.protobuf.Timestamp started_at indicates when the container started at.
finished_at .google.protobuf.Timestamp finished_at indicates when the container exited at.
container_id string containerID is the ID of the container when it was running.

GetPodRequest Message

A request message of the GetPod method.

Name Type Description
name string (name of Pod) Name of ntt.applications.v1.Pod
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetPodsRequest Message

A request message of the BatchGetPods method.

Name Type Description
names repeated string (name of Pod) Names of Pods
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetPodsResponse Message

A response message of the BatchGetPods method.

Name Type Description
pods repeated Pod found Pods
missing repeated string (name of Pod) list of not found Pods

ListPodsRequest Message

A request message of the ListPods method.

Name Type Description
parent string (parent name of Pod) Parent name of ntt.applications.v1.Pod
page_size int32 Requested page size. Server may return fewer Pods than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Pod) A token identifying a page of results the server should return. Typically, this is the value of ListPodsResponse.next_page_token.
order_by string (orderBy of Pod) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Pod) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListPodsResponse Message

A response message of the ListPods method.

Name Type Description
pods repeated Pod The list of Pods
prev_page_token string (cursor of Pod) A token to retrieve previous page of results. Pass this value in the ListPodsRequest.page_token.
next_page_token string (cursor of Pod) A token to retrieve next page of results. Pass this value in the ListPodsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Pods across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchPodRequest Message

A request message of the WatchPod method.

Name Type Description
name string (name of Pod) Name of ntt.applications.v1.Pod
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchPodResponse Message

A response message of the WatchPod method.

Name Type Description
change PodChange

WatchPodsRequest Message

A request message of the WatchPods method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of Pod) Parent name of ntt.applications.v1.Pod
page_size int32 Requested page size. Server may return fewer Pods than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Pod) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Pod) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Pod) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Pod that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Pod that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchPodsResponse Message

A response message of the WatchPods method.

Name Type Description
pod_changes repeated PodChange Changes of Pods
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Pods will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchPodsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Pods will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchPodsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Pod) New token to retrieve previous page of results.
next_page_token string (cursor of Pod) New token to retrieve next page of results.

CreatePodRequest Message

A request message of the CreatePod method.

Name Type Description
parent string (parent name of Pod) Parent name of ntt.applications.v1.Pod
pod Pod Pod resource body
response_mask CreatePodRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreatePodRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdatePodRequest Message

A request message of the UpdatePod method.

Name Type Description
pod Pod Pod resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdatePodRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdatePodRequest.ResponseMask reduce message response size.

UpdatePodRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Pod Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdatePodRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeletePodRequest Message

A request message of the DeletePod method.

Name Type Description
name string (name of Pod) Name of ntt.applications.v1.Pod

Pod Enumerations

Here is the list of Pod resource enumerations:

Pod.Status.Phase Enumeration

PodPhase is states of Pod. TODO remove prefixes when the name conflict issue by gogo is resolved

Name Description
PHASE_UNSPECIFIED PhaseUnspecified means the Pod is in unknown state. This state is usually not used.
PENDING PhasePending is used when the Pod is accepted by the system and it’s under processing to be launched.
RUNNING PhaseRunning indicates all the containers supposed to be running are up and running.
SUCCEEDED PhaseSucceeded indicates the Pod is terminated however the exit codes of the containers are non-error numbers.
FAILED PhaseFailed is used when the Pod encountered an issue and some or all of the container are not running. This Phase happens after the containers are initially created successfully
UNKNOWN PhaseUnknown is used when the assigned node doesn’t respond anymore
IMAGE_DOWNLOAD_FAILED IMAGE_DOWNLOAD_FAILED is the state when docker image pull fails.
INIT_FAILED INIT_FAILED is the state when validation fails or pod initialization fails because of some system error. Typically caused by yaml syntax errors or system errors on device such as disk full etc
POD_CREATE_FAILED POD_CREATE_FAILED is the state when pod UP fails. In this case, the compose file is a valid yaml. The failure could be wrong or could be caused by docker errors or keyword errors

Pod.Status.HealthStatus Enumeration

Name Description
HEALTH_STATUS_UNKNOWN
HEALTHY
UNHEALTHY

Pod.Status.Container.State Enumeration

TODO remove prefixes when the name conflict issue by gogo is resolved

Name Description
STATE_UNSPECIFIED
WAITING
RUNNING
TERMINATED
UNKNOWN

Project Resource

Project Resource

Name patterns:

  • projects/{project}

This section covers the methods and messages to interact with Project resource.

Project Methods

Here is the list of Project resource methods:

GetProject Method

GetProject

rpc GetProject(GetProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.get

The equivalent REST API is:

GET /v1/{name=projects/*}

BatchGetProjects Method

BatchGetProjects

rpc BatchGetProjects(BatchGetProjectsRequest) returns (BatchGetProjectsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.batchGet

The equivalent REST API is:

GET /v1/projects:batchGet

ListProjects Method

ListProjects

rpc ListProjects(ListProjectsRequest) returns (ListProjectsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.list

The equivalent REST API is:

GET /v1/projects

WatchProject Method

WatchProject

rpc WatchProject(WatchProjectRequest) returns (WatchProjectResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.watch

The equivalent REST API is:

POST /v1/{name=projects/*}:watch

WatchProjects Method

WatchProjects

rpc WatchProjects(WatchProjectsRequest) returns (WatchProjectsResponse)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.watch

The equivalent REST API is:

POST /v1/projects:watch

CreateProject Method

CreateProject

rpc CreateProject(CreateProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.create

The equivalent REST API is:

POST /v1/projects (BODY: project)

UpdateProject Method

UpdateProject

rpc UpdateProject(UpdateProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.update

The equivalent REST API is:

PUT /v1/{project.name=projects/*} (BODY: project)

DeleteProject Method

DeleteProject

rpc DeleteProject(DeleteProjectRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/applications.edgelq.com/permissions/projects.delete

The equivalent REST API is:

DELETE /v1/{name=projects/*}

Project Messages

Here is the list of Project resource messages:

Project Message

Name Type Description
name string (name of Project) Name of Project When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
multi_region_policy MultiRegionPolicy Multi region policy defines in which region all kid resources (and their kids) will by default belong and cross-region syncing policies.

GetProjectRequest Message

A request message of the GetProject method.

Name Type Description
name string (name of Project) Name of ntt.applications.v1.Project
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetProjectsRequest Message

A request message of the BatchGetProjects method.

Name Type Description
names repeated string (name of Project) Names of Projects
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetProjectsResponse Message

A response message of the BatchGetProjects method.

Name Type Description
projects repeated Project found Projects
missing repeated string (name of Project) list of not found Projects

ListProjectsRequest Message

A request message of the ListProjects method.

Name Type Description
page_size int32 Requested page size. Server may return fewer Projects than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Project) A token identifying a page of results the server should return. Typically, this is the value of ListProjectsResponse.next_page_token.
order_by string (orderBy of Project) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of Project) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListProjectsResponse Message

A response message of the ListProjects method.

Name Type Description
projects repeated Project The list of Projects
prev_page_token string (cursor of Project) A token to retrieve previous page of results. Pass this value in the ListProjectsRequest.page_token.
next_page_token string (cursor of Project) A token to retrieve next page of results. Pass this value in the ListProjectsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total Projects across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchProjectRequest Message

A request message of the WatchProject method.

Name Type Description
name string (name of Project) Name of ntt.applications.v1.Project
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchProjectResponse Message

A response message of the WatchProject method.

Name Type Description
change ProjectChange

WatchProjectsRequest Message

A request message of the WatchProjects method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
page_size int32 Requested page size. Server may return fewer Projects than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Project) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Project) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of Project) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to Project that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Project that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchProjectsResponse Message

A response message of the WatchProjects method.

Name Type Description
project_changes repeated ProjectChange Changes of Projects
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All Projects will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchProjectsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (Projects will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchProjectsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of Project) New token to retrieve previous page of results.
next_page_token string (cursor of Project) New token to retrieve next page of results.

CreateProjectRequest Message

A request message of the CreateProject method.

Name Type Description
project Project Project resource body
response_mask CreateProjectRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateProjectRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateProjectRequest Message

A request message of the UpdateProject method.

Name Type Description
project Project Project resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateProjectRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateProjectRequest.ResponseMask reduce message response size.

UpdateProjectRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state Project Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateProjectRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteProjectRequest Message

A request message of the DeleteProject method.

Name Type Description
name string (name of Project) Name of ntt.applications.v1.Project

Applications Service Shared Methods and Messages

Applications Service Shared Messages

Here is the list of Applications service shared messages:

ConfigMapChange Message

ConfigMapChange is used by Watch notifications Responses to describe change of single ConfigMap One of Added, Modified, Removed

Name Type Description
added ConfigMapChange.Added Added is returned when watched document is added, either created or enters Query view
modified ConfigMapChange.Modified Modified is returned when watched document is modified
current ConfigMapChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ConfigMapChange.Removed Removed is returned when ConfigMap is deleted or leaves Query view

ConfigMapChange.Added Message

ConfigMap has been added to query view

Name Type Description
config_map ConfigMap
view_index int32 Integer describing index of added ConfigMap in resulting query view.

ConfigMapChange.Current Message

ConfigMap has been added or modified in a query view. Version used for stateless watching

Name Type Description
config_map ConfigMap

ConfigMapChange.Modified Message

ConfigMap changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of ConfigMap) Name of modified ConfigMap
config_map ConfigMap New version of ConfigMap or masked difference, depending on mask_changes instrumentation of issued [WatchConfigMapRequest] or [WatchConfigMapsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified ConfigMap. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying ConfigMap new index in resulting query view.

ConfigMapChange.Removed Message

Removed is returned when ConfigMap is deleted or leaves Query view

Name Type Description
name string (name of ConfigMap)
view_index int32 Integer specifying removed ConfigMap index. Not populated in stateless watch type.

ConfigMapEnvSource Message

ConfigMapEnvSource selects a ConfigMap to populate the environment variables with.

The contents of the target ConfigMap’s Data field will represent the key-value pairs as environment variables.

Name Type Description
name string The ConfigMap to select from.
optional bool Specify whether the ConfigMap must be defined

ConfigMapKeySelector Message

Name Type Description
name string The ConfigMap to select from.
key string The key to select.
optional bool Specify whether the ConfigMap or its key must be defined

ConfigMapVolumeSource Message

Adapts a ConfigMap into a volume.

The contents of the target ConfigMap’s Data field will be presented in a volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. ConfigMap volumes support ownership management and SELinux relabeling.

Name Type Description
name string
items repeated KeyToPath If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the ‘..’ path or start with ‘..’.
default_mode int32 Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.
optional bool Specify whether the ConfigMap or its keys must be defined

DistributionChange Message

DistributionChange is used by Watch notifications Responses to describe change of single Distribution One of Added, Modified, Removed

Name Type Description
added DistributionChange.Added Added is returned when watched document is added, either created or enters Query view
modified DistributionChange.Modified Modified is returned when watched document is modified
current DistributionChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed DistributionChange.Removed Removed is returned when Distribution is deleted or leaves Query view

DistributionChange.Added Message

Distribution has been added to query view

Name Type Description
distribution Distribution
view_index int32 Integer describing index of added Distribution in resulting query view.

DistributionChange.Current Message

Distribution has been added or modified in a query view. Version used for stateless watching

Name Type Description
distribution Distribution

DistributionChange.Modified Message

Distribution changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Distribution) Name of modified Distribution
distribution Distribution New version of Distribution or masked difference, depending on mask_changes instrumentation of issued [WatchDistributionRequest] or [WatchDistributionsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Distribution. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Distribution new index in resulting query view.

DistributionChange.Removed Message

Removed is returned when Distribution is deleted or leaves Query view

Name Type Description
name string (name of Distribution)
view_index int32 Integer specifying removed Distribution index. Not populated in stateless watch type.

EnvFromSource Message

EnvFromSource represents the source of a set of ConfigMaps

Name Type Description
prefix string An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER.
config_map_ref ConfigMapEnvSource The ConfigMap to select from
secret_ref SecretEnvSource The Secret to select from

EnvVar Message

EnvVar is a key value pair for environment variables.

Name Type Description
name string name is the name of the environment variable.
value string value is the value of the environment variable.
value_from EnvVarSource Source for the environment variable’s value. Cannot be used if value is not empty.

EnvVarSource Message

EnvVarSource represents a source for the value of an EnvVar.

Name Type Description
config_map_key_ref ConfigMapKeySelector Selects a key of a ConfigMap.
secret_key_ref SecretKeySelector Selects a key of a secret in the pod’s namespace

HostPathVolumeSource Message

Represents a host path mapped into a pod.

Name Type Description
path string Path of the directory on the host. If the path is a symlink, it will follow the link to the real path.
type HostPathVolumeSource.Type Type for HostPath Volume

KeyToPath Message

Maps a string key to a path within a volume.

Name Type Description
key string The key to project.
path string The relative path of the file to map the key to. May not be an absolute path. May not contain the path element ‘..’. May not start with the string ‘..’.
mode int32 Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.

LabelSelector Message

A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.

Name Type Description
match_labels map<string, string> matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed. +optional
match_expressions repeated LabelSelectorRequirement matchExpressions is a list of label selector requirements. The requirements are ANDed. +optional

LabelSelectorRequirement Message

A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.

Name Type Description
key string key is the label key that the selector applies to. +patchMergeKey=key +patchStrategy=merge
operator string operator represents a key’s relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
values repeated string values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. +optional

LocalObjectReferenceSecret Message

LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace.

Name Type Description
name string (reference to Secret) Name of the referent.

PodChange Message

PodChange is used by Watch notifications Responses to describe change of single Pod One of Added, Modified, Removed

Name Type Description
added PodChange.Added Added is returned when watched document is added, either created or enters Query view
modified PodChange.Modified Modified is returned when watched document is modified
current PodChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed PodChange.Removed Removed is returned when Pod is deleted or leaves Query view

PodChange.Added Message

Pod has been added to query view

Name Type Description
pod Pod
view_index int32 Integer describing index of added Pod in resulting query view.

PodChange.Current Message

Pod has been added or modified in a query view. Version used for stateless watching

Name Type Description
pod Pod

PodChange.Modified Message

Pod changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Pod) Name of modified Pod
pod Pod New version of Pod or masked difference, depending on mask_changes instrumentation of issued [WatchPodRequest] or [WatchPodsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Pod. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Pod new index in resulting query view.

PodChange.Removed Message

Removed is returned when Pod is deleted or leaves Query view

Name Type Description
name string (name of Pod)
view_index int32 Integer specifying removed Pod index. Not populated in stateless watch type.

PodSpec Message

PodSpec defines the configuration of a Pod

Name Type Description
node string (reference to Device) node is the name of the target node that the Pod is meant to be deployed to.
containers repeated PodSpec.Container containers defines list of containers that the Pod launches.
host_network bool Containers use the host network.
restart_policy PodSpec.RestartPolicy
image_pull_secrets repeated LocalObjectReferenceSecret ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored.
volumes repeated Volume List of volumes that can be mounted by containers belonging to the pod.
compose string Compose file as a string. When this value is provided, you can manage containers directlry using Docker Compose. Other values in the Spec expect node will be ignored.
host_volume_mounts repeated VolumeMount HostVolumeMounts defines volumes to be mounted to the host file system.
compose_health_checks map<string, PodSpec.ContainerHealthChecks> Health checks for services defined in the compose. map of serviceName to HealthCheck

PodSpec.Container Message

Container defines configuration of a Container.

Name Type Description
args repeated string args to run the command.
command repeated string command to run the container. The image default command will be used when it’s not given.
env repeated EnvVar env is additional environment variables passed to the container.
image string image is the URL of the container image.
image_pull_policy string
name string name is the name of the container. Must be unique in the Pod.
resources PodSpec.Container.ResourceRequirements
security_context SecurityContext Security options the pod should run with.
volume_mounts repeated VolumeMount Pod volumes to mount into the container’s filesystem. Cannot be updated.
envFrom EnvFromSource List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
health_check repeated HealthCheckSpec Health check for container

PodSpec.Container.ResourceRequirements Message

Name Type Description
limits map<string, int64> todo: change to k8s.io.apimachinery.pkg.api.resource.
requests map<string, int64>

PodSpec.ContainerHealthChecks Message

There can be more than 1 health check for a container

Name Type Description
health_checks repeated HealthCheckSpec

ProjectChange Message

ProjectChange is used by Watch notifications Responses to describe change of single Project One of Added, Modified, Removed

Name Type Description
added ProjectChange.Added Added is returned when watched document is added, either created or enters Query view
modified ProjectChange.Modified Modified is returned when watched document is modified
current ProjectChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed ProjectChange.Removed Removed is returned when Project is deleted or leaves Query view

ProjectChange.Added Message

Project has been added to query view

Name Type Description
project Project
view_index int32 Integer describing index of added Project in resulting query view.

ProjectChange.Current Message

Project has been added or modified in a query view. Version used for stateless watching

Name Type Description
project Project

ProjectChange.Modified Message

Project changed some of it’s fields - contains either full document or masked change

Name Type Description
name string (name of Project) Name of modified Project
project Project New version of Project or masked difference, depending on mask_changes instrumentation of issued [WatchProjectRequest] or [WatchProjectsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified Project. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Project new index in resulting query view.

ProjectChange.Removed Message

Removed is returned when Project is deleted or leaves Query view

Name Type Description
name string (name of Project)
view_index int32 Integer specifying removed Project index. Not populated in stateless watch type.

SecretEnvSource Message

SecretEnvSource selects a Secret to populate the environment variables with.

The contents of the target Secret’s Data field will represent the key-value pairs as environment variables.

Name Type Description
name string The Secret to select from.
optional bool Specify whether the Secret must be defined

SecretKeySelector Message

SecretKeySelector selects a key of a Secret.

Name Type Description
name string The name of the secret in the pod’s namespace to select from.
key string The key of the secret to select from. Must be a valid secret key.
optional bool Specify whether the Secret or its key must be defined

SecretVolumeSource Message

Adapts a Secret into a volume.

The contents of the target Secret’s Data field will be presented in a volume as files using the keys in the Data field as the file names. Secret volumes support ownership management and SELinux relabeling.

Name Type Description
secret_name string Name of the secret in the pod’s namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
items repeated KeyToPath If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the ‘..’ path or start with ‘..’. +optional
default_mode int32 Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.
optional bool Specify whether the Secret or its keys must be defined

SecurityContext Message

PodSecurityContext holds pod-level security attributes and common container settings. Some fields are also present in container.securityContext. Field values of container.securityContext take precedence over field values of PodSecurityContext.

Name Type Description
privileged bool Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false.

Volume Message

Volume represents a named volume in a pod that may be accessed by any container in the pod.

Name Type Description
name string Volume’s name. Must be a DNS_LABEL and unique within the pod.
host_path HostPathVolumeSource HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this.
secret SecretVolumeSource Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
config_map ConfigMapVolumeSource ConfigMap represents a configMap that should populate this volume

VolumeMount Message

VolumeMount describes a mounting of a Volume within a container.

Name Type Description
name string This must match the Name of a Volume.
read_only bool Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false.
mount_path string Path within the container at which the volume should be mounted. Must not contain ‘:’.
sub_path string Path within the volume from which the container’s volume should be mounted. Defaults to "" (volume’s root).

Applications Service Shared Enumerations

Here is the list of Applications service shared enumerations:

HostPathVolumeSource.Type Enumeration

Name Description
TYPE_UNSPECIFIED TYPE_UNSPECIFIED is not used. Type must be set to one of the concreate values.
DIRECTORY_OR_CREATE If nothing exists at the given path, an empty directory will be created there as needed with permission set to 0755, having the same group and ownership with Droplet.
DIRECTORY A directory must exist at the given path
FILE_OR_CREATE If nothing exists at the given path, an empty file will be created there as needed with permission set to 0644, having the same group and ownership with Droplet.
FILE A file must exist at the given path
SOCKET A UNIX socket must exist at the given path
CHAR_DEVICE A character device must exist at the given path
BLOCK_DEVICE A block device must exist at the given path

PodSpec.RestartPolicy Enumeration

Name Description
RESTART_POLICY_UNSPECIFIED
ALWAYS
ON_FAILURE
NEVER