This topic shows how to set an expiration date for a secret in Secret Manager. The topic also describes how to update or remove the expiration date that is set for a secret.
Overview
By default, secrets stored in Secret Manager exist until a user deletes them. If a secret should only be stored for a known, limited amount of time, you can attach an expiration time to it. At a secret's configured expiration time, it is automatically deleted.
If you don't have requirements that the secret must be deleted, consider using IAM Conditions or the Disabled version state to revoke access in a safe way.
You can enter an expiration time as either a timestamp or a duration. When secret metadata is retrieved, the expiration is always returned as a timestamp, regardless of how it was given.
An expiration can be added, updated, or removed from a secret at any time.
Limitations
Secret expiration is only available only in the Secret Manager
v1
API and gcloud command-line tool.A secret's expiration cannot be less than 60 seconds away or more than 100 years away.
Safely use expiring secrets
When a secret expires in Secret Manager, it is irreversibly deleted. The best way to detect soon-to-expire secrets is by using IAM Conditions to remove permissions from the accounts that use the secret prior to expiration.
To do this, when granting permissions on a secret, attach a time-based condition to the binding. The binding should expire after the secret is expected to no longer be used, but early enough that the removed permissions would be noticed before the secret expires. If workflows that were thought to no longer use the secret break after permissions are revoked, then permissions can be added back to quickly mitigate. If more time is required, the secret expiration can be updated or even removed.
For example, suppose a service account is expected to access a secret daily over a 30 day period. The secret expiration could then be set to 60 days from creation and a conditional IAM binding could be used to grant the service account the Secret Accessor role for 45 days. If the service account attempts to access the secret after 45 days, a Permission Denied error will be returned and workflows requiring the secret would break. An administrator could then grant the Secret Accessor role back to the service account to quickly mitigate while investigating, since the secret itself wouldn't be deleted for 15 more days.
Additionally, it is possible to create alerts based on logs warning of secrets that are expiring soon. See Expiration logging for more information.
Specify timestamps and durations
Timestamp values must be formatted as RFC 3339, for example
2100-01-01T09:00:00-05:00
.Duration values must be formatted as the number of seconds including the "s" suffix, for example
86400s
.
Create an expiring secret
Create an expiring secret using a timestamp:
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 378.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
gcloud secrets create "SECRET_ID" \
--replication-policy "automatic" \
--expire-time "TIMESTAMP"
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" \
--request "POST" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data-binary @- <<EOF
{
"replication": {"automatic": {}},
"expire_time": "TIMESTAMP"
}
EOF
Create an expiring secret using a duration:
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 378.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
gcloud secrets create "SECRET_ID" \
--replication-policy "automatic" \
--ttl "DURATION"
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" \
--request "POST" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data-binary @- <<EOF
{
"replication": {"automatic": {}},
"ttl": "DURATION"
}
EOF
Update a secret's expiration
Any secret can have a new expiration applied to it regardless of whether it already has one. Each secret can only have one configured expiration at a time. Updating the expiration of a secret that already has one will overwrite its existing expiration.
Update a secret's expiration using a timestamp:
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 378.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
gcloud secrets update "SECRET_ID" \
--expire-time "TIMESTAMP"
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=expire_time" \
--request "PATCH" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data-binary @- <<EOF
{
"expire_time": "TIMESTAMP"
}
EOF
Update a secret's expiration using a duration:
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 378.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
gcloud secrets update "SECRET_ID" \
--ttl "DURATION"
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=ttl" \
--request "PATCH" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data-binary @- <<EOF
{
"ttl": "DURATION"
}
EOF
Remove a secret's expiration
gcloud
To use Secret Manager on the command line, first Install or upgrade to version 378.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
gcloud secrets update "SECRET_ID" \
--remove-expiration
API
These examples use curl to demonstrate using the API. You can generate access tokens with gcloud auth print-access-token. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.
Including either expire_time
or ttl
in the updateMask
while providing
values for neither will remove the expiration.
curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=ttl" \
--request "PATCH" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data-binary '{}'
Expiration logging
Cloud Audit Logs are not produced when a Secret automatically expires.
Instead Secret Manager writes logs to the Secret Manager Secret
resource at
specific intervals leading up to a secret's expiration.
Log Timing | Secret Event Type |
---|---|
30 days before expiration | EXPIRES_IN_30_DAYS |
7 days before expiration | EXPIRES_IN_7_DAYS |
1 day before expiration | EXPIRES_IN_1_DAY |
6 hours before expiration | EXPIRES_IN_6_HOURS |
1 hour before expiration | EXPIRES_IN_1_HOUR |
at expiration | EXPIRED |
See the Logging Quickstart guide for information about how to view these logs. You can create Log-based metrics and use them to create alerts for upcoming expirations.
What's next
- Learn how to set up rotation schedules for secrets.
- Learn how to enable Customer-Managed Encryption Keys (CMEK) for Secret Manager.