Rotate the managed key
Replace the DSN key that connected apps and CI environments use, rebuild every connected app with the new one, and retire the old key once nothing sends with it.
The managed key exists once an app or a CI environment is connected to the project (see Connect an app). Rotating it never touches the project's other keys. Replace project-id with the project's id.
Prerequisites
- Permission for
errors:UpdateProjecton the project. - In the console, also
errors:ListProjectson the project to open it (without it the project is not found). - A rotation starts a rebuild of every connected app; each rebuild is a deployment of that app.
Rotate the key
- Open the project, then the Setup tab.
- Under Managed key, for Previous key works for at least, choose 1 hour, 24 hours (default) or 7 days.
- Choose Rotate key, then confirm with Rotate key.
The console says how many apps are rebuilding, which to rebuild yourself, and which rebuilds could not start.
dcloud errors connections rotate-key project-id --grace-seconds 86400POST /errors/api/projects/project-id/rotate-key
{ "graceSeconds": 86400 }graceSeconds is 600 (10 minutes) to 604 800 (7 days), 86 400 by default. The answer is 201 with
the new dsn, revokeAfter, redeployed (the apps rebuilding), rebuildYourself and failed.
What happens
- A new key is created. The managed entry in Secrets gets a new version holding its DSN.
- Every connected app is rebuilt and redeployed, so the new DSN also reaches its browser bundle.
- The previous key keeps accepting events. It is revoked once all of these hold:
- the grace is over;
- every connected app built here runs a deployment made after the rotation (a rebuild that failed holds the revocation);
- the previous key has received no event for 15 minutes.
Apps that run an image or a compose file built elsewhere get the new DSN at run time, but their
browser bundles keep the old one until you rebuild them; the rotation lists them under
rebuildYourself, and does not wait for them.
While a rotation is in progress, the Setup tab says "A rotation is in progress." with the earliest time the previous key is revoked, and offers no Rotate key until it is revoked.
End the grace early or move it
- Open the project, then the Setup tab.
- Under Managed key, choose Revoke previous key now.
The previous key is revoked at once; events still sent with it are refused.
dcloud errors connections revoke-previous-key project-id
dcloud errors connections extend-grace project-id --grace-seconds 172800POST /errors/api/projects/project-id/rotate-key/revoke-previousPOST /errors/api/projects/project-id/rotate-key/extend
{ "graceSeconds": 172800 }extend sets the earliest revocation to graceSeconds from now, earlier or later than before. It
still waits for the rebuilds and for the key to go quiet.
When a rotation is refused
404"Nothing is connected to this project, so there is no managed key".409"A rotation is still in its grace period: revoke the previous key now, or wait until it is revoked".409"No rotation is in progress" for revoking or extending when there is none.