Skip to content

Commit

Permalink
Add a link to protobuf-grpc-service design page in proto doc (#310)
Browse files Browse the repository at this point in the history 
* #309

* removed commented out todo lines
  • Loading branch information
@yabuchan
yabuchan authored Jun 28, 2022
1 parent b2f733e commit 85c548b
Show file tree
Hide file tree
Showing 2 changed files with 254 additions and 15 deletions.
268 changes: 253 additions & 15 deletions docs/design/protobuf-grpc-service.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,86 @@ In order to better define resources at the API level, a few proto files will be
We end up propsing a simple and easy API which can cover most of the daily requirements.

```
service ClusterService {
// Creates a new Cluster.
rpc CreateCluster(CreateClusterRequest) returns (Cluster) {
option (google.api.http) = {
post: "/apis/v1alpha2/namespaces/{namespace}/clusters"
body: "cluster"
};
}
// Finds a specific Cluster by ID.
rpc GetCluster(GetClusterRequest) returns (Cluster) {
option (google.api.http) = {
get: "/apis/v1alpha2/namespaces/{namespace}/clusters/{name}"
};
}
// Finds all Clusters in a given namespace. Supports pagination, and sorting on certain fields.
rpc ListCluster(ListClustersRequest) returns (ListClustersResponse) {
option (google.api.http) = {
get: "/apis/v1alpha2/namespaces/{namespace}/clusters"
};
}
// Finds all Clusters in all namespaces. Supports pagination, and sorting on certain fields.
rpc ListAllClusters(ListAllClustersRequest) returns (ListAllClustersResponse) {
option (google.api.http) = {
get: "/apis/v1alpha2/clusters"
};
}
// Deletes an cluster without deleting the cluster's runs and jobs. To
// avoid unexpected behaviors, delete an cluster's runs and jobs before
// deleting the cluster.
rpc DeleteCluster(DeleteClusterRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/apis/v1alpha2/namespaces/{namespace}/clusters/{name}"
};
}
}
message CreateClusterRequest {
// The cluster to be created.
Cluster cluster = 1;
// The namespace of the cluster to be created.
string namespace = 2;
}
message GetClusterRequest {
// The name of the cluster to be retrieved.
string name = 1;
// The namespace of the cluster to be retrieved.
string namespace = 2;
}
message ListClustersRequest {
// The namespace of the clusters to be retrieved.
string namespace = 1;
}
message ListClustersResponse {
// A list of clusters returned.
repeated Cluster clusters = 1;
}
message ListAllClustersRequest {}
message ListAllClustersResponse {
// A list of clusters returned.
repeated Cluster clusters = 1;
}
message DeleteClusterRequest {
// The name of the cluster to be deleted.
string name = 1;
// The namespace of the cluster to be deleted.
string namespace = 2;
}
message Cluster {
// Required input field. Unique Cluster name provided by user.
// Required input field. Unique cluster name provided by user.
string name = 1;
// Required input field. Cluster's namespace provided by user
Expand All @@ -68,14 +146,14 @@ message Cluster {
PRODUCTION = 3;
}
Environment environment = 5;
// Required field. This field indicates ray cluster configuration
ClusterSpec cluster_spec = 6;
// Output. The time that the Cluster created.
// Output. The time that the cluster created.
google.protobuf.Timestamp created_at = 7;
// Output. The time that the Cluster deleted.
// Output. The time that the cluster deleted.
google.protobuf.Timestamp deleted_at = 8;
}
Expand Down Expand Up @@ -114,41 +192,201 @@ message WorkerGroupSpec {
map<string, string> ray_start_params = 7;
}
service ComputeTemplateService {
// Creates a new compute template.
rpc CreateComputeTemplate(CreateComputeTemplateRequest) returns (ComputeTemplate) {
option (google.api.http) = {
post: "/apis/v1alpha2/compute_templates"
body: "compute_template"
};
}
// Finds a specific compute template by its name and namespace.
rpc GetComputeTemplate(GetComputeTemplateRequest) returns (ComputeTemplate) {
option (google.api.http) = {
get: "/apis/v1alpha2/namespaces/{namespace}/compute_templates/{name}"
};
}
// Finds all compute templates in a given namespace. Supports pagination, and sorting on certain fields.
rpc ListComputeTemplates(ListComputeTemplatesRequest) returns (ListComputeTemplatesResponse) {
option (google.api.http) = {
get: "/apis/v1alpha2/namespaces/{namespace}/compute_templates"
};
}
// Finds all compute templates in a given namespace. Supports pagination, and sorting on certain fields.
rpc ListAllComputeTemplates(ListAllComputeTemplatesRequest) returns (ListAllComputeTemplatesResponse) {
option (google.api.http) = {
get: "/apis/v1alpha2/compute_templates"
};
}
// Deletes a compute template by its name and namespace
rpc DeleteComputeTemplate(DeleteComputeTemplateRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/apis/v1alpha2/namespaces/{namespace}/compute_templates/{name}"
};
}
}
message CreateComputeTemplateRequest {
// The compute template to be created.
ComputeTemplate compute_template = 1;
// The namespace of the compute template to be created
string namespace = 2;
}
message GetComputeTemplateRequest {
// The name of the ComputeTemplate to be retrieved.
string name = 1;
// The namespace of the compute template to be retrieved.
string namespace = 2;
}
message ListComputeTemplatesRequest {
// The namespace of the compute templates to be retrieved.
string namespace = 1;
// TODO: support paganation later
}
message ListComputeTemplatesResponse {
repeated ComputeTemplate compute_templates = 1;
}
message ListAllComputeTemplatesRequest {
// TODO: support paganation later
}
message ListAllComputeTemplatesResponse {
repeated ComputeTemplate compute_templates = 1;
}
message DeleteComputeTemplateRequest {
// The name of the compute template to be deleted.
string name = 1;
// The namespace of the compute template to be deleted.
string namespace = 2;
}
// ComputeTemplate can be reused by any compute units like worker group, workspace, image build job, etc
message ComputeTemplate {
// The ID of the compute template
// The name of the compute template
string name = 1;
// The namespace of the compute template
string namespace = 2;
// Number of cpus
uint32 cpu = 2;
uint32 cpu = 3;
// Number of memory
uint32 memory = 3;
uint32 memory = 4;
// Number of gpus
uint32 gpu = 4;
uint32 gpu = 5;
// The detail gpu accelerator type
string gpu_accelerator = 5;
string gpu_accelerator = 6;
}
service ImageTemplateService {
// Creates a new ImageTemplate.
rpc CreateImageTemplate(CreateImageTemplateRequest) returns (ImageTemplate) {
option (google.api.http) = {
post: "/apis/v1alpha2/image_templates"
body: "image_template"
};
}
// Finds a specific ImageTemplate by ID.
rpc GetImageTemplate(GetImageTemplateRequest) returns (ImageTemplate) {
option (google.api.http) = {
get: "/apis/v1alpha2/namespaces/{namespace}/image_templates/{name}"
};
}
// Finds all ImageTemplates. Supports pagination, and sorting on certain fields.
rpc ListImageTemplates(ListImageTemplatesRequest) returns (ListImageTemplatesResponse) {
option (google.api.http) = {
get: "/apis/v1alpha2/namespaces/{namespace}/image_templates"
};
}
// Deletes an ImageTemplate.
rpc DeleteImageTemplate(DeleteImageTemplateRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/apis/v1alpha2/namespaces/{namespace}/image_templates/{name}"
};
}
}
message CreateImageTemplateRequest {
// The image template to be created.
ImageTemplate image_template = 1;
// The namespace of the image template to be created.
string namespace = 2;
}
message GetImageTemplateRequest {
// The name of the image template to be retrieved.
string name = 1;
// The namespace of the image template to be retrieved.
string namespace = 2;
}
message ListImageTemplatesRequest {
// The namespace of the image templates to be retrieved.
string namespace = 1;
// TODO: support pagingation later
}
message ListImageTemplatesResponse {
// A list of Compute returned.
repeated ImageTemplate image_templates = 1;
}
message ListAllImageTemplatesRequest {
// TODO: support pagingation later
}
message ListAllImageTemplatesResponse {
// A list of Compute returned.
repeated ImageTemplate image_templates = 1;
}
message DeleteImageTemplateRequest {
// The name of the image template to be deleted.
string name = 1;
// The namespace of the image template to be deleted.
string namespace = 2;
}
// ImageTemplate can be used by worker group and workspce.
// They can be distinguish by different entrypoints
message ImageTemplate {
// The ID of the image template
string name = 1;
// The namespace of the image template
string namespace = 2;
// The base container image to be used for image building
string base_image = 2;
string base_image = 3;
// The pip packages to install
repeated string pip_packages = 3;
repeated string pip_packages = 4;
// The conda packages to install
repeated string conda_packages = 4;
repeated string conda_packages = 5;
// The system packages to install
repeated string system_packages = 5;
repeated string system_packages = 6;
// The environment variables to set
map<string, string> environment_variables = 6;
map<string, string> environment_variables = 7;
// The post install commands to execute
string custom_commands = 7;
string custom_commands = 8;
// Output. The result image generated
string image = 9;
}
message Status {
string error = 1;
int32 code = 2;
repeated google.protobuf.Any details = 3;
}
```

### Support multiple clients
Expand Down
1 change: 1 addition & 0 deletions proto/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ We postpone the client generation until there's external service needs for commu

Use the tools [bootprint-openapi](https://github.com/bootprint/bootprint-monorepo/tree/master/packages/bootprint-openapi)
and [html-inline](https://github.com/substack/html-inline) to generate the API reference from the swagger files.
Refer to [design doc](../docs/design/protobuf-grpc-service.md) for more details of the API and architecture.

### Third Party Protos

Expand Down

0 comments on commit 85c548b

Please sign in to comment.