A key can have a rotation schedule which determines if and when it is automatically rotated.
To automatically rotate a key by setting a rotation period (Update a key)
or to manually rotate a key (Create a new key version), a user needs the
Cloud Identity and Access Management role roles/cloudkms.admin
, roles/owner
, or
roles/editor
.
After rotating a key, its previous key versions (which no longer are primary) are neither disabled or destroyed, and remain available for decrypting data.
Automatic rotation: Setting the rotation period for a key
To enable automation rotation of a key, set the rotation schedule with the
following gcloud
command-line tool syntax:
Command-line
gcloud kms keys update KEY_NAME \
--location LOCATION \
--keyring KEYRING_NAME \
--rotation-period ROTATION_PERIOD \
--next-rotation-time NEXT_ROTATION_TIME
Windows cmd.exe
gcloud kms keys update KEY_NAME ^ --location LOCATION ^ --keyring KEYRING_NAME ^ --rotation-period ROTATION_PERIOD ^ --next-rotation-time NEXT_ROTATION_TIME
PowerShell
gcloud kms keys update KEY_NAME ` --location LOCATION ` --keyring KEYRING_NAME ` --rotation-period ROTATION_PERIOD ` --next-rotation-time NEXT_ROTATION_TIME
Rotation schedule syntax
The format for the rotation schedule depends on the client library that is used.
For the gcloud
tool, the next rotation time must be in ISO or
RFC 3339 format, and the rotation period must be in the form
INTEGER[UNIT]
, where units can be one of
seconds (s
), minutes (m
), hours (h
) or days (d
). For example, a valid
rotation schedule for use with the gcloud
tool could be:
--rotation-period=30d --next-rotation-time=2016-10-12T12:34:56.1234Z
Create a key with a rotation schedule
To create a new key for the key ring:
Command-line
gcloud kms keys create KEY_NAME \
--location LOCATION \
--keyring KEYRING_NAME \
--purpose ENCRYPTION \
--rotation-period ROTATION_PERIOD \
--next-rotation-time NEXT_ROTATION_TIME
Windows cmd.exe
gcloud kms keys create KEY_NAME ^ --location LOCATION ^ --keyring KEYRING_NAME ^ --purpose ENCRYPTION ^ --rotation-period ROTATION_PERIOD ^ --next-rotation-time NEXT_ROTATION_TIME
PowerShell
gcloud kms keys create KEY_NAME ` --location LOCATION ` --keyring KEYRING_NAME ` --purpose ENCRYPTION ` --rotation-period ROTATION_PERIOD ` --next-rotation-time NEXT_ROTATION_TIME
Where the command uses the following parameters: a new key KEY_NAME
for
the key ring KEYRING_NAME
with rotation schedule defined by ROTATION_PERIOD
and NEXT_ROTATION_TIME
.
Manual rotation: Generating a new key version
To create a new key version and make it primary with the gcloud
tool,
for the key KEY_NAME
for the key ring KEYRING_NAME
, run:
Command-line
gcloud kms keys versions create --location LOCATION \
--keyring KEYRING_NAME \
--key KEY_NAME --primary
Windows cmd.exe
gcloud kms keys versions create --location LOCATION ^ --keyring KEYRING_NAME ^ --key KEY_NAME --primary
PowerShell
gcloud kms keys versions create --location LOCATION ` --keyring KEYRING_NAME ` --key KEY_NAME --primary
This is equivalent to you creating a new key version that is not primary, then
making that version primary. That would require you knowing the version number
VERSION_ID
of the newly created key version. This is equivalent to the
following gcloud
tool commands:
Command-line
gcloud kms keys versions create \
--location LOCATION \
--keyring KEYRING_NAME \
--key KEY_NAME
gcloud kms keys update KEY_NAME \
--primary-version VERSION_ID \
--location LOCATION \
--keyring KEYRING_NAME
Windows cmd.exe
gcloud kms keys versions create ^ --location LOCATION ^ --keyring KEYRING_NAME ^ --key KEY_NAME gcloud kms keys update KEY_NAME ^ --primary-version VERSION_ID ^ --location LOCATION ^ --keyring KEYRING_NAME
PowerShell
gcloud kms keys versions create ` --location LOCATION ` --keyring KEYRING_NAME ` --key KEY_NAME gcloud kms keys update KEY_NAME ` --primary-version VERSION_ID ` --location LOCATION ` --keyring KEYRING_NAME
Disable automatic rotation
To disable an automatic rotation, clear the rotation schedule of the key:
Command-line
gcloud kms keys update KEY_NAME \
--remove-rotation-schedule \
--location LOCATION \
--keyring KEYRING_NAME
Windows cmd.exe
gcloud kms keys update KEY_NAME ^ --remove-rotation-schedule ^ --location LOCATION ^ --keyring KEYRING_NAME
PowerShell
gcloud kms keys update KEY_NAME ` --remove-rotation-schedule ` --location LOCATION ` --keyring KEYRING_NAME
Setting an existing version as the primary key version
To make version 42
(which is enabled) the primary version of the key
dont-panic
in key ring hitchhiker
:
Command-line
gcloud kms keys update dont-panic \
--primary-version 42 \
--location global \
--keyring hitchhiker
Windows cmd.exe
gcloud kms keys update dont-panic ^ --primary-version 42 ^ --location global ^ --keyring hitchhiker
PowerShell
gcloud kms keys update dont-panic ` --set-=primary-version 42 ` --location global ` --keyring hitchhiker