connectivity_test.proto 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313
  1. // Copyright 2021 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. syntax = "proto3";
  15. package google.cloud.networkmanagement.v1beta1;
  16. import "google/api/field_behavior.proto";
  17. import "google/api/resource.proto";
  18. import "google/cloud/networkmanagement/v1beta1/trace.proto";
  19. import "google/protobuf/timestamp.proto";
  20. import "google/rpc/status.proto";
  21. import "google/api/annotations.proto";
  22. option csharp_namespace = "Google.Cloud.NetworkManagement.V1Beta1";
  23. option go_package = "google.golang.org/genproto/googleapis/cloud/networkmanagement/v1beta1;networkmanagement";
  24. option java_multiple_files = true;
  25. option java_outer_classname = "TestOuterClass";
  26. option java_package = "com.google.cloud.networkmanagement.v1beta1";
  27. option php_namespace = "Google\\Cloud\\NetworkManagement\\V1beta1";
  28. option ruby_package = "Google::Cloud::NetworkManagement::V1beta1";
  29. // A Connectivity Test for a network reachability analysis.
  30. message ConnectivityTest {
  31. option (google.api.resource) = {
  32. type: "networkmanagement.googleapis.com/ConnectivityTest"
  33. pattern: "projects/{project}/locations/global/connectivityTests/{test}"
  34. };
  35. // Required. Unique name of the resource using the form:
  36. // `projects/{project_id}/locations/global/connectivityTests/{test}`
  37. string name = 1 [(google.api.field_behavior) = REQUIRED];
  38. // The user-supplied description of the Connectivity Test.
  39. // Maximum of 512 characters.
  40. string description = 2;
  41. // Required. Source specification of the Connectivity Test.
  42. //
  43. // You can use a combination of source IP address, virtual machine
  44. // (VM) instance, or Compute Engine network to uniquely identify
  45. // the source location.
  46. //
  47. // Examples:
  48. // If the source IP address is an internal IP address within a Google Cloud
  49. // Virtual Private Cloud (VPC) network, then you must also specify the VPC
  50. // network. Otherwise, specify the VM instance, which already contains its
  51. // internal IP address and VPC network information.
  52. //
  53. // If the source of the test is within an on-premises network, then you must
  54. // provide the destination VPC network.
  55. //
  56. // If the source endpoint is a Compute Engine VM instance with multiple
  57. // network interfaces, the instance itself is not sufficient to identify the
  58. // endpoint. So, you must also specify the source IP address or VPC network.
  59. //
  60. // A reachability analysis proceeds even if the source location is
  61. // ambiguous. However, the test result may include endpoints that you don't
  62. // intend to test.
  63. Endpoint source = 3 [(google.api.field_behavior) = REQUIRED];
  64. // Required. Destination specification of the Connectivity Test.
  65. //
  66. // You can use a combination of destination IP address, Compute Engine
  67. // VM instance, or VPC network to uniquely identify the destination
  68. // location.
  69. //
  70. // Even if the destination IP address is not unique, the source IP
  71. // location is unique. Usually, the analysis can infer the destination
  72. // endpoint from route information.
  73. //
  74. // If the destination you specify is a VM instance and the instance has
  75. // multiple network interfaces, then you must also specify either
  76. // a destination IP address or VPC network to identify the destination
  77. // interface.
  78. //
  79. // A reachability analysis proceeds even if the destination location is
  80. // ambiguous. However, the result can include endpoints that you don't
  81. // intend to test.
  82. Endpoint destination = 4 [(google.api.field_behavior) = REQUIRED];
  83. // IP Protocol of the test. When not provided, "TCP" is assumed.
  84. string protocol = 5;
  85. // Other projects that may be relevant for reachability analysis.
  86. // This is applicable to scenarios where a test can cross project boundaries.
  87. repeated string related_projects = 6;
  88. // Output only. The display name of a Connectivity Test.
  89. string display_name = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
  90. // Resource labels to represent user-provided metadata.
  91. map<string, string> labels = 8;
  92. // Output only. The time the test was created.
  93. google.protobuf.Timestamp create_time = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
  94. // Output only. The time the test's configuration was updated.
  95. google.protobuf.Timestamp update_time = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
  96. // Output only. The reachability details of this test from the latest run.
  97. // The details are updated when creating a new test, updating an
  98. // existing test, or triggering a one-time rerun of an existing test.
  99. ReachabilityDetails reachability_details = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
  100. // Output only. The probing details of this test from the latest run, present for
  101. // applicable tests only. The details are updated when creating a new test,
  102. // updating an existing test, or triggering a one-time rerun of an existing
  103. // test.
  104. ProbingDetails probing_details = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
  105. }
  106. // Source or destination of the Connectivity Test.
  107. message Endpoint {
  108. // The type definition of an endpoint's network. Use one of the
  109. // following choices:
  110. enum NetworkType {
  111. // Default type if unspecified.
  112. NETWORK_TYPE_UNSPECIFIED = 0;
  113. // A network hosted within Google Cloud Platform.
  114. // To receive more detailed output, specify the URI for the source or
  115. // destination network.
  116. GCP_NETWORK = 1;
  117. // A network hosted outside of Google Cloud Platform.
  118. // This can be an on-premises network, or a network hosted by another cloud
  119. // provider.
  120. NON_GCP_NETWORK = 2;
  121. }
  122. // The IP address of the endpoint, which can be an external or internal IP.
  123. // An IPv6 address is only allowed when the test's destination is a
  124. // [global load balancer
  125. // VIP](https://cloud.google.com/load-balancing/docs/load-balancing-overview).
  126. string ip_address = 1;
  127. // The IP protocol port of the endpoint.
  128. // Only applicable when protocol is TCP or UDP.
  129. int32 port = 2;
  130. // A Compute Engine instance URI.
  131. string instance = 3;
  132. // A cluster URI for [Google Kubernetes Engine
  133. // master](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture).
  134. string gke_master_cluster = 7;
  135. // A [Cloud SQL](https://cloud.google.com/sql) instance URI.
  136. string cloud_sql_instance = 8;
  137. // A Compute Engine network URI.
  138. string network = 4;
  139. // Type of the network where the endpoint is located.
  140. // Applicable only to source endpoint, as destination network type can be
  141. // inferred from the source.
  142. NetworkType network_type = 5;
  143. // Project ID where the endpoint is located.
  144. // The Project ID can be derived from the URI if you provide a VM instance or
  145. // network URI.
  146. // The following are two cases where you must provide the project ID:
  147. // 1. Only the IP address is specified, and the IP address is within a GCP
  148. // project.
  149. // 2. When you are using Shared VPC and the IP address that you provide is
  150. // from the service project. In this case, the network that the IP address
  151. // resides in is defined in the host project.
  152. string project_id = 6;
  153. }
  154. // Results of the configuration analysis from the last run of the test.
  155. message ReachabilityDetails {
  156. // The overall result of the test's configuration analysis.
  157. enum Result {
  158. // No result was specified.
  159. RESULT_UNSPECIFIED = 0;
  160. // Possible scenarios are:
  161. //
  162. // * The configuration analysis determined that a packet originating from
  163. // the source is expected to reach the destination.
  164. // * The analysis didn't complete because the user lacks permission for
  165. // some of the resources in the trace. However, at the time the user's
  166. // permission became insufficient, the trace had been successful so far.
  167. REACHABLE = 1;
  168. // A packet originating from the source is expected to be dropped before
  169. // reaching the destination.
  170. UNREACHABLE = 2;
  171. // The source and destination endpoints do not uniquely identify
  172. // the test location in the network, and the reachability result contains
  173. // multiple traces. For some traces, a packet could be delivered, and for
  174. // others, it would not be.
  175. AMBIGUOUS = 4;
  176. // The configuration analysis did not complete. Possible reasons are:
  177. //
  178. // * A permissions error occurred--for example, the user might not have
  179. // read permission for all of the resources named in the test.
  180. // * An internal error occurred.
  181. // * The analyzer received an invalid or unsupported argument or was unable
  182. // to identify a known endpoint.
  183. UNDETERMINED = 5;
  184. }
  185. // The overall result of the test's configuration analysis.
  186. Result result = 1;
  187. // The time of the configuration analysis.
  188. google.protobuf.Timestamp verify_time = 2;
  189. // The details of a failure or a cancellation of reachability analysis.
  190. google.rpc.Status error = 3;
  191. // Result may contain a list of traces if a test has multiple possible
  192. // paths in the network, such as when destination endpoint is a load balancer
  193. // with multiple backends.
  194. repeated Trace traces = 5;
  195. }
  196. // Latency percentile rank and value.
  197. message LatencyPercentile {
  198. // Percentage of samples this data point applies to.
  199. int32 percent = 1;
  200. // percent-th percentile of latency observed, in microseconds.
  201. // Fraction of percent/100 of samples have latency lower or
  202. // equal to the value of this field.
  203. int64 latency_micros = 2;
  204. }
  205. // Describes measured latency distribution.
  206. message LatencyDistribution {
  207. // Representative latency percentiles.
  208. repeated LatencyPercentile latency_percentiles = 1;
  209. }
  210. // Results of active probing from the last run of the test.
  211. message ProbingDetails {
  212. // Overall probing result of the test.
  213. enum ProbingResult {
  214. // No result was specified.
  215. PROBING_RESULT_UNSPECIFIED = 0;
  216. // At least 95% of packets reached the destination.
  217. REACHABLE = 1;
  218. // No packets reached the destination.
  219. UNREACHABLE = 2;
  220. // Less than 95% of packets reached the destination.
  221. REACHABILITY_INCONSISTENT = 3;
  222. // Reachability could not be determined. Possible reasons are:
  223. // * The user lacks permission to access some of the network resources
  224. // required to run the test.
  225. // * No valid source endpoint could be derived from the request.
  226. // * An internal error occurred.
  227. UNDETERMINED = 4;
  228. }
  229. // Abort cause types.
  230. enum ProbingAbortCause {
  231. // No reason was specified.
  232. PROBING_ABORT_CAUSE_UNSPECIFIED = 0;
  233. // The user lacks permission to access some of the
  234. // network resources required to run the test.
  235. PERMISSION_DENIED = 1;
  236. // No valid source endpoint could be derived from the request.
  237. NO_SOURCE_LOCATION = 2;
  238. }
  239. // The overall result of active probing.
  240. ProbingResult result = 1;
  241. // The time that reachability was assessed through active probing.
  242. google.protobuf.Timestamp verify_time = 2;
  243. // Details about an internal failure or the cancellation of active probing.
  244. google.rpc.Status error = 3;
  245. // The reason probing was aborted.
  246. ProbingAbortCause abort_cause = 4;
  247. // Number of probes sent.
  248. int32 sent_probe_count = 5;
  249. // Number of probes that reached the destination.
  250. int32 successful_probe_count = 6;
  251. // The source and destination endpoints derived from the test input and used
  252. // for active probing.
  253. EndpointInfo endpoint_info = 7;
  254. // Latency as measured by active probing in one direction:
  255. // from the source to the destination endpoint.
  256. LatencyDistribution probing_latency = 8;
  257. }