Skip to main content

Deploying on Oracle Cloud

Oracle Cloud runs Polaris on AMD SEV-SNP confidential VMs. Read Deploying Polaris first for the choices common to every cloud; this page covers what is specific to OCI.

Before you start​

You deploy into your own OCI tenancy and compartment. You provide the tenancy and compartment identifiers and the region. Pick a region that offers the AMD EPYC confidential-VM shapes.

TEE options​

ChoiceHardwareShape
AMD SEV-SNPAMD EPYC TurinVM.Standard.E6.Flex / BM.Standard.E6.256

Intel TDX and confidential GPUs are not available on OCI. If you need those, see the Google Cloud or Microsoft Azure pages.

Verification path​

Polaris verifies the AMD SEV-SNP report against AMD's published keys, so no cloud attestation service sits in the trust path. On top of that platform check you get the full continuous-attestation model: image integrity, runtime behavior, and kernel integrity, all gating key access.

Key management​

The Policy Manager gates a key in OCI Vault. The vault and key are created in your compartment. The deploy script names the vault after the deployment, <name prefix>-vault, unless kms.oracle.vault_display_name names it. OCI renames a vault in place, so changing the name replaces nothing.

The gate is a defined tag on each workload VM. While appraisal passes, the Policy Manager sets Polaris.AttestationState to active on the VM. That puts the VM in a dynamic group whose policy allows encrypt and decrypt on the key, and nothing else: no export, no sign. When appraisal fails, the Policy Manager removes the tag.

The Policy Manager can only tag VMs that carry Polaris.Role = workload-cvm and its own deployment's Polaris.Deployment, the display name prefix, so it cannot tag itself, any other instance, or another deployment's VMs. The dynamic groups match on Polaris.Deployment too, so an attested VM from another deployment in the same compartment does not get this key.

That does not fully separate two deployments in one compartment. The Policy Manager writes a VM's whole tag map back, and OCI limits that right by tag namespace, not by tag. So whoever holds a Policy Manager's identity can move its own deployment's VM to another deployment's Polaris.Deployment value and mark it active in one write, and that VM then gets the other deployment's key. Run one deployment per compartment to rule this out. It matters more once the Policy Manager's list grant for its sweep is on (pm_oci_reconcile_list, off by default). With it, each Policy Manager can read every instance in the compartment, user_data included. That no longer holds Polaris's tokens, only the names of the vault secrets they are in, but it does hold workload_env_vars, which stay in user_data. A Policy Manager can read only its own deployment's secrets, and so can its workload VMs: their read group names each VM by OCID, so a VM moved to another deployment's tags does not get that deployment's tokens.

The Policy Manager's API tokens, the Sentinel's token and the OCIR auth token are secrets in the same vault, under their own key, not in the VMs' user_data, which anyone who can read an instance through the API could read. Each VM reads its own at boot as its instance principal: the workload VMs through a dynamic group that names each of them by OCID, in any attestation state, since they read them before the Policy Manager has seen them, and the Policy Manager through its own group. That keeps the tokens from the instance API, not from the VM: anything on a VM that can read the metadata service's identity key, root or the proxy, can read that VM's secrets as the boot does. Each may read only its own secrets, by name, in this deployment's vault. A VM that can't read one stops its boot there.

The OCIR auth token belongs to the OCI user who made it, so treat it as that user's credential. The deploy script reads it from OCIR_AUTH_TOKEN and gives it to Terraform in Terraform's environment only. It is not written to the deployment's tfvars file. A run without OCIR_AUTH_TOKEN keeps the token already in the vault, so you only set it to replace the token. With both OCIR_USERNAME and OCIR_AUTH_TOKEN set, the script logs docker in to <region>.ocir.io itself and logs out again before it finishes, which replaces any login you already had for that registry. Unset them to keep an existing login. A tfvars file an older script wrote still has the token in it, and the next deploy or destroy removes that line.

Terraform keeps the content of every vault secret it manages in its state, so the state file and its .backup hold the OCIR auth token and the Policy Manager's tokens. Keep the state directory (terraform/modules/oracle/sev for the deploy script) private: do not commit it, copy it to shared storage or attach it to a ticket. If a state file or an old tfvars file has left your machine, revoke the OCIR auth token in OCI, make a new one and deploy with it.

Revocation is not instant. OCI reads group membership from the tags inside a VM's instance principal token, and that token lives 20 minutes. A VM that fetches a new token for each call loses the key within about 30 seconds of the revoke. The proxy uses a token for at most a minute, so its key routes stop within about a minute. A process that holds on to a token issued while the VM was active keeps the key until the token expires, so plan for up to 20 minutes.

A failed appraisal removes the tag at once. A VM that stops reporting keeps it until its grant expires, attestation.grant_ttl seconds after its last passing report, 180 by default, and the Policy Manager checks for expired grants every 30 seconds. The dead man's switch (attestation.deadman_interval, 240 by default) comes later. The default is 180 rather than 120 so that a proxy restart keeps the key: the Policy Manager holds the restarted proxy's reports, without renewing the grant, until the old proxy's key ages out after three report intervals, and with the default 30-second interval the first pass after that can land just under 120 seconds after the last renewal. If you raise attestation.report_interval, keep the TTL at least 3 x max(interval, 30) + interval, plus a minute for a slow appraisal. deploy.sh warns when the TTL, set or default, is under that, and refuses one that is not over the interval, since a healthy VM would then lose its grant between its own reports. Below a 30-second interval no TTL keeps the key on a proxy restart: the Policy Manager holds the restarted proxy only once the old key has been silent for more than 30 seconds, which a fast proxy's first report usually beats, so the node is refused and the grant revoked until the old key has been silent for 90 seconds. deploy.sh warns about that too. These checks run on deploy, up and up-polaris, not on destroy or status.

Use the gated key from your workload​

Your workload never holds an OCI credential, and its container cannot reach the metadata service, where the VM's instance key lives: the VM's firewall drops traffic from the workload network to 169.254.169.254 and lets only the proxy through. The workload asks the Polaris proxy in its own VM, on the proxy's internal listener, which only the workload's network reaches. The proxy calls OCI Vault as the VM's instance principal, which the Policy Manager's tag keeps in the group allowed to encrypt and decrypt with the key.

curl -s -X POST http://polaris-proxy:3000/polaris-container/key/encrypt \
-H 'Content-Type: application/json' -d '{"plaintext":"aGVsbG8="}'
# {"ciphertext":"..."}

curl -s -X POST http://polaris-proxy:3000/polaris-container/key/decrypt \
-H 'Content-Type: application/json' -d '{"ciphertext":"..."}'
# {"plaintext":"aGVsbG8="}
  • The routes need proxy v1.1.0-rc.38 or later, the release the deploy script pins. The deploy script sets them up on every Oracle deployment, and an older proxy ignores the settings and serves no routes.
  • plaintext is base64, up to a little under 768 KiB, since the body is capped at 1 MiB. Treat the ciphertext as opaque. The proxy seals each plaintext under a fresh data key and has OCI Vault encrypt that key with the deployment's key, so both calls need the Policy Manager's grant, and only a VM holding the grant can make a ciphertext that opens.
  • A 400 means the input was malformed or OCI Vault could not use it. A 503 means there is no passing verdict yet, or OCI refused the call, as it does once the tag is gone.
  • Nothing is cached, so every decrypt is a fresh OCI Vault call. A plaintext your workload keeps in memory outlives a revoke, so decrypt per operation if a revoke has to stop it.
  • On a fail the proxy refuses at once. OCI itself stops the proxy's calls within about a minute of the tag's removal, as Key management describes.
  • The proxy reaches OCI's auth service and the vault's crypto endpoint through the service gateway. Policy Manager learning sees those connections only when the workload uses its key, so use it while the Policy Manager learns.
  • The ciphertext decrypts only with this OCI Vault key. Moving the deployment to another platform means re-encrypting your data there.

Network shape​

The Oracle module puts the workload VMs in a private subnet behind a public network load balancer that passes TCP through on 443, and the Policy Manager in a separate control subnet. Two options are worth calling out at setup:

  • A public endpoint for the Policy Manager. Optional, so you can reach the management API directly instead of going through the proxy passthrough. You name the allowed source ranges; an open 0.0.0.0/0 is rejected.
  • A bastion for SSH. Optional access into the private subnets through the OCI Bastion service, again scoped to ranges you name.

Status and promotion​

./scripts/deploy.sh status --config <file> lists the deployment's VMs and shows the Policy Manager's verdict for each workload VM, its license and how far learning has got. ./scripts/deploy.sh promote --config <file> --layers <layers> moves enforcement layers between advise, enforce and off in place, as on the other clouds.

Neither VM has a public address, so both reach the Policy Manager through the OCI Bastion. They need cloud.oracle.bastion_allow_cidrs to include the address you run them from, cloud.oracle.ssh_public_key_file with its private key beside it (the same path without .pub), the oci CLI signed in with the right to create Bastion sessions, and the same config file you deployed with. Each run opens one Bastion session to the Policy Manager and deletes it when it ends. Without the Bastion, status lists the VMs and says the Policy Manager was not read, and promote refuses.

The first status or promote trusts the Policy Manager's SSH host key as it is offered and keeps it, and later runs refuse a different key. The Bastion's own key comes from OCI with the session and is always checked.

Sizing​

You set the shape for the workload VMs and for the Policy Manager, and how many workload VMs to run behind the load balancer.

How you deploy​

  • Command line. Point the deploy script at an Oracle config file with your tenancy, compartment, and region.
  • OCI Marketplace. Deploy from the listing as a Resource Manager stack. The marketplace image bakes in the Polaris components, so nothing but your own workload image is pulled at launch, and the stack generates the Policy Manager's management token for you. The image carries no license, so paste the license file Fr0ntierX sent you into the stack's License field. See Licensing.

Notes​

  • The load balancer terminates nothing: it passes encrypted TCP straight to the proxy on the confidential VM, so TLS is still terminated inside the TEE.
  • The Policy Manager keeps its keys, which layers enforce, and everything it learned on its own block volume, so all of it survives a restart or a replacement of the Policy Manager VM.
  • Tearing down the deployment removes the VMs, the Policy Manager's state volume, the load balancer, the network, and the vault resources it created, the token secrets included.
  • Upgrading a deployment from before the tokens moved to the vault creates the secrets and the read grants, and replaces the Policy Manager and the workload VMs once, since their boot config changes. The Policy Manager keeps its state volume. A token change after that, or a new OCIR token, updates its secret: a changed Policy Manager or Sentinel token replaces the VMs that read it, and a new OCIR token replaces none.
  • Upgrading a deployment from before Polaris.Deployment tags its VMs in place and then switches the dynamic groups and the Policy Manager's policy to the new tag. Expect the key to fail closed for up to about 20 minutes, while VMs renew tokens issued before their tag. If the Policy Manager's own token is that old when its new group rule takes effect, it cannot revoke either until it renews it, so a VM that fails appraisal in that window keeps the key until the Policy Manager tries again: on the VM's next failed appraisal, or when its grant expires (180 seconds by default) if the VM stops reporting.
  • A second deployment in another compartment of the same tenancy reuses the Polaris tag namespace the first one created. The deploy script finds it and does not create it again.