Polaris on Google Cloud
This page explains how Polaris works on Google Cloud and why it is built the way it is. Read Deploying Polaris first for the choices common to every cloud.
To deploy and run your own workload, use the how-to guides, and to look up a machine type, a permission or a config key, use the GCP reference. The reference also lists what Polaris offers on GCP today and what is still to come.
The shape of a deployment
A deployment is two confidential VMs in a VPC network of their own, together with a Cloud KMS key the deployment creates in your project.
- The workload VM runs your container, with the Polaris proxy in front of it and the Sentinel agent beside it.
- The Policy Manager VM checks the evidence the workload VM sends and decides whether the workload keeps access to the key.
The Policy Manager runs on its own VM so that the machine judging the evidence is separate from the machine producing it. It always runs on AMD SEV-SNP, whichever TEE the workload VM uses, and the workload VM's proxy checks its hardware report before trusting any verdict from it. That check shows a genuine SEV-SNP VM of the right shape, as What the hardware report proves explains, and not on its own that the VM is your Policy Manager.
Both VMs run in the zone you choose. The workload VM takes a reserved external address, which stays the same when the VM is replaced. The Policy Manager has no external address, and you reach it through IAP or through the workload VM's endpoint.
Choosing the TEE
tee.cpu | Hardware | Default machine type |
|---|---|---|
sev-snp-direct | AMD SEV-SNP | n2d-standard-4 |
sev-snp-svsm | AMD SEV-SNP with an SVSM and its vTPM | n2d-standard-4 |
tdx | Intel TDX | c3-standard-4 |
sev-snp-directis the default. The proxy reads the AMD report on the VM and the Policy Manager checks its signature against AMD's keys itself, with no Google service in the path. Writingsev-snpgets you this too, since Google's own verifier currently rejects every SEV-SNP VM anddeployswitches the setting.sev-snp-svsmadds a small firmware layer, the SVSM, that runs at the highest privilege level, VMPL 0, and holds the VM's vTPM, and the platform check then requires the guest's reports to come from VMPL 2, below it. Terraform andgcloudcannot ask for it, sodeploycreates this workload VM through Compute Engine's alpha API and deletes it again if it came up without the SVSM. You can also pin which SVSM firmware the platform check accepts.tdxruns the workload VM on Intel TDX. The Policy Manager stays on AMD SEV-SNP.
The Policy Manager does not check AMD's or Intel's certificate revocation lists on GCP. The deployment's network blocks the way out to them, so the check rests on the certificate chain alone.
NVIDIA H100 confidential GPUs pair with Intel TDX on GCP, on the a3-highgpu-1g machine type. The proxy sends the GPU's evidence to NVIDIA's attestation service, which is the one destination outside Google the deployment opens for it, and the deployment is healthy only when both the CPU and the GPU attest. The released images include no GPU-enabled proxy yet, so a GPU deployment needs the tooling's from-source build. The GPU VM always runs as a Spot VM, and when Compute Engine preempts it, it loses access to the key until the next deploy creates it again.
What the hardware report proves
An SEV-SNP report is signed by the CPU, and the signature chains back to AMD, so it can be checked without trusting Google. The report includes a launch measurement, a hash of what the VM held when it started. On GCP that hash covers Google's firmware and the VM's vCPU shape. The operating system and everything that runs after boot are loaded later and fall outside it.
A matching measurement therefore means "an SEV-SNP VM of this shape, on this Google firmware", which is true of every VM of that shape in every project. It is not an identity for your Policy Manager, and a Google firmware rollout or a new Policy Manager machine type changes it. Polaris adds its own layers on top for image integrity, runtime behavior and kernel integrity, and those layers carry the evidence about what the workload VM actually runs. See Attestation & Trust Model for the layers.
How the workload VM recognises its Policy Manager
The workload VM's proxy keeps a pin of the Policy Manager's launch measurement and privilege level, and refuses a Policy Manager whose report does not match. Since the measurement describes the VM's shape and firmware, the pin holds the workload VM to Policy Managers of that shape on that firmware, not to your Policy Manager alone.
You can set the pin before the workload VM boots, with cloud.gcp.pm_measurement_hex and cloud.gcp.pm_required_vmpl. The workload VM then refuses any other Policy Manager from its first report, and deploy checks that the Policy Manager it created reports the pinned value. Without a pin, the workload VM trusts the first Policy Manager that answers until deploy captures the report over IAP and installs it as the pin. deploy then prints the config that pins the value from the next run on.
The pin leaves out the report's field that names the physical chip, so the Policy Manager still matches after host maintenance moves it to another machine. The how-to guide explains how to set it.
What tells your Policy Manager apart is its identity key. deploy makes an EC P-256 key for each deployment, wraps it with a Cloud KMS key in its own key ring, <name>-pm-identity, whose only key-level grant is decrypt for the Policy Manager's service account, and writes the public half into the workload VM's boot configuration. The Policy Manager opens the key at start and signs its TLS key with it, and the workload VM refuses a Policy Manager that can't. The Policy Manager identity record names the key too, as pm_identity_pubkey, so Polaris Desktop checks the same signature and shows "PM verified" rather than "PM image verified". That proves the Policy Manager holds its service account's role, not what software it runs: anyone who can act as that service account, or holds a KMS decrypt role inherited from the project, can open the key too. It is on by default. cloud.gcp.pm_identity_key: false turns it off, which leaves only the measurement pin. Cloud KMS can't delete a key ring, so <name>-pm-identity stays in the project after destroy, and a later deployment with the same name reuses its Cloud KMS key.
Google's firmware rollouts used to move the pinned measurement, and the workload VM then refused the Policy Manager until someone pinned it again. With a proxy that has the check, the Policy Manager's proxy now sends Google's signed launch endorsement for its own measurement, which it fetches from Google's public gce_tcb_integrity bucket at storage.googleapis.com through Private Google Access. The workload VM checks Google's signature, that the endorsement lists the Policy Manager's measurement for its vCPU count, and that Google signed it on or after cloud.gcp.pm_endorsement_min_date. A good endorsement takes the place of the exact measurement only. The privilege level, the identity key and the rest still apply, and the identity key is required, since the endorsement only says the firmware is Google's. With the floor set, a Policy Manager that sends no endorsement is refused. If its proxy can't reach the bucket when it starts, it tries again each minute, and deploy stops after the apply when the Policy Manager still sends none. When the Policy Manager's measurement isn't the pinned one, deploy reads the workload VM's proxy log and goes on only once the proxy has accepted it as a Google-endorsed build. cloud.gcp.pm_launch_endorsement: false turns this off.
How your key is gated
The deployment creates a key ring and key, <name>-keyring and <name>-key, in the deployment's region. The key is an RSA-4096 key for asymmetric decryption, protected by an HSM. Polaris governs access to it through the key's IAM policy.
By default the Policy Manager's service account holds one custom role on the key, which lets it read and write the key's IAM policy. With cloud.gcp.pm_grant_by_tag it binds a tag on the key ring instead, and holds nothing on the key. How the Policy Manager grants the key describes both modes. In the default mode, while the workload VM passes, the Policy Manager adds the workload VM's service account to the key with two roles, roles/cloudkms.cryptoKeyEncrypterDecrypter and roles/cloudkms.publicKeyViewer, and removes it again:
- When a layer you enforce fails. It also locks that service account, so the key stays withdrawn until the VM that failed passes again or you lift the lock.
- When the workload VM goes quiet. It withdraws the grant after
attestation.deadman_intervalseconds without a report, 120 by default. - When a grant reaches its lifetime. It checks every minute, and each passing report extends the grant by
attestation.grant_ttl, an hour by default.
Layers in advise report findings without touching the key's policy, so a new deployment holds access while it learns, alerts included.
In either mode this is a real change in Google Cloud, and you can see it from outside Polaris: in the key's IAM policy, or in the key ring's tag bindings. Revocation stops future calls to Cloud KMS. A key your workload already decrypted stays in its memory for as long as it holds it.
The deployment also creates a Workload Identity Federation pool and provider for Google's confidential computing tokens. Both are disabled and nothing is bound to them, so no token from them can act as the workload VM's service account, and the key gate does not use them. Access to the key rests on the service account's own grant on the key, which the Policy Manager switches on and off.
All of this runs inside the Policy Manager. GCP has no separate component that ends access when the Policy Manager stops, so a Policy Manager that stops or hangs leaves the last binding in place until it comes back. When it starts again, it removes every binding it is not tracking, and grants access again on the workload VM's next passing report.
The key outlives every deployment. destroy keeps the key ring and key, and a later deployment with the same name gates the same key again. In the default mode destroy does not remove the bindings the Policy Manager added, and the how-to guide shows how to clear them.
How a workload uses the key
Your workload never holds a Google credential and cannot reach the metadata server. It asks the Polaris proxy in its own VM, over two routes on the proxy's internal listener, to encrypt and decrypt. The proxy calls Cloud KMS as the workload VM's service account, which only the Policy Manager's grant lets use the key, so calls fail once the grant is withdrawn. The routes are in Use the gated key from your workload, and the workload contract says what a revoke ends.
What your clients see when a check fails
The proxy holds workload traffic when a layer you enforce fails, and serves it otherwise. Findings from layers in advise do not hold traffic. While traffic is held, new HTTP requests receive 503 with a Retry-After: 30 header and a message that ends in attestation pending.
Three moments are worth planning around.
- At start-up. On GCP the proxy holds traffic from the moment it starts until the Policy Manager's first verdict that is not a failure.
- When an enforcing layer fails. The proxy holds traffic from the report that carries the failing verdict, and it serves again once a later report passes.
- When the Policy Manager stops answering. The proxy keeps serving until five reports in a row go unanswered, about two and a half minutes at the default 30-second interval, and then holds traffic until the Policy Manager answers again.
A set of status routes stays reachable throughout, so your monitoring can tell these cases apart. See Monitor a deployment.
What stays closed
- Outbound connections go where you allow them. A firewall rule denies all outbound traffic from both VMs, and rules above it allow Google APIs and Artifact Registry through Google's private API addresses, traffic within the subnet, and HTTPS to the address ranges you list. Private DNS zones point Google's API names at those private addresses. Name lookups are the exception: they go to the metadata server, which firewall rules do not filter, so both VMs can resolve any name.
- Only Polaris's proxy reaches the metadata server. The workload VM's firewall keeps every container but the proxy's away from it, so your workload never holds the VM's service account credentials.
- Nothing on the VM's host reaches the workload directly. Traffic to the workload passes through the proxy.
- Shell access is through IAP. Port 22 on both VMs opens only to
35.235.240.0/20, the range IAP connects from, so SSH needs a Google identity with IAP access in your project. - The workload VM is reachable on port 443 from any address. Apart from SSH through IAP, the Policy Manager accepts connections from the workload VM only.
The deployment creates no access for Fr0ntierX in your project. The Policy Manager exports health telemetry only when you give it a collector, and nothing exports from the workload VM. The GCP reference lists every destination.
Why patching means rebuilding
The Polaris image keeps the packages it was built with, and the workload VM switches off automatic package updates, snap updates and the other update timers at boot. Polaris measures what runs, and an automatic update would change those files and lead Polaris to withdraw your key from a machine doing nothing wrong.
A security fix therefore arrives as a new image. You publish it to the image family the deployment boots from and run deploy again. deploy boots both VMs from the newest image in the family, so a new image replaces both, and Polaris learns the new VMs before you turn enforcement back on, at a time you choose. See Take a security fix.
Learning, then enforcing
A new deployment starts in an advisory state, and Polaris fills its allowlists by watching the healthy workload. Advisory layers report findings and leave your key alone. Learning watches for at least 10 minutes by default, and longer when the workload keeps doing new things. A layer can also read clean for an hour and still meet a job that runs once a day, so the Policy Manager refuses to enforce a layer until it has been clean under advise for a day. See Move a layer to enforce.
The Policy Manager keeps its state on a disk of its own, <name>-pm-state, which outlives the Policy Manager VM. What it learned, and the layers you moved to enforce, survive a restart of its container or its VM.
It keeps that learned state and those settings only while the deployment's baseline file stays the same, and on GCP each deploy writes the baseline under a new name that carries the time of the run. So every deploy returns every layer to the settings the deployment started with and starts learning again, even when nothing else changed.
What survives a replacement
The workload VM's address, the Cloud KMS key and the Policy Manager's state disk survive any replacement. The disk keeps the Policy Manager's keys, its record of the workload VMs and the locks a failure put on the key. Learned allowlists and enforcement settings last until the next deploy, as above.
What Polaris relies on in your project
Polaris protects your workload from the cloud operator and from a compromised workload. Within your own project, it relies on the people who can change IAM. Anyone who can change the key's IAM policy or act as the deployment's service accounts can reach the key without Polaris. A dedicated project, and a short list of people with IAM rights in it, keep that group small.