fix(pipeline-run,model-run): clarify actors in Run objects (#519)

Because - The `PipelineRun` and `ModelRun` objects have confusing documentation for the requester, runner and owner of a pipeline/model run. This commit - Recovers changes in #513 improving the object naming and documentation. --------- Co-authored-by: droplet-bot <[email protected]>
instill-ai · Nov 29, 2024 · bbbeead · bbbeead
1 parent 7e2f368
commit bbbeead
Show file tree

Hide file tree

Showing 8 changed files with 192 additions and 104 deletions.
diff --git a/.github/workflows/buf-ci.yaml b/.github/workflows/buf-ci.yaml
@@ -47,6 +47,8 @@ jobs:
           git_tag_gpgsign: true
           workdir: ./protogen-go
       - name: Generate Go/gRPC/gRPC-Gateway client and server stubs, and commit to protogen-go repository
+        env:
+          BUF_TOKEN: ${{ secrets.botBufToken }}
         run: |
           go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
           go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
@@ -86,6 +88,8 @@ jobs:
           git_tag_gpgsign: true
           workdir: ./protogen-python
       - name: Generate Go/gRPC client and server stubs, and commit to protogen-python repository
+        env:
+          BUF_TOKEN: ${{ secrets.botBufToken }}
         run: |
           go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
           go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

diff --git a/.github/workflows/buf-gen-openapi.yaml b/.github/workflows/buf-gen-openapi.yaml
@@ -25,6 +25,8 @@ jobs:
           git_commit_gpgsign: true
           git_tag_gpgsign: true
       - name: Generate OpenAPI definitions
+        env:
+          BUF_TOKEN: ${{ secrets.botBufToken }}
         run: |
           make openapi
       - name: Lint generated OpenAPI definitions

diff --git a/artifact/artifact/v1alpha/artifact_public_service.proto b/artifact/artifact/v1alpha/artifact_public_service.proto
@@ -55,7 +55,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -69,7 +69,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -86,7 +86,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -100,7 +100,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -117,7 +117,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -131,7 +131,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -146,6 +146,10 @@ service ArtifactPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "💾 Artifact"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -165,7 +169,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -179,7 +183,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -207,7 +211,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -238,7 +242,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -253,6 +257,10 @@ service ArtifactPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "💾 Artifact"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -273,6 +281,10 @@ service ArtifactPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "💾 Artifact"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -292,7 +304,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -301,12 +313,12 @@ service ArtifactPublicService {
   //
   // Returns a paginated list of catalog runs.
   rpc ListCatalogRuns(ListCatalogRunsRequest) returns (ListCatalogRunsResponse) {
-    option (google.api.http) = {get: "/v1beta/namespaces/{namespace_id}/catalogs/{catalog_id}/runs"};
+    option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/catalogs/{catalog_id}/runs"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -320,7 +332,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }
@@ -334,7 +346,7 @@ service ArtifactPublicService {
       tags: "💾 Artifact"
       extensions: {
         key: "x-stage"
-        value: {string_value: "beta"}
+        value: {string_value: "alpha"}
       }
     };
   }

diff --git a/model/model/v1alpha/model.proto b/model/model/v1alpha/model.proto
@@ -1724,8 +1724,9 @@ message UndeployOrganizationModelAdminResponse {}
 message ModelRun {
   // Model Run UUID.
   string uid = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
-  // Model UUID.
-  string model_uid = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // 2 is reserved for the model UUID. Public resources should be identified by
+  // their ID and parent resource.
+  reserved 2;
   // Model run status.
   common.run.v1alpha.RunStatus status = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
   // Run source.
@@ -1770,11 +1771,11 @@ message ModelRun {
     (google.api.field_behavior) = OUTPUT_ONLY,
     (google.api.field_behavior) = OPTIONAL
   ];
-  // Requester ID. This field might be empty if the model run belongs to a
-  // deleted namespace.
+  // Requester ID. The namespace used to trigger the run. This field might be
+  // empty if the model run belongs to a deleted namespace.
   string requester_id = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
-  // Namespace ID.
-  string namespace_id = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // ID of the namespace that owns the model.
+  string model_namespace_id = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // ListModelRunsRequest represents a request to list of model runs.

diff --git a/model/model/v1alpha/model_public_service.proto b/model/model/v1alpha/model_public_service.proto
@@ -289,6 +289,10 @@ service ModelPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -310,6 +314,10 @@ service ModelPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -331,6 +339,10 @@ service ModelPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -352,6 +364,10 @@ service ModelPublicService {
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -369,6 +385,10 @@ service ModelPublicService {
   rpc TriggerNamespaceModelBinaryFileUpload(stream TriggerNamespaceModelBinaryFileUploadRequest) returns (TriggerNamespaceModelBinaryFileUploadResponse) {
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -386,6 +406,10 @@ service ModelPublicService {
   rpc TriggerNamespaceLatestModelBinaryFileUpload(stream TriggerNamespaceLatestModelBinaryFileUploadRequest) returns (TriggerNamespaceLatestModelBinaryFileUploadResponse) {
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
       parameters: {
         headers: {
           name: "Instill-Requester-Uid"
@@ -824,9 +848,13 @@ service ModelPublicService {
     option (google.api.method_visibility).restriction = "INTERNAL";
   }
 
-  // List model runs
+  // List Model Runs
   //
-  // Returns a paginated list of model runs.
+  // Returns a paginated list of runs for a given model. When the requester is
+  // the owner of the model, they will be able to all the model runs,
+  // regardless who requested the trigger (the view will be partial to hide
+  // sensitive data like e.g. the trigger input and output). Other requesters
+  // will only be able to see the runs requested by themselves.
   rpc ListModelRuns(ListModelRunsRequest) returns (ListModelRunsResponse) {
     option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/models/{model_id}/runs"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
@@ -838,23 +866,24 @@ service ModelPublicService {
           type: STRING
         }
       }
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
     };
   }
 
-  // List Model Runs of a Namespace (user or organization)
+  // List Model Runs By Requester
   //
-  // Returns a paginated list of runs for 1 or more models. This is mainly used by dashboard.
-  // The requester can view all the runs by the requester across different models.
+  // Returns a paginated list of runs requested by a namespace. The response
+  // may contain runs from several models.
   rpc ListModelRunsByRequester(ListModelRunsByRequesterRequest) returns (ListModelRunsByRequesterResponse) {
     option (google.api.http) = {get: "/v1alpha/dashboard/models/runs"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       tags: "⚗️ Model"
-      parameters: {
-        headers: {
-          name: "Instill-Requester-Uid"
-          description: "Indicates the authenticated namespace is making the request on behalf of another entity, typically an organization they belong to"
-          type: STRING
-        }
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
       }
     };
   }