自定义开发环境

本页面介绍了工作站配置参数，可用于自定义 Cloud Workstations 环境，包括虚拟机类型、主磁盘大小、基本容器映像等。在 API 中，这些工作站配置参数统称为 WorkstationConfig。

使用这些工作站配置参数之前，请先熟悉以下内容：

REST 资源：projects.locations.workstationClusters.workstationConfigs

资源：WorkstationConfig

Cloud Workstations API 中的工作站配置资源。

工作站配置充当着工作站的模板。工作站配置定义了一些详细信息，例如工作站虚拟机 (VM) 实例类型、永久性存储空间、容器映像定义环境、要使用的 IDE 或代码编辑器等。管理员和平台团队还可以使用 Identity and Access Management (IAM) 规则向团队或个人开发者授予访问权限。

JSON 表示法 

{
  "name": string,
  "displayName": string,
  "uid": string,
  "reconciling": boolean,
  "annotations": {
    string: string,
    ...
  },
  "labels": {
    string: string,
    ...
  },
  "createTime": string,
  "updateTime": string,
  "deleteTime": string,
  "etag": string,
  "idleTimeout": string,
  "runningTimeout": string,
  "host": {
    object (Host)
  },
  "persistentDirectories": [
    {
      object (PersistentDirectory)
    }
  ],
  "ephemeralDirectories": [
    {
      object (EphemeralDirectory)
    }
  ],
  "container": {
    object (Container)
  },
  "encryptionKey": {
    object (CustomerEncryptionKey)
  },
  "readinessChecks": [
    {
      object (ReadinessCheck)
    }
  ],
  "replicaZones": [
    string
  ],
  "degraded": boolean,
  "conditions": [
    {
      object (Status)
    }
  ],
  "enableAuditAgent": boolean,
  "disableTcpConnections": boolean
}
字段
name

string

标识符。此工作站配置的全名。
displayName

string

可选。此工作站配置的直观易懂的名称。
uid

string

仅供输出。系统为此工作站配置分配的唯一标识符。
reconciling

boolean

仅供输出。指示此工作站配置目前正在更新以匹配其预期状态。
annotations

map (key: string, value: string)

可选。客户端指定的注解。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
labels

map (key: string, value: string)

可选。应用于工作站配置以及传播到底层 Compute Engine 资源的标签。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
createTime

string (Timestamp format)

仅供输出。创建此工作站配置的时间。

采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式的时间戳，采用纳秒级精度，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

仅供输出。此工作站配置最近一次更新的时间。

采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式的时间戳，采用纳秒级精度，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
deleteTime

string (Timestamp format)

仅供输出。软删除此工作站配置的时间。

采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式的时间戳，采用纳秒级精度，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
etag

string

可选。服务器计算的校验和。可能会在更新和删除请求时发送，以确保客户端在继续操作之前具有最新的值。
idleTimeout

string (Duration format)

可选。工作站上次收到用户流量后，在自动关停工作站之前等待的秒数。

如果值为 "0s"，则表示使用此配置创建的 Cloud Workstations 虚拟机绝不会因空闲而超时。提供以 s 结尾的时长，表示秒，例如 "7200s"（2 小时）。默认值为 "1200s"（20 分钟）。

此时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
runningTimeout

string (Duration format)

可选。工作站在自动关闭之前可以运行的秒数。我们建议每天关停工作站以降低费用，以便在重启时应用安全更新。idleTimeout 和 runningTimeout 字段彼此独立。请注意，无论虚拟机是否处于空闲状态，runningTimeout 字段都会在指定时间后关停虚拟机。

提供以 s 结尾的秒数，例如 "54000s"（15 小时）。默认值为 "43200s"（12 小时）。值 "0s" 表示使用此配置的工作站绝不应超时。如果设置了 encryptionKey，则它必须大于 "0s" 且小于 "86400s"（24 小时）。

警告：值为 "0s" 表示使用此配置创建的 Cloud Workstations 虚拟机没有最长运行时间。强烈建议您不要这样做，因为这会产生费用，并且不会获取安全更新。

此时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
host

object (Host)

可选。工作站的运行时主机。
persistentDirectories[]

object (PersistentDirectory)

可选。可在工作站会话之间保留的目录。
ephemeralDirectories[]

object (EphemeralDirectory)

可选。不会在工作站会话之间保留的临时目录。
container

object (Container)

可选。使用此工作站配置为每个工作站在启动时运行的容器。
encryptionKey

object (CustomerEncryptionKey)

不可变。使用客户管理的加密密钥 (CMEK) 加密此工作站配置的资源。

如果指定，则 Compute Engine 实例的启动磁盘和永久性磁盘将使用此加密密钥进行加密。如果未设置此字段，则使用生成的密钥对磁盘进行加密。客户管理的加密密钥不会保护磁盘元数据。

如果轮替客户管理的加密密钥，则工作站实例停止时，系统会尝试使用新版本的密钥重新创建永久性磁盘。在重新创建永久性磁盘之前，请务必保留密钥的旧版本。否则，永久性磁盘上的数据可能会丢失。

如果加密密钥被撤消，工作站会话将在 7 小时内自动停止。

工作站配置创建后将不可变。
readinessChecks[]

object (ReadinessCheck)

可选。使用此工作站配置启动工作站时要执行的就绪性检查。仅当所有指定的就绪性检查都返回 200 状态代码后，才将工作站标记为正在运行。
replicaZones[]

string

可选。不可变。指定用于在区域内复制虚拟机和磁盘资源的可用区。如果设置了此项，则必须正好指定工作站集群所在区域内的两个可用区，例如 ['us-central1-a', 'us-central1-f']。如果此字段为空，系统会使用该区域内的两个默认可用区。

工作站配置创建后将不可变。
degraded

boolean

仅供输出。该资源是否会降级；在这种情况下，用户可能需要执行相关操作才能恢复完整功能。另请参阅 conditions 字段。
conditions[]

object (Status)

仅供输出。描述当前资源状态的状态条件。
enableAuditAgent

boolean

可选。是否在工作站上启用 Linux auditd 日志记录。启用后，还必须指定对项目具有 logging.buckets.write 权限的服务帐号。操作系统审核日志记录与 Cloud Audit Logs 不同。
disableTcpConnections

boolean

可选。在工作站中停用对普通 TCP 连接的支持。默认情况下，该服务支持通过 websocket 中继建立 TCP 连接。如果将此选项设为 true，系统会停用该中继，从而防止使用需要普通 TCP 连接的服务，如 SSH。启用后，所有通信都必须通过 HTTPS 或 WSS 进行。

主机

工作站的运行时主机。

JSON 表示法 

{

  // Union field config can be only one of the following:
  "gceInstance": {
    object (GceInstance)
  }
  // End of list of possible types for union field config.
}
字段
联合字段 config。工作站运行时使用的主机类型。config 只能是下列其中一项：
gceInstance

object (GceInstance)

将 Compute Engine 实例指定为主机。

GceInstance

使用 Compute Engine 实例的运行时。

JSON 表示法 

{
  "machineType": string,
  "serviceAccount": string,
  "serviceAccountScopes": [
    string
  ],
  "tags": [
    string
  ],
  "poolSize": integer,
  "pooledInstances": integer,
  "disablePublicIpAddresses": boolean,
  "enableNestedVirtualization": boolean,
  "shieldedInstanceConfig": {
    object (GceShieldedInstanceConfig)
  },
  "confidentialInstanceConfig": {
    object (GceConfidentialInstanceConfig)
  },
  "bootDiskSizeGb": integer,
  "accelerators": [
    {
      object (Accelerator)
    }
  ],
  "disableSsh": boolean
}
字段
machineType

string

可选。用于虚拟机实例的机器类型，例如 "e2-standard-4"。如需详细了解 Cloud Workstations 支持的机器类型，请参阅可用机器类型列表。
serviceAccount

string

可选。使用此配置创建的 Cloud Workstations 虚拟机的服务帐号的电子邮件地址。指定后，请确保服务帐号对项目具有 logginglogEntries.create 权限，以便它可以将日志写入 Cloud Logging。如果使用自定义容器映像，服务帐号必须具有 Artifact Registry Reader 权限才能拉取指定的映像。

如果您是管理员，希望能够ssh 到底层虚拟机，则需要将此值设置为您拥有 iam.serviceAccounts.actAs 权限的服务帐号。反之，如果您不希望任何人通过 ssh 访问底层虚拟机，请使用没有人具有该权限的服务帐号。

如果未设置，则虚拟机将使用 Cloud Workstations 服务提供的服务帐号运行，且映像必须可公开访问。
serviceAccountScopes[]

string

可选。要授予 serviceAccount 的范围。系统会根据功能使用情况自动添加各种范围。指定此配置时，工作站的用户必须对服务帐号拥有 iam.serviceAccounts.actAs。
tags[]

string

可选。要添加到为工作站提供支持的 Compute Engine 虚拟机的网络标记。此选项会将网络标记应用于使用此配置创建的虚拟机。这些网络标记允许创建防火墙规则。
poolSize

integer

可选。系统应保持空闲状态的虚拟机数量，以便新用户能够快速启动新的工作站。在 API 中默认为 0。
pooledInstances

integer

仅供输出。池中当前可用的实例数，以加快工作站启动速度。
disablePublicIpAddresses

boolean

可选。设置为 true 时，系统会停用虚拟机的公共 IP 地址。如果您停用公共 IP 地址，则必须在自己的网络上设置专用 Google 访问通道或 Cloud NAT。如果您使用专用 Google 访问通道，并将 private.googleapis.com 或 restricted.googleapis.com 用于 Container Registry 和 Artifact Registry，请务必为网域 *.gcr.io 和 *.pkg.dev 设置 DNS 记录。默认值为 false（虚拟机具有公共 IP 地址）。
enableNestedVirtualization

boolean

可选。是否对使用此工作站配置创建的 Cloud Workstations 虚拟机启用嵌套虚拟化。

利用嵌套虚拟化，您可以在工作站内运行虚拟机 (VM) 实例。在启用嵌套虚拟化之前，请考虑以下重要注意事项。Cloud Workstations 实例受到与 Compute Engine 实例相同的限制：

  • 组织政策：如果在组织政策中强制执行停用虚拟机嵌套虚拟化限制条件，项目、文件夹或组织可能无法创建嵌套虚拟机。如需了解详情，请参阅 Compute Engine 的检查是否允许嵌套虚拟化部分。
  • 性能：对于受 CPU 限制的工作负载而言，嵌套虚拟机的性能可能会降低 10% 或更大；对于受输入/输出限制的工作负载来说，其性能可能会下降 10% 以上。
  • 机器类型：嵌套虚拟化只能在 N1 或 N2 机器系列中指定 machineType 的工作站配置中启用。
  • GPU：对于带有加速器的工作站配置，嵌套虚拟化可能未启用。
  • 操作系统：由于 Container-Optimized OS 不支持嵌套虚拟化，因此启用嵌套虚拟化后，底层 Compute Engine 虚拟机实例会从 Ubuntu LTS 映像启动。
shieldedInstanceConfig

object (GceShieldedInstanceConfig)

可选。一组 Compute Engine 安全强化型实例选项。
confidentialInstanceConfig

object (GceConfidentialInstanceConfig)

可选。一组 Compute Engine 机密虚拟机实例选项。
bootDiskSizeGb

integer

可选。虚拟机的启动磁盘大小，以千兆字节 (GB) 为单位。启动磁盘大小下限为 30 GB。默认值为 50 GB。
accelerators[]

object (Accelerator)

可选。附加到实例的加速器卡的类型和数量列表。
disableSsh

boolean

可选。是否停用对虚拟机的 SSH 访问权限。

GceShieldedInstanceConfig

一组 Compute Engine 安全强化型实例选项。

JSON 表示法 

{
  "enableSecureBoot": boolean,
  "enableVtpm": boolean,
  "enableIntegrityMonitoring": boolean
}
字段
enableSecureBoot

boolean

可选。实例是否启用了安全启动。
enableVtpm

boolean

可选。实例是否已启用 vTPM。
enableIntegrityMonitoring

boolean

可选。实例是否启用了完整性监控。

GceConfidentialInstanceConfig

一组 Compute Engine 机密虚拟机实例选项。

JSON 表示法 

{
  "enableConfidentialCompute": boolean
}
字段
enableConfidentialCompute

boolean

可选。实例是否启用了机密计算。

加速器

附加到实例的加速器卡。

JSON 表示法 

{
  "type": string,
  "count": integer
}
字段
type

string

可选。要挂接到实例的加速器资源类型，例如 "nvidia-tesla-p100"。
count

integer

可选。向实例公开的加速卡数量。

PersistentDirectory

跨工作站会话持久保留的目录。

JSON 表示法 

{
  "mountPath": string,

  // Union field directory_type can be only one of the following:
  "gcePd": {
    object (GceRegionalPersistentDisk)
  }
  // End of list of possible types for union field directory_type.
}
字段
mountPath

string

可选。此目录在正在运行的工作站中的位置。
联合字段 directory_type。应如何实现永久性目录。directory_type 只能是下列其中一项：
gcePd

object (GceRegionalPersistentDisk)

由 Compute Engine 永久性磁盘提供支持的 PersistentDirectory。

GceRegionalPersistentDisk

由 Compute Engine 区域永久性磁盘提供支持的永久性目录。persistentDirectories 字段是重复的，但它可能只包含一个条目。它会创建一个永久性磁盘，该磁盘在会话启动时 /home 装载到工作站虚拟机，并在会话结束时分离出来。如果此字段为空，则表示使用此配置创建的工作站没有永久性主目录。

JSON 表示法 

{
  "sizeGb": integer,
  "fsType": string,
  "diskType": string,
  "sourceSnapshot": string,
  "reclaimPolicy": enum (ReclaimPolicy)
}
字段
sizeGb

integer

可选。使用此配置创建的每个工作站的永久性主目录的容量（以 GB 为单位）。如果设置了 sourceSnapshot，则必须为空。

有效值为 10、50、100、200、500 或 1000。默认值为 200。如果小于 200 GB，则 diskType 必须为 "pd-balanced" 或 "pd-ssd"。
fsType

string

可选。用于格式化磁盘的文件系统类型。工作站映像必须支持此文件系统类型。如果设置了 sourceSnapshot，则必须为空。默认值为 "ext4"。
diskType

string

可选。主目录的永久性磁盘类型。默认值为 "pd-standard"。
sourceSnapshot

string

可选。要用作磁盘来源的快照的名称。如果设置了此字段，则 sizeGb 和 fsType 必须为空。
reclaimPolicy

enum (ReclaimPolicy)

可选。删除工作站时，是否应删除永久性磁盘。有效值为 DELETE 和 RETAIN。默认值为 DELETE。

ReclaimPolicy

该值表示删除工作站后磁盘应执行的操作。

枚举
RECLAIM_POLICY_UNSPECIFIED 请勿使用。
DELETE 删除工作站时，请删除永久性磁盘。
RETAIN 删除工作站时，请保留永久性磁盘。管理员必须手动删除磁盘。

EphemeralDirectory

不会在工作站会话之间持久保留的临时目录。系统会在每次工作站启动操作时重新创建此临时实例。

JSON 表示法 

{
  "mountPath": string,

  // Union field directory_type can be only one of the following:
  "gcePd": {
    object (GcePersistentDisk)
  }
  // End of list of possible types for union field directory_type.
}
字段
mountPath

string

必需。此目录在正在运行的工作站中的位置。
联合字段 directory_type。临时目录应如何实现。directory_type 只能是下列其中一项：
gcePd

object (GcePersistentDisk)

由 Compute Engine 永久性磁盘提供支持的 EphemeralDirectory。

GcePersistentDisk

EphemeralDirectory 由 Compute Engine 永久性磁盘提供支持。

JSON 表示法 

{
  "diskType": string,
  "sourceSnapshot": string,
  "sourceImage": string,
  "readOnly": boolean
}
字段
diskType

string

可选。要使用的磁盘类型。默认值为 "pd-standard"。
sourceSnapshot

string

可选。要用作磁盘来源的快照的名称。如果设置了 sourceImage，则必须为空。如果 readOnly 为 false，则必须为空。更新 sourceSnapshot 将在工作站重启后更新临时目录中的内容。此字段可更改。
sourceImage

string

可选。要用作磁盘来源的磁盘映像的名称。如果设置了 sourceSnapshot，则必须为空。更新 sourceImage 将在工作站重启后更新临时目录中的内容。此字段可更改。
readOnly

boolean

可选。磁盘是否处于只读状态。如果为 true，则磁盘可以由多个虚拟机共享，并且必须设置 sourceSnapshot。

容器

一个 Docker 容器。

JSON 表示法 

{
  "image": string,
  "command": [
    string
  ],
  "args": [
    string
  ],
  "env": {
    string: string,
    ...
  },
  "workingDir": string,
  "runAsUser": integer
}
字段
image

string

可选。用于定义自定义环境的 Docker 容器映像。

Cloud Workstations 提供了许多预配置的映像，但您可以创建自己的自定义容器映像。如果使用私有映像，必须在工作站配置中指定 host.gceInstance.serviceAccount 字段。如果使用自定义容器映像，服务帐号必须具有 Artifact Registry Reader 权限才能拉取指定的映像。否则，相应图片必须可公开访问。
command[]

string

可选。如果设置了此字段，则会替换映像指定的默认 ENTRYPOINT。
args[]

string

可选。传递给入口点的参数。
env

map (key: string, value: string)

可选。传递给容器的入口点的环境变量。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
workingDir

string

可选。如果设置了此字段，则会替换映像指定的默认 DIR。
runAsUser

integer

可选。如果设置了此字段，则会使用给定 UID 替换映像中指定的 USER。

CustomerEncryptionKey

关联工作站配置的 Compute Engine 资源的客户管理的加密密钥 (CMEK)。指定 Cloud KMS 加密密钥的名称和默认服务帐号。我们建议您使用单独的服务帐号，并遵循 Cloud KMS 最佳实践。

JSON 表示法 

{
  "kmsKey": string,
  "kmsKeyServiceAccount": string
}
字段
kmsKey

string

不可变。Google Cloud KMS 加密密钥的名称。例如 "projects/PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"。密钥必须与工作站配置位于同一区域。
kmsKeyServiceAccount

string

不可变。要与指定的 KMS 密钥搭配使用的服务帐号。我们建议您使用单独的服务帐号并遵循 KMS 最佳实践。如需了解详情，请参阅职责分离和 gcloud kms keys add-iam-policy-binding --member。

ReadinessCheck

将在工作站上执行的就绪性检查。

JSON 表示法 

{
  "path": string,
  "port": integer
}
字段
path

string

可选。请求应发送到的路径。
port

integer

可选。应向其发送请求的端口。

方法

create

 创建新的工作站配置。

delete

 删除指定的工作站配置。

get

 返回请求的工作站配置。

getIamPolicy

 获取资源的访问权限控制政策。

list

 返回指定集群中的所有工作站配置。

listUsable

 返回调用方具有“workstations.workstation.create”权限的指定集群中的所有工作站配置。

patch

 更新现有工作站配置。

setIamPolicy

 设置对指定资源的访问权限控制政策。

testIamPermissions

 返回调用者对指定资源拥有的权限。