Working with Confidential Space images

The Confidential Space image that runs the workload is a minimal, single-purpose OS. It's built on the existing security enhancements of Container-Optimized OS, and adds the following benefits:

  • Encrypted disk partitions with integrity protection

  • Authenticated, encrypted network connections

  • Various boot measurements

  • Disabled remote access and cloud-specific tooling

  • Reduced state transitions

Types of Confidential Space images

The Confidential Space image is available in two variants: production and debug. The debug version is considered insecure, and is used for testing your workload on non-production data. It differs from the production image in the following ways:

  • SSH is enabled.

  • The operator has root access to the VM that runs the workload.

  • The VM instance running the debug image doesn't stop after the workload is complete.

To learn more about specifying which image to use, see VM options and metadata.

Confidential Space image lifecycle

When you create a Confidential VM using the Confidential Space image, the latest version of the image is used. If you always delete your Confidential VM when your workload is done and create a new one each time you run the workload, then you can be sure of the image being up to date each time you run the workload.

However, long-running workloads or running a workload on a VM created in the past opens you up to the risk of using old versions of the Confidential Space image, which might introduce security vulnerabilities.

As a data collaborator, you can prevent workloads from accessing your data unless they're running on the latest production Confidential Space image. To do so, add the support_attributes assertion to your workload identity pool provider.

To view Confidential Space image versions, see Image versions.

Workloads and reproducible container images

A workload can be added via Docker or other container software. Building a container image in a reproducible way can help to increase trust between parties. If you're using Docker, you can build reproducible images for it with Bazel.

Disk and memory limits

The total disk space available to Confidential Space is around 7GB. This includes the workload image and anything written to disk during the workload.

Make sure to keep within VM memory limits. Swap memory is disabled on Confidential Space VMs, which means excessive memory use can crash the workload.

Multiple workload runs

To ensure a clean environment, a VM must be restarted to restart a workload. This encrypts the VM disk with an ephemeral key, to address the attack vector of modifying a workload image on the disk after it has been downloaded and measured.

This also adds overheads like boot time and pulling the workload image to each workload run. If these overheads impact your workload's performance too much, you can code a workload restart into the workload itself, at the cost of increasing your risk profile.

Expired OIDC tokens

An OIDC token is made available for your workload to consume when it starts. It contains verified attestation claims about your workload's VM, and is stored in the workload container at /run/container_launcher/attestation_verifier_claims_token. The token expires after 60 minutes.

If the token expires, a refresh is attempted in the background using exponential backoff until it succeeds. If a refresh fails (due to network issues, an attestation service outage, or otherwise), your workload code needs to be able to handle that failure.

Your workload could handle a token refresh failure in one of the following ways:

  • Ignore the expired token, assuming it's no longer required after the initial use.
  • Wait for the expired token to be refreshed successfully.
  • Exit the workload.


Like any command line program, the workload stdout and stderr can be displayed in the console running the workload. This can optionally be hidden from the operator through the log_redirect launch policy.

Additionally, the workload stdout and stderr can be redirected to Cloud Logging by setting the tee-container-log-redirect metadata key to true on the Confidential Space VM, and ensuring the service account running the workload has the logging.logWriter role.

To reduce your risk profile, log the minimum amount of information, and don't log sensitive information.

Return codes

Like other stdout and stderr content, return codes are displayed in the console when running the launcher and workload, and can be redirected to Cloud Logging.

The return codes are described in the following table:

Code Definition VM stop behavior
0 The workload completed successfully when using the production image. The VM stops after the workload is complete.
1 The workload or launcher returned an error when using the production image. The VM stops after it has returned an error.
3 The launcher has restarted after a failure due to its tee-restart-policy. The VM is restarted.
4 The workload or launcher has finished running when using the debug image, and the VM is now idling. The VM doesn't stop after the workload completes or returns an error. This is so you can debug their workload over SSH.

If a workload fails, a workload operator only receives the message workload finished with a non-zero return code, without further context. For a production image, the launcher can be set to restart on failure with tee-restart-policy=OnFailure.

Launch policies

When building a workload you can specify policies that override VM metadata variables, that restrict the capability of a malicious operator.

Launch policies are set as a label. For example, in a Dockerfile:

LABEL: "tee.launch_policy.allow_cmd_override"="true"

In a Bazel BUILD file:


The available launch policies are in the following table:

Policy Value Description
tee.launch_policy.allow_cmd_override Boolean (default is false) Determines if the CMD specified in the Dockerfile can be overridden by the tee-cmd metadata value.
tee.launch_policy.allow_env_override Comma separated string A comma separated string of environment variable names that are allowed to be overwritten by the tee-env-ENVIRONMENT_VARIABLE_NAME metadata values.
tee.launch_policy.log_redirect debugonly (default), always, or never

Determines how logging works if `tee-container-log-redirect` is set to true.

  • debugonly: only allow stdout and stderr redirects when using a debug image.
  • always: always allow stdout and stderr redirects.
  • never: never allow stdout and stderr redirects.