feat: add output field for the control plane IP address

feat: add output field for the number of pooled instances feat: add support for accelerators feat: add support for readiness checks feat: add auditd support feat: add support for workstation-level environment variables docs: adjust documentation wording PiperOrigin-RevId: 531290149
2 years ago · d6a61ef1cf
parent 3d497fa928
commit d6a61ef1cf
3 changed files with 144 additions and 47 deletions
--- a/google/cloud/workstations/v1beta/workstations.proto
+++ b/google/cloud/workstations/v1beta/workstations.proto
@ -175,7 +175,7 @@ service Workstations {
    option (google.api.method_signature) = "name";
  }

-  // Returns all Workstations using the specified config.
+  // Returns all Workstations using the specified workstation configuration.
  rpc ListWorkstations(ListWorkstationsRequest)
      returns (ListWorkstationsResponse) {
    option (google.api.http) = {
@ -184,8 +184,8 @@ service Workstations {
    option (google.api.method_signature) = "parent";
  }

-  // Returns all Workstations using the specified config on which the caller has
-  // the "workstations.workstations.use" permission.
+  // Returns all workstations using the specified workstation configuration
+  // on which the caller has the "workstations.workstations.use" permission.
  rpc ListUsableWorkstations(ListUsableWorkstationsRequest)
      returns (ListUsableWorkstationsResponse) {
    option (google.api.http) = {
@ -343,7 +343,7 @@ message WorkstationCluster {
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Checksum computed by the server. May be sent on update and delete requests
-  // to ensure that the client has an up-to-date value before proceeding.
+  // to make sure that the client has an up-to-date value before proceeding.
  string etag = 9;

  // Immutable. Name of the Compute Engine network in which instances associated
@ -355,6 +355,12 @@ message WorkstationCluster {
  // subnetwork specified for this cluster.
  string subnetwork = 11 [(google.api.field_behavior) = IMMUTABLE];

+  // Output only. The private IP address of the control plane for this cluster.
+  // Workstation VMs need access to this IP address to work with the service, so
+  // make sure that your firewall rules allow egress from the workstation VMs to
+  // this address.
+  string control_plane_ip = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
+
  // Configuration for private cluster.
  PrivateClusterConfig private_cluster_config = 12;

@ -400,6 +406,16 @@ message WorkstationConfig {
        bool enable_confidential_compute = 1;
      }

+      // An accelerator card attached to the instance.
+      message Accelerator {
+        // Type of accelerator resource to attach to the instance, for example,
+        // "nvidia-tesla-p100".
+        string type = 1;
+
+        // Number of accelerator cards exposed to the instance.
+        int32 count = 2;
+      }
+
      // The name of a Compute Engine machine type.
      string machine_type = 1;

@ -414,9 +430,13 @@ message WorkstationConfig {
      // Workstations.
      repeated string tags = 4;

-      // Number of instances to pool for faster workstation starup.
+      // Number of instances to pool for faster workstation startup.
      int32 pool_size = 5;

+      // Output only. Number of instances currently available in the pool for
+      // faster workstation startup.
+      int32 pooled_instances = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
+
      // Whether instances have no public IP address.
      bool disable_public_ip_addresses = 6;

@ -426,8 +446,12 @@ message WorkstationConfig {
      // A set of Compute Engine Confidential VM instance options.
      GceConfidentialInstanceConfig confidential_instance_config = 10;

-      // Size of the boot disk in GB.
+      // Size of the boot disk in GB. Defaults to 50.
      int32 boot_disk_size_gb = 9;
+
+      // A list of the type and count of accelerator cards attached to the
+      // instance.
+      repeated Accelerator accelerators = 11;
    }

    // Type of host that will be used for the workstation's runtime.
@ -457,14 +481,15 @@ message WorkstationConfig {
      }

      // Size of the disk in GB. Must be empty if source_snapshot is set.
+      // Defaults to 200.
      int32 size_gb = 1;

      // Type of file system that the disk should be formatted with. The
      // workstation image must support this file system type. Must be empty
-      // if source_snapshot is set.
+      // if source_snapshot is set. Defaults to ext4.
      string fs_type = 2;

-      // Type of the disk to use.
+      // Type of the disk to use. Defaults to pd-standard.
      string disk_type = 3;

      // Name of the snapshot to use as the source for the disk. If set,
@ -489,7 +514,7 @@ message WorkstationConfig {
  // A Docker container.
  message Container {
    // Docker image defining the container. This image must be accessible by the
-    // config's service account.
+    // service account specified in the workstation configuration.
    string image = 1;

    // If set, overrides the default ENTRYPOINT specified by the image.
@ -498,7 +523,7 @@ message WorkstationConfig {
    // Arguments passed to the entrypoint.
    repeated string args = 3;

-    // Environment variables passed to the container.
+    // Environment variables passed to the container's entrypoint.
    map<string, string> env = 4;

    // If set, overrides the default DIR specified by the image.
@ -511,18 +536,28 @@ message WorkstationConfig {
  // A customer-managed encryption key for the Compute Engine resources
  // of this workstation configuration.
  message CustomerEncryptionKey {
-    // The name of the Google Cloud KMS encryption key. For example,
+    // Immutable. The name of the Google Cloud KMS encryption key. For example,
    // `projects/PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY_NAME`.
-    string kms_key = 1;
+    string kms_key = 1 [(google.api.field_behavior) = IMMUTABLE];

-    // The service account to use with the specified
+    // Immutable. The service account to use with the specified
    // KMS key. We recommend that you use a separate service account
    // and follow KMS best practices. For more information, see
    // [Separation of
    // duties](https://cloud.google.com/kms/docs/separation-of-duties) and
    // `gcloud kms keys add-iam-policy-binding`
    // [`--member`](https://cloud.google.com/sdk/gcloud/reference/kms/keys/add-iam-policy-binding#--member).
-    string kms_key_service_account = 2;
+    string kms_key_service_account = 2
+        [(google.api.field_behavior) = IMMUTABLE];
+  }
+
+  // A readiness check to be performed on a workstation.
+  message ReadinessCheck {
+    // Path to which the request should be sent.
+    string path = 1;
+
+    // Port to which the request should be sent.
+    int32 port = 2;
  }

  // Full name of this resource.
@ -558,7 +593,7 @@ message WorkstationConfig {
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Checksum computed by the server. May be sent on update and delete requests
-  // to ensure that the client has an up-to-date value before proceeding.
+  // to make sure that the client has an up-to-date value before proceeding.
  string etag = 9;

  // How long to wait before automatically stopping an instance that hasn't
@ -582,7 +617,7 @@ message WorkstationConfig {
  // when that workstation is started.
  Container container = 14;

-  // Encrypts resources of this workstation configuration using a
+  // Immutable. Encrypts resources of this workstation configuration using a
  // customer-managed encryption key.
  //
  // If specified, the boot disk of the Compute Engine instance and the
@ -598,7 +633,15 @@ message WorkstationConfig {
  //
  // If the encryption key is revoked, the workstation session will
  // automatically be stopped within 7 hours.
-  CustomerEncryptionKey encryption_key = 17;
+  //
+  // Immutable after the workstation configuration is created.
+  CustomerEncryptionKey encryption_key = 17
+      [(google.api.field_behavior) = IMMUTABLE];
+
+  // Readiness checks to perform when starting a workstation using this
+  // workstation configuration. Mark a workstation as running only after all
+  // specified readiness checks return 200 status codes.
+  repeated ReadinessCheck readiness_checks = 19;

  // Output only. Whether this resource is in degraded mode, in which case it
  // may require user action to restore full functionality. Details can be found
@ -608,6 +651,13 @@ message WorkstationConfig {
  // Output only. Status conditions describing the current resource state.
  repeated google.rpc.Status conditions = 16
      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Whether to enable linux auditd logging on the workstation. When enabled, a
+  // service account must also be specified that has logging.buckets.write
+  // permission on the project. Operating system audit logging is distinct from
+  // [Cloud Audit
+  // Logs](https://cloud.google.com/workstations/docs/audit-logging).
+  bool enable_audit_agent = 20;
 }

 // A single instance of a developer workstation with its own persistent storage.
@ -671,7 +721,7 @@ message Workstation {
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Checksum computed by the server. May be sent on update and delete requests
-  // to ensure that the client has an up-to-date value before proceeding.
+  // to make sure that the client has an up-to-date value before proceeding.
  string etag = 9;

  // Output only. Current state of the workstation.
@ -683,6 +733,9 @@ message Workstation {
  // clients may prefix the host with the destination port in the format
  // `{port}-{host}`.
  string host = 11 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Environment variables passed to the workstation container's entrypoint.
+  map<string, string> env = 12;
 }

 // Request message for GetWorkstationCluster.
@ -782,7 +835,7 @@ message DeleteWorkstationClusterRequest {
  bool validate_only = 2;

  // If set, the request will be rejected if the latest version of the
-  // workstation cluster on the server does not have this etag.
+  // workstation cluster on the server does not have this ETag.
  string etag = 3;

  // If set, any workstation configurations and workstations in the
@ -872,7 +925,7 @@ message CreateWorkstationConfigRequest {
    }
  ];

-  // Required. ID to use for the config.
+  // Required. ID to use for the workstation configuration.
  string workstation_config_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. Config to create.
@ -890,7 +943,8 @@ message UpdateWorkstationConfigRequest {
  WorkstationConfig workstation_config = 1
      [(google.api.field_behavior) = REQUIRED];

-  // Required. Mask specifying which fields in the config should be updated.
+  // Required. Mask specifying which fields in the workstation configuration
+  // should be updated.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = REQUIRED];

@ -898,14 +952,15 @@ message UpdateWorkstationConfigRequest {
  // apply it.
  bool validate_only = 3;

-  // If set, and the config is not found, a new config will be created.
-  // In this situation, update_mask is ignored.
+  // If set and the workstation configuration is not found, a new
+  // workstation configuration will be created. In this situation,
+  // update_mask is ignored.
  bool allow_missing = 4;
 }

 // Message for deleting a workstation configuration.
 message DeleteWorkstationConfigRequest {
-  // Required. Name of the config to delete.
+  // Required. Name of the workstation configuration to delete.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
@ -917,12 +972,13 @@ message DeleteWorkstationConfigRequest {
  // apply it.
  bool validate_only = 2;

-  // If set, the request will be rejected if the latest version of the config on
-  // the server does not have this etag.
+  // If set, the request is rejected if the latest version of the
+  // workstation configuration on the server does not have this ETag.
  string etag = 3;

-  // If set, any Workstations in the config will also be deleted. Otherwise,
-  // the request will work only if the config has no workstations.
+  // If set, any workstations in the workstation configuration are also deleted.
+  // Otherwise, the request works only if the workstation configuration has
+  // no workstations.
  bool force = 4;
 }

@ -1023,7 +1079,8 @@ message UpdateWorkstationRequest {
  // Required. Workstation to update.
  Workstation workstation = 1 [(google.api.field_behavior) = REQUIRED];

-  // Required. Mask specifying which fields in the config should be updated.
+  // Required. Mask specifying which fields in the workstation configuration
+  // should be updated.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = REQUIRED];

@ -1031,8 +1088,9 @@ message UpdateWorkstationRequest {
  // apply it.
  bool validate_only = 3;

-  // If set, and the config is not found, a new config will be created.
-  // In this situation, update_mask is ignored.
+  // If set and the workstation configuration is not found, a new
+  // workstation configuration is created. In this situation, update_mask
+  // is ignored.
  bool allow_missing = 4;
 }

@ -1051,7 +1109,7 @@ message DeleteWorkstationRequest {
  bool validate_only = 2;

  // If set, the request will be rejected if the latest version of the
-  // workstation on the server does not have this etag.
+  // workstation on the server does not have this ETag.
  string etag = 3;
 }

@ -1070,7 +1128,7 @@ message StartWorkstationRequest {
  bool validate_only = 2;

  // If set, the request will be rejected if the latest version of the
-  // workstation on the server does not have this etag.
+  // workstation on the server does not have this ETag.
  string etag = 3;
 }

@ -1089,7 +1147,7 @@ message StopWorkstationRequest {
  bool validate_only = 2;

  // If set, the request will be rejected if the latest version of the
-  // workstation on the server does not have this etag.
+  // workstation on the server does not have this ETag.
  string etag = 3;
 }

@ -1123,7 +1181,7 @@ message GenerateAccessTokenRequest {
 message GenerateAccessTokenResponse {
  // The generated bearer access token. To use this token, include it in an
  // Authorization header of an HTTP request sent to the associated
-  // workstation's hostname, for example, `Authorization: Bearer
+  // workstation's hostname—for example, `Authorization: Bearer
  // <access_token>`.
  string access_token = 1;

--- a/google/cloud/workstations/v1beta/workstations_grpc_service_config.json
+++ b/google/cloud/workstations/v1beta/workstations_grpc_service_config.json
@ -9,7 +9,16 @@
      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "ListUsableWorkstations" },
      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "ListWorkstationClusters" },
      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "ListWorkstationConfigs" },
-      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "ListWorkstations" }
+      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "ListWorkstations" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "GenerateAccessToken" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "GetWorkstation" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "GetWorkstationCluster" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "GetWorkstationConfig" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "ListUsableWorkstationConfigs" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "ListUsableWorkstations" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "ListWorkstationClusters" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "ListWorkstationConfigs" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "ListWorkstations" }
    ],
    "timeout": "60s",
    "retryPolicy": {
@ -32,7 +41,18 @@
      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "StopWorkstation" },
      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "UpdateWorkstation" },
      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "UpdateWorkstationCluster" },
-      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "UpdateWorkstationConfig" }
+      { "service": "google.cloud.workstations.v1beta.Workstations", "method": "UpdateWorkstationConfig" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "CreateWorkstation" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "CreateWorkstationCluster" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "CreateWorkstationConfig" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "DeleteWorkstation" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "DeleteWorkstationCluster" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "DeleteWorkstationConfig" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "StartWorkstation" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "StopWorkstation" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "UpdateWorkstation" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "UpdateWorkstationCluster" },
+      { "service": "google.cloud.workstations.v1.Workstations", "method": "UpdateWorkstationConfig" }
    ],
    "timeout": "60s"
  }]
--- a/google/cloud/workstations/v1beta/workstations_v1beta.yaml
+++ b/google/cloud/workstations/v1beta/workstations_v1beta.yaml
@ -13,6 +13,7 @@ types:
 - name: google.cloud.workstations.v1beta.OperationMetadata

 documentation:
+  summary: Allows administrators to create managed developer environments in the cloud.
  rules:
  - selector: google.cloud.location.Locations.GetLocation
    description: Gets information about a location.
@ -108,20 +109,38 @@ authentication:
        https://www.googleapis.com/auth/cloud-platform

 publishing:
-  organization: CLOUD
-  new_issue_uri: 'https://issuetracker.google.com/issues/new?component=1328344'
-  documentation_uri: 'https://cloud.google.com/workstations/docs'
-  api_short_name: 'workstations'
+  new_issue_uri: https://issuetracker.google.com/issues/new?component=1328344
+  documentation_uri: https://cloud.google.com/workstations/docs
+  api_short_name: workstations
  github_label: 'api: workstations'
-  doc_tag_prefix: 'workstations'
-  codeowner_github_teams:
+  doc_tag_prefix: workstations
+  organization: CLOUD
  library_settings:
-  - version: 'google.cloud.workstations.v1beta'
+  - version: google.cloud.workstations.v1
+    launch_stage: GA
+    java_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    cpp_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    python_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    node_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+    go_settings:
+      common:
+        destinations:
+        - PACKAGE_MANAGER
+  - version: google.cloud.workstations.v1beta
    launch_stage: BETA
-    rest_numeric_enums: false
    java_settings:
-      library_package: ''
-      service_class_names:
      common:
        destinations:
        - PACKAGE_MANAGER