Deploy workloads

Workload operator

A workload operator can pass options to a Confidential Space workload VM to determine its behavior before it runs. While some flags have required values that don't change, you still need to make the following choices:

Whether to base the VM on a production or debug Confidential Space image.
What VM metadata variables need to be passed, which include details like which workload container image to run, whether to log to Cloud Logging, and what environment variables to set.
What service account to attach to the VM to run the workload, and what permissions it needs to access confidential data in other projects and write the results somewhere.
What zone the VM instance should run in.

Here's an example that creates a Confidential VM in the us-west1-b zone based on the latest production Confidential Space image, and runs a Docker container called WORKLOAD_CONTAINER_NAME:

gcloud compute instances create workload-vm-name \
    --confidential-compute \
    --shielded-secure-boot \
    --image-project=confidential-space-images \
    --image-family=confidential-space \
    --metadata="^~^tee-image-reference=us-docker.pkg.dev/WORKLOAD_AUTHOR_PROJECT_ID/REPOSITORY_NAME/WORKLOAD_CONTAINER_NAME:latest" \
    --service-account=WORKLOAD_SERVICE_ACCOUNT_NAME@WORKLOAD_OPERATOR_PROJECT_ID.iam.gserviceaccount.com \
    --scopes=cloud-platform \
    --zone=us-west1-b

The options used in this example are detailed in the following table.

Flag	Description
`--confidential-compute`	Required. Tells Compute Engine to use a Confidential VM for the instance.
`--shielded-secure-boot`	Required. Tells Compute Engine to use Secure Boot for the instance.
`--image-project=confidential-space-images`	Required. Tells Compute Engine to look in the `confidential-space-images` project for the Confidential Space image.
`--image-family=confidential-space`	Required. Tells Compute Engine to use the latest production Confidential Space image, which is part of the `confidential-space-images` project. This production image must be used for your final workload that processes confidential data. To use the debug image for monitoring and debugging, set `image-family` to `confidential-space-debug` instead.
`--metadata`	Required. Changes the Confidential Space VM behavior by passing in variables. The `tee-image-reference` key and value is required and tells the VM instance to run the specified Docker container on top of the specified Confidential Space image. For the available key/value pairs, see Metadata variables.
`--service-account`	Optional. The service account attached to the VM instance that runs the workload, and impersonates service accounts attached to workload identity pools in other projects. If not specified, the default Compute Engine service account is used.
`--scopes=cloud-platform`	Required. Sets the access scope. The `cloud-platform` scope is an OAuth scope for most Google Cloud services, and lets the VM communicate with the attestation verifier.
`--zone`	Required. The zone the VM instance runs in. Confidential Space requires the following services, which are available in specific locations: Confidential VM Certificate Authority Service

Attached service account

A service account must be attached to a workload's Confidential VM to run the workload. The service account must be set up in the following way:

With the following roles:
- roles/confidentialcomputing.workloadUser to generate an attestation token.
- roles/artifactregistry.reader to retrieve a workload container image stored in Artifact Registry.
- roles/logging.logWriter if you want to redirect STDOUT and STDERR to Cloud Logging.
With read access to where the data collaborators store their confidential data, for example, a Cloud Storage bucket or BigQuery table.
With write access to where the workload should output the data, for example, a Cloud Storage bucket. Data collaborators should have read access to this location.

Additionally, data collaborators and workload operators need to set up the following things:

Data collaborators must add the service account to their workload identity pool provider as an attribute condition:

'WORKLOAD_SERVICE_ACCOUNT_NAME@DATA_COLLABORATOR_PROJECT_ID.iam.gserviceaccount.com' in assertion.google_service_accounts

The workload operator needs the roles/iam.serviceAccountUser role to impersonate the service account. This lets them attach it to a workload VM so it can run the workload.

Metadata variables

You can change the Confidential Space workload VM behavior by passing variables into the --metadata option when you create the VM.

To pass in multiple variables, first set the delimiter by prefixing the --metadata value with ^~^. This sets the delimiter to ~, as , is used in variable values.

For example:

metadata="^~^tee-restart-policy=Always~tee-image-reference=us-docker.pkg.dev/WORKLOAD_AUTHOR_PROJECT_ID/REPOSITORY_NAME/WORKLOAD_CONTAINER_NAME:latest"

The following table details the metadata variables you can set for your workload VM.

Metadata key Type Description and values

Metadata key	Type	Description and values
`tee-image-reference` Interacts with: Data collaborators: The `container.image_id` assertion.	String	Required. This points to the location of the workload container. Example `tee-image-reference=us-docker.pkg.dev/WORKLOAD_AUTHOR_PROJECT_ID/REPOSITORY_NAME/WORKLOAD_CONTAINER_NAME:latest`
`tee-cmd` Interacts with: Workload author: The `allow_cmd_override` launch policy. Data collaborators: The `container.cmd_override` assertion.	String array	Overrides the CMD instructions specified in the workload container's `Dockerfile`. Example `tee-cmd=['ls', 'cat ./file.txt']`
`tee-container-log-redirect` Interacts with: Workload author: The `log_redirect` launch policy.	Defined string	Outputs `STDOUT` and `STDERR` from the workload container to Cloud Logging or serial console, under the confidential-space-launcher field. The valid values are: `false`: (default) no logging occurs. `true`: outputs to the serial console and Cloud Logging. `cloud_logging`: outputs to Cloud Logging only. `serial`: outputs to the serial console only. A high log volume in the serial console might impact workload performance. Example `tee-container-log-redirect=true`
`tee-env-ENVIRONMENT_VARIABLE_NAME` Interacts with: Data collaborators: The `container.env` and `container.env_override` assertions.	String	Sets environment variables in the workload container. The workload author must also add the environment variable names to the `allow_env_override` launch policy, or they won't be set. Example `tee-env-example-env-1='value-1'~tee-env-example-env-2='value-2'`
`tee-impersonate-service-accounts` Interacts with: Data collaborators: The `google_service_accounts` assertion.	String	A list of service accounts that can be impersonated by the workload operator. The workload operator must be allowed to impersonate the service accounts. Multiple service accounts can be listed, separated by commas. Example `tee-impersonate-service-accounts=SERVICE_ACCOUNT_NAME_1@WORKLOAD_OPERATOR_PROJECT_ID.iam.gserviceaccount.com,SERVICE_ACCOUNT_NAME_2@WORKLOAD_OPERATOR_PROJECT_ID.iam.gserviceaccount.com`
`tee-monitoring-memory-enable` Interacts with: Data collaborators: The `instance_memory_monitoring_enabled` assertion. Workload author: The `monitoring_memory_allow` launch policy.	Boolean	Defaults to `false`. When set to `true`, enables memory usage monitoring. The metrics collected by the Confidential VM are of the `guest/memory/bytes_used` type, and can be viewed in Cloud Logging or Metrics Explorer. Example `tee-monitoring-memory-enable=true`
`tee-restart-policy` Interacts with: Data collaborators: The `container.restart_policy` assertion.	Defined string	The restart policy of the container launcher when the workload stops The valid values are: `Never` (default) `Always` `OnFailure` This variable is only supported by the production Confidential Space image. Example `tee-restart-policy=OnFailure`
`tee-signed-image-repos` Interacts with: Data collaborators: The `container.image_signatures` assertion.	String	A list of comma-separated container repositories that store the signatures that are generated by Sigstore Cosign. Example `tee-signed-image-repos=us-docker.pkg.dev/projectA/repo/example,us-docker.pkg.dev/projectB/repo/example,us-docker.pkg.dev/projectC/repo/example`

tee-image-reference

Interacts with:

Data collaborators: The container.image_id assertion.

String

Required. This points to the location of the workload container.

Example

tee-image-reference=us-docker.pkg.dev/WORKLOAD_AUTHOR_PROJECT_ID/REPOSITORY_NAME/WORKLOAD_CONTAINER_NAME:latest

tee-cmd

Interacts with:

Workload author: The allow_cmd_override launch policy.
Data collaborators: The container.cmd_override assertion.

String array

Overrides the CMD instructions specified in the workload container's Dockerfile.

Example

tee-cmd=['ls', 'cat ./file.txt']

tee-container-log-redirect

Interacts with:

Workload author: The log_redirect launch policy.

Defined string

Outputs STDOUT and STDERR from the workload container to Cloud Logging or serial console, under the confidential-space-launcher field.

The valid values are:

false: (default) no logging occurs.
true: outputs to the serial console and Cloud Logging.
cloud_logging: outputs to Cloud Logging only.
serial: outputs to the serial console only.

A high log volume in the serial console might impact workload performance.

Example

tee-container-log-redirect=true

tee-env-ENVIRONMENT_VARIABLE_NAME

Interacts with:

Data collaborators: The container.env and container.env_override assertions.

String

Sets environment variables in the workload container. The workload author must also add the environment variable names to the allow_env_override launch policy, or they won't be set.

Example

tee-env-example-env-1='value-1'~tee-env-example-env-2='value-2'

tee-impersonate-service-accounts

Interacts with:

Data collaborators: The google_service_accounts assertion.

String

A list of service accounts that can be impersonated by the workload operator. The workload operator must be allowed to impersonate the service accounts.

Multiple service accounts can be listed, separated by commas.

Example

tee-impersonate-service-accounts=SERVICE_ACCOUNT_NAME_1@WORKLOAD_OPERATOR_PROJECT_ID.iam.gserviceaccount.com,SERVICE_ACCOUNT_NAME_2@WORKLOAD_OPERATOR_PROJECT_ID.iam.gserviceaccount.com

tee-monitoring-memory-enable

Interacts with:

Data collaborators: The instance_memory_monitoring_enabled assertion.
Workload author: The monitoring_memory_allow launch policy.

Boolean

Defaults to false. When set to true, enables memory usage monitoring. The metrics collected by the Confidential VM are of the guest/memory/bytes_used type, and can be viewed in Cloud Logging or Metrics Explorer.

Example

tee-monitoring-memory-enable=true

tee-restart-policy

Interacts with:

Data collaborators: The container.restart_policy assertion.

Defined string

The restart policy of the container launcher when the workload stops

The valid values are:

Never (default)
Always
OnFailure

This variable is only supported by the production Confidential Space image.

Example

tee-restart-policy=OnFailure

tee-signed-image-repos

Interacts with:

Data collaborators: The container.image_signatures assertion.

String

A list of comma-separated container repositories that store the signatures that are generated by Sigstore Cosign.

Example

tee-signed-image-repos=us-docker.pkg.dev/projectA/repo/example,us-docker.pkg.dev/projectB/repo/example,us-docker.pkg.dev/projectC/repo/example

Scaling

For scaling and high availability of production Confidential Space workloads, see Managed Instance Groups.