docs: Operation.Type is now documented in detail

Google APIs · copybara-github · commit 427318085bad · 2023-04-21T07:17:25.000-07:00
docs: Operation.self_link and Operation.target_link given examples
feat: Cluster resizes will now have their own operation type (RESIZE_CLUSTER) instead of reusing REPAIR_CLUSTER; they will start using this in the near future

PiperOrigin-RevId: 526025502
diff --git a/google/container/v1/cluster_service.proto b/google/container/v1/cluster_service.proto
@@ -2108,58 +2108,125 @@ message Operation {
     ABORTING = 4;
   }
 
-  // Operation type.
+  // Operation type categorizes the operation.
   enum Type {
     // Not set.
     TYPE_UNSPECIFIED = 0;
 
-    // Cluster create.
+    // The cluster is being created. The cluster should be assumed to be
+    // unusable until the operation finishes.
+    //
+    // In the event of the operation failing, the cluster will enter the [ERROR
+    // state][Cluster.Status.ERROR] and eventually be deleted.
     CREATE_CLUSTER = 1;
 
-    // Cluster delete.
+    // The cluster is being deleted. The cluster should be assumed to be
+    // unusable as soon as this operation starts.
+    //
+    // In the event of the operation failing, the cluster will enter the [ERROR
+    // state][Cluster.Status.ERROR] and the deletion will be automatically
+    // retried until completed.
     DELETE_CLUSTER = 2;
 
-    // A master upgrade.
+    // The [cluster
+    // version][google.container.v1.ClusterUpdate.desired_master_version] is
+    // being updated. Note that this includes "upgrades" to the same version,
+    // which are simply a recreation. This also includes
+    // [auto-upgrades](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-upgrades#upgrading_automatically).
+    // For more details, see [documentation on cluster
+    // upgrades](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-upgrades#cluster_upgrades).
     UPGRADE_MASTER = 3;
 
-    // A node upgrade.
+    // A node pool is being updated. Despite calling this an "upgrade", this
+    // includes most forms of updates to node pools. This also includes
+    // [auto-upgrades](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades).
+    //
+    // This operation sets the
+    // [progress][google.container.v1.Operation.progress] field and may be
+    // [canceled][google.container.v1.ClusterManager.CancelOperation].
+    //
+    // The upgrade strategy depends on [node pool
+    // configuration](https://cloud.google.com/kubernetes-engine/docs/concepts/node-pool-upgrade-strategies).
+    // The nodes are generally still usable during this operation.
     UPGRADE_NODES = 4;
 
-    // Cluster repair.
+    // A problem has been detected with the control plane and is being repaired.
+    // This operation type is initiated by GKE. For more details, see
+    // [documentation on
+    // repairs](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions#repairs).
     REPAIR_CLUSTER = 5;
 
-    // Cluster update.
+    // The cluster is being updated. This is a broad category of operations and
+    // includes operations that only change metadata as well as those that must
+    // recreate the entire cluster. If the control plane must be recreated, this
+    // will cause temporary downtime for zonal clusters.
+    //
+    // Some features require recreating the nodes as well. Those will be
+    // recreated as separate operations and the update may not be completely
+    // functional until the node pools recreations finish. Node recreations will
+    // generally follow [maintenance
+    // policies](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions).
+    //
+    // Some GKE-initiated operations use this type. This includes certain types
+    // of auto-upgrades and incident mitigations.
     UPDATE_CLUSTER = 6;
 
-    // Node pool create.
+    // A node pool is being created. The node pool should be assumed to be
+    // unusable until this operation finishes. In the event of an error, the
+    // node pool may be partially created.
+    //
+    // If enabled, [node
+    // autoprovisioning](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-provisioning)
+    // may have automatically initiated such operations.
     CREATE_NODE_POOL = 7;
 
-    // Node pool delete.
+    // The node pool is being deleted. The node pool should be assumed to be
+    // unusable as soon as this operation starts.
     DELETE_NODE_POOL = 8;
 
-    // Set node pool management.
+    // The node pool's [manamagent][google.container.v1.NodePool.management]
+    // field is being updated. These operations only update metadata and may be
+    // concurrent with most other operations.
     SET_NODE_POOL_MANAGEMENT = 9;
 
-    // Automatic node pool repair.
+    // A problem has been detected with nodes and [they are being
+    // repaired](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair).
+    // This operation type is initiated by GKE, typically automatically. This
+    // operation may be concurrent with other operations and there may be
+    // multiple repairs occurring on the same node pool.
     AUTO_REPAIR_NODES = 10;
 
-    // Automatic node upgrade.
-    AUTO_UPGRADE_NODES = 11;
+    // Unused. Automatic node upgrade uses
+    // [UPGRADE_NODES][google.container.v1.Operation.Type.UPGRADE_NODES].
+    AUTO_UPGRADE_NODES = 11 [deprecated = true];
 
-    // Set labels.
-    SET_LABELS = 12;
+    // Unused. Updating labels uses
+    // [UPDATE_CLUSTER][google.container.v1.Operation.Type.UPDATE_CLUSTER].
+    SET_LABELS = 12 [deprecated = true];
 
-    // Set/generate master auth materials
-    SET_MASTER_AUTH = 13;
+    // Unused. Updating master auth uses
+    // [UPDATE_CLUSTER][google.container.v1.Operation.Type.UPDATE_CLUSTER].
+    SET_MASTER_AUTH = 13 [deprecated = true];
 
-    // Set node pool size.
+    // The node pool is being resized. With the exception of resizing to or from
+    // size zero, the node pool is generally usable during this operation.
     SET_NODE_POOL_SIZE = 14;
 
-    // Updates network policy for a cluster.
-    SET_NETWORK_POLICY = 15;
-
-    // Set the maintenance policy.
-    SET_MAINTENANCE_POLICY = 16;
+    // Unused. Updating network policy uses
+    // [UPDATE_CLUSTER][google.container.v1.Operation.Type.UPDATE_CLUSTER].
+    SET_NETWORK_POLICY = 15 [deprecated = true];
+
+    // Unused. Updating maintenance policy uses
+    // [UPDATE_CLUSTER][google.container.v1.Operation.Type.UPDATE_CLUSTER].
+    SET_MAINTENANCE_POLICY = 16 [deprecated = true];
+
+    // The control plane is being resized. This operation type is initiated by
+    // GKE. These operations are often performed preemptively to ensure that the
+    // control plane has sufficient resources and is not typically an indication
+    // of issues. For more details, see
+    // [documentation on
+    // resizes](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions#repairs).
+    RESIZE_CLUSTER = 18;
   }
 
   // The server-assigned ID for the operation.
@@ -2184,10 +2251,23 @@ message Operation {
   string status_message = 5
       [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Server-defined URL for the resource.
+  // Server-defined URI for the operation. Example:
+  // `https://container.googleapis.com/v1alpha1/projects/123/locations/us-central1/operations/operation-123`.
   string self_link = 6;
 
-  // Server-defined URL for the target of the operation.
+  // Server-defined URI for the target of the operation. The format of this is a
+  // URI to the resource being modified (such as a cluster, node pool, or node).
+  // For node pool repairs, there may be multiple nodes being repaired, but only
+  // one will be the target.
+  //
+  // Examples:
+  //
+  //   -
+  //   `https://container.googleapis.com/v1/projects/123/locations/us-central1/clusters/my-cluster`
+  //   -
+  //   `https://container.googleapis.com/v1/projects/123/zones/us-central1-c/clusters/my-cluster/nodePools/my-np`
+  //   -
+  //   `https://container.googleapis.com/v1/projects/123/zones/us-central1-c/clusters/my-cluster/nodePools/my-np/node/my-node`
   string target_link = 7;
 
   // [Output only] The name of the Google Compute Engine
@@ -4218,12 +4298,12 @@ message DatabaseEncryption {
     DECRYPTED = 2;
   }
 
-  // Denotes the state of etcd encryption.
-  State state = 2;
-
   // Name of CloudKMS key to use for the encryption of secrets in etcd.
   // Ex. projects/my-project/locations/global/keyRings/my-ring/cryptoKeys/my-key
   string key_name = 1;
+
+  // The desired state of etcd encryption.
+  State state = 2;
 }
 
 // ListUsableSubnetworksRequest requests the list of usable subnetworks
