Data plane upgrade authorization
Since 0.5.0, upgrading a data plane is authorized separately from managing one. This page describes the boundary: which operations sit behind it, the credential that passes it, the deployment order for an environment that runs its own management plane, and what fails when a step is skipped.
What sits behind the boundary
Five upgrade operations require the dataplane_upgrade.operate permission or the effective dataplane_operator scope:
SubmitDataplaneUpgradeCredentialsGetDataplaneUpgradeCredentialsAckDataplaneUpgradeCredentialsCancelDataplaneUpgradeRollbackDataplaneUpgrade
TriggerUpdate applies the same requirement when its type is DATAPLANE_UPGRADE. Ordinary configuration updates keep their existing authorization, and trusted in-process auto-upgrade keeps its existing opt-in and eligibility checks: neither is affected by the boundary.
Who holds the grant
- Only the
dataplanemachine role holdsdataplane_upgrade.operate. The workers that fetch and acknowledge upgrade credentials hold it through their existingdataplanerole binding; no re-scope of worker service accounts is needed. - The
dataplane_operatorscope is carried by the platform credential. It is not in the customer-mintable management-key catalog, so it cannot be added to an ordinary management API key. - Organization admin credentials can no longer run upgrades. Before 0.5.0 they could; a credential that ran upgrades through 0.4.x receives
permission_deniedon the operations above until the platform credential carries the operator scope.
On a Tetrate-hosted management plane these grants are prepared by Tetrate as part of the release, and nothing on this page is an operator step. The rest of this page applies to a deployment that runs its own management plane (the topology the tare CLI installs).
The order
The steps run in this order because each one is what makes the next safe. Deploying the management plane first is the failure case, not a variant.
- Deploy the auth service at the new release. This is what defines
dataplane_upgrade.operateand binds it to thedataplanerole. - Verify the permission exists and belongs only to the
dataplanerole before anything starts enforcing against it. - Prepare the platform credential. A credential generated at this release carries the
dataplane_operatorscope; an existing credential is updated in place to add it. Regenerating replaces several deployment secrets at once, so a regeneration goes through the normal credential-rotation procedure. Reload every consumer of the credential afterward. - Verify the worker role bindings. Every worker that calls
GetDataplaneUpgradeCredentialsorAckDataplaneUpgradeCredentialsmust hold itsdataplanerole binding. - Deploy the management plane. Enforcement begins here, and by this point every caller already holds what it needs.
What fails when a step is skipped
- Management plane deployed before the auth service:
GetDataplaneUpgradeCredentialsand the credentials acknowledgement are denied for every data plane. No data plane can be upgraded until the auth service catches up. - Platform credential not prepared: upgrade operations fail with
permission_denied, and the error does not name the missing scope. The deployment keeps serving traffic and accepts ordinary configuration changes; only the ability to upgrade the data plane is lost, which is easy to misread as an upgrade bug rather than a credential gap. - A worker without its
dataplanerole binding: that worker's credential fetch and acknowledgement are denied, and its data plane cannot complete an upgrade.
Rolling back
If upgrade operations fail after enforcement, restoring the previous management plane image restores the previous behavior. The added permission and the prepared platform credential are additive and can stay in place; they do nothing until the new release is deployed again. Note that this rollback temporarily restores organization-admin upgrade access, so the redeployment should follow once the cause is fixed rather than being left open-ended.
Where to go next