xref: /aosp_15_r20/external/googleapis/google/cloud/networkmanagement/v1/reachability.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)
1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.networkmanagement.v1;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/cloud/networkmanagement/v1/connectivity_test.proto";
24import "google/longrunning/operations.proto";
25import "google/protobuf/empty.proto";
26import "google/protobuf/field_mask.proto";
27import "google/protobuf/timestamp.proto";
28
29option csharp_namespace = "Google.Cloud.NetworkManagement.V1";
30option go_package = "cloud.google.com/go/networkmanagement/apiv1/networkmanagementpb;networkmanagementpb";
31option java_multiple_files = true;
32option java_outer_classname = "ReachabilityServiceProto";
33option java_package = "com.google.cloud.networkmanagement.v1";
34option php_namespace = "Google\\Cloud\\NetworkManagement\\V1";
35option ruby_package = "Google::Cloud::NetworkManagement::V1";
36
37// The Reachability service in Google Cloud Network Management API
38
39// The Reachability service in the Google Cloud Network Management API provides
40// services that analyze the reachability within a single Google Virtual Private
41// Cloud (VPC) network, between peered VPC networks, between VPC and on-premises
42// networks, or between VPC networks and internet hosts. A reachability analysis
43// is based on Google Cloud network configurations.
44//
45// You can use the analysis results to verify these configurations and
46// to troubleshoot connectivity issues.
47service ReachabilityService {
48  option (google.api.default_host) = "networkmanagement.googleapis.com";
49  option (google.api.oauth_scopes) =
50      "https://www.googleapis.com/auth/cloud-platform";
51
52  // Lists all Connectivity Tests owned by a project.
53  rpc ListConnectivityTests(ListConnectivityTestsRequest)
54      returns (ListConnectivityTestsResponse) {
55    option (google.api.http) = {
56      get: "/v1/{parent=projects/*/locations/global}/connectivityTests"
57    };
58    option (google.api.method_signature) = "parent";
59  }
60
61  // Gets the details of a specific Connectivity Test.
62  rpc GetConnectivityTest(GetConnectivityTestRequest)
63      returns (ConnectivityTest) {
64    option (google.api.http) = {
65      get: "/v1/{name=projects/*/locations/global/connectivityTests/*}"
66    };
67    option (google.api.method_signature) = "name";
68  }
69
70  // Creates a new Connectivity Test.
71  // After you create a test, the reachability analysis is performed as part
72  // of the long running operation, which completes when the analysis completes.
73  //
74  // If the endpoint specifications in `ConnectivityTest` are invalid
75  // (for example, containing non-existent resources in the network, or you
76  // don't have read permissions to the network configurations of listed
77  // projects), then the reachability result returns a value of `UNKNOWN`.
78  //
79  // If the endpoint specifications in `ConnectivityTest` are
80  // incomplete, the reachability result returns a value of
81  // <code>AMBIGUOUS</code>. For more information,
82  // see the Connectivity Test documentation.
83  rpc CreateConnectivityTest(CreateConnectivityTestRequest)
84      returns (google.longrunning.Operation) {
85    option (google.api.http) = {
86      post: "/v1/{parent=projects/*/locations/global}/connectivityTests"
87      body: "resource"
88    };
89    option (google.api.method_signature) = "parent,test_id,resource";
90    option (google.longrunning.operation_info) = {
91      response_type: "google.cloud.networkmanagement.v1.ConnectivityTest"
92      metadata_type: "OperationMetadata"
93    };
94  }
95
96  // Updates the configuration of an existing `ConnectivityTest`.
97  // After you update a test, the reachability analysis is performed as part
98  // of the long running operation, which completes when the analysis completes.
99  // The Reachability state in the test resource is updated with the new result.
100  //
101  // If the endpoint specifications in `ConnectivityTest` are invalid
102  // (for example, they contain non-existent resources in the network, or the
103  // user does not have read permissions to the network configurations of
104  // listed projects), then the reachability result returns a value of
105  // <code>UNKNOWN</code>.
106  //
107  // If the endpoint specifications in `ConnectivityTest` are incomplete, the
108  // reachability result returns a value of `AMBIGUOUS`. See the documentation
109  // in `ConnectivityTest` for for more details.
110  rpc UpdateConnectivityTest(UpdateConnectivityTestRequest)
111      returns (google.longrunning.Operation) {
112    option (google.api.http) = {
113      patch: "/v1/{resource.name=projects/*/locations/global/connectivityTests/*}"
114      body: "resource"
115    };
116    option (google.api.method_signature) = "update_mask,resource";
117    option (google.longrunning.operation_info) = {
118      response_type: "google.cloud.networkmanagement.v1.ConnectivityTest"
119      metadata_type: "OperationMetadata"
120    };
121  }
122
123  // Rerun an existing `ConnectivityTest`.
124  // After the user triggers the rerun, the reachability analysis is performed
125  // as part of the long running operation, which completes when the analysis
126  // completes.
127  //
128  // Even though the test configuration remains the same, the reachability
129  // result may change due to underlying network configuration changes.
130  //
131  // If the endpoint specifications in `ConnectivityTest` become invalid (for
132  // example, specified resources are deleted in the network, or you lost
133  // read permissions to the network configurations of listed projects), then
134  // the reachability result returns a value of `UNKNOWN`.
135  rpc RerunConnectivityTest(RerunConnectivityTestRequest)
136      returns (google.longrunning.Operation) {
137    option (google.api.http) = {
138      post: "/v1/{name=projects/*/locations/global/connectivityTests/*}:rerun"
139      body: "*"
140    };
141    option (google.longrunning.operation_info) = {
142      response_type: "google.cloud.networkmanagement.v1.ConnectivityTest"
143      metadata_type: "OperationMetadata"
144    };
145  }
146
147  // Deletes a specific `ConnectivityTest`.
148  rpc DeleteConnectivityTest(DeleteConnectivityTestRequest)
149      returns (google.longrunning.Operation) {
150    option (google.api.http) = {
151      delete: "/v1/{name=projects/*/locations/global/connectivityTests/*}"
152    };
153    option (google.api.method_signature) = "name";
154    option (google.longrunning.operation_info) = {
155      response_type: "google.protobuf.Empty"
156      metadata_type: "OperationMetadata"
157    };
158  }
159}
160
161// Request for the `ListConnectivityTests` method.
162message ListConnectivityTestsRequest {
163  // Required. The parent resource of the Connectivity Tests:
164  //     `projects/{project_id}/locations/global`
165  string parent = 1 [(google.api.field_behavior) = REQUIRED];
166
167  // Number of `ConnectivityTests` to return.
168  int32 page_size = 2;
169
170  // Page token from an earlier query, as returned in `next_page_token`.
171  string page_token = 3;
172
173  // Lists the `ConnectivityTests` that match the filter expression. A filter
174  // expression filters the resources listed in the response. The expression
175  // must be of the form `<field> <operator> <value>` where operators: `<`, `>`,
176  // `<=`,
177  // `>=`,
178  // `!=`, `=`, `:` are supported (colon `:` represents a HAS operator which is
179  // roughly synonymous with equality). <field> can refer to a proto or JSON
180  // field, or a synthetic field. Field names can be camelCase or snake_case.
181  //
182  // Examples:
183  // - Filter by name:
184  //   name = "projects/proj-1/locations/global/connectivityTests/test-1
185  //
186  // - Filter by labels:
187  //   - Resources that have a key called `foo`
188  //     labels.foo:*
189  //   - Resources that have a key called `foo` whose value is `bar`
190  //     labels.foo = bar
191  string filter = 4;
192
193  // Field to use to sort the list.
194  string order_by = 5;
195}
196
197// Response for the `ListConnectivityTests` method.
198message ListConnectivityTestsResponse {
199  // List of Connectivity Tests.
200  repeated ConnectivityTest resources = 1;
201
202  // Page token to fetch the next set of Connectivity Tests.
203  string next_page_token = 2;
204
205  // Locations that could not be reached (when querying all locations with `-`).
206  repeated string unreachable = 3;
207}
208
209// Request for the `GetConnectivityTest` method.
210message GetConnectivityTestRequest {
211  // Required. `ConnectivityTest` resource name using the form:
212  //     `projects/{project_id}/locations/global/connectivityTests/{test_id}`
213  string name = 1 [(google.api.field_behavior) = REQUIRED];
214}
215
216// Request for the `CreateConnectivityTest` method.
217message CreateConnectivityTestRequest {
218  // Required. The parent resource of the Connectivity Test to create:
219  //     `projects/{project_id}/locations/global`
220  string parent = 1 [(google.api.field_behavior) = REQUIRED];
221
222  // Required. The logical name of the Connectivity Test in your project
223  // with the following restrictions:
224  //
225  // * Must contain only lowercase letters, numbers, and hyphens.
226  // * Must start with a letter.
227  // * Must be between 1-40 characters.
228  // * Must end with a number or a letter.
229  // * Must be unique within the customer project
230  string test_id = 2 [(google.api.field_behavior) = REQUIRED];
231
232  // Required. A `ConnectivityTest` resource
233  ConnectivityTest resource = 3 [(google.api.field_behavior) = REQUIRED];
234}
235
236// Request for the `UpdateConnectivityTest` method.
237message UpdateConnectivityTestRequest {
238  // Required. Mask of fields to update. At least one path must be supplied in
239  // this field.
240  google.protobuf.FieldMask update_mask = 1
241      [(google.api.field_behavior) = REQUIRED];
242
243  // Required. Only fields specified in update_mask are updated.
244  ConnectivityTest resource = 2 [(google.api.field_behavior) = REQUIRED];
245}
246
247// Request for the `DeleteConnectivityTest` method.
248message DeleteConnectivityTestRequest {
249  // Required. Connectivity Test resource name using the form:
250  //     `projects/{project_id}/locations/global/connectivityTests/{test_id}`
251  string name = 1 [(google.api.field_behavior) = REQUIRED];
252}
253
254// Request for the `RerunConnectivityTest` method.
255message RerunConnectivityTestRequest {
256  // Required. Connectivity Test resource name using the form:
257  //     `projects/{project_id}/locations/global/connectivityTests/{test_id}`
258  string name = 1 [(google.api.field_behavior) = REQUIRED];
259}
260
261// Metadata describing an [Operation][google.longrunning.Operation]
262message OperationMetadata {
263  // The time the operation was created.
264  google.protobuf.Timestamp create_time = 1;
265
266  // The time the operation finished running.
267  google.protobuf.Timestamp end_time = 2;
268
269  // Target of the operation - for example
270  // projects/project-1/locations/global/connectivityTests/test-1
271  string target = 3;
272
273  // Name of the verb executed by the operation.
274  string verb = 4;
275
276  // Human-readable status of the operation, if any.
277  string status_detail = 5;
278
279  // Specifies if cancellation was requested for the operation.
280  bool cancel_requested = 6;
281
282  // API version.
283  string api_version = 7;
284}
285