Filter lists of secrets and secret versions

This topic discusses support for filtering in the following resource-listing calls in Secret Manager:

Usage

Filtering intent in a list operation is indicated by the presence of the filter string field in the list request body. The API uses a simple language for referring to the fields in the object that is being filtered.

In the following examples, let us assume that a subset of secrets contains either "asecret" or "bsecret" substring. Specify a filter matching these secrets. The results are sorted by name in the ascending order.

gcloud

Filters are specified using the --filter flag. If your filter contains a space or other special character, you must surround it in quotes.

gcloud secrets list --filter="name:asecret OR name:bsecret"

Google Cloud CLI also supports regular expressions (regex), for example:

gcloud secrets list --filter='name ~ "secret_ab.*"'

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.

Filters are specified as the filter querystring parameter and must be URL-encoded. For example, the filter name:asecret OR name:bsecret would be URL-encoded as name%3Aasecret+OR+name%3Absecret.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?filter=FILTER" \
    --request "GET" \
    --header "Authorization: Bearer ACCESS_TOKEN"

Regex is not supported in the API.

Examples

Scenario Filter
Secrets whose name contains the "mysecret" substring name:mysecret
Secrets with a specific label labels.environment=production
Secrets created within date/time range create_time<2021-01-01T06:00:00Z AND create_time>2021-01-01T12:00:00Z
Secrets with automatic replication replication.automatic:*
Secrets with user-managed replication but not stored in either of the given regions replication.user_managed.replicas.location:* AND NOT replication.user_managed.replicas.location:(us-central1 OR us-east1)
Secrets encrypted with CMEK keys replication.user_managed.replicas.customerManagedEncryption:*
Secrets encrypted with a specific CMEK key replication.user_managed.replicas.customerManagedEncryption.kmsKeyName=projects/p/locations/us-central1/keyRings/kr/cryptoKeys/my-cmek-key
Secrets without a rotation period NOT rotation.next_rotation_time:*
Secrets with a rotation period > 30d rotation.rotation_period>259200s
Secrets with expiration set expire_time:*
Secrets expiring before a date expire_time<2021-07-31
Versions that are enabled or disabled state:(ENABLED OR DISABLED)
Destroyed versions, destroyed after date state:DESTROYED AND destroy_time>2021-01-01

Filter syntax

The filter syntax consists of an expression on one or more fields of the objects being filtered.

You can use the following expression operators.

Operator Description
= Equality.
> Greater than.
< Less than.
>= Greater than or equal to.
<= Less than or equal to.
!=
-
NOT
 Inequality. The following are equivalent:
name!="topsecret"
-name="topsecret"
NOT name="topsecret"
:

Containment. This is a case-insensitive substring match.

As an example, name:"myapp" filters on resources that contain myapp (case-insensitive) in the resource name.

AND

Logical AND.

A space is equivalent to AND, so the following are equivalent:
name:"myapp" AND name:"secret1"
name:"myapp" name:"secret1"

OR Logical OR.
*

Wildcard.

Can be used as a standalone where field:* indicates that field is set.

Consistently with Cloud Search API, OR takes precedence over AND by default. Parentheses can be used to indicate the desired operation priority.

When filtering on time values, encode the time as a string in the RFC 3399 format, such as 2020-10-15T01:30:15Z.

When accessing a subfield, use dot syntax. For example, the Secret resource may include the labels field whose value is a key-value map. If a color label is use, you can filter Secret results on the subfield labels.color as follows:

labels.color=red

If you want to list only secrets with color label set, use a wildcard:

labels.color:*

A quoted string is interpreted as a single value rather than a sequence of values.

Filter fields

You can filter on any field of Secret or SecretVersion object.

List method Link to filterable fields
projects.secrets.list Secret fields
projects.secrets.versions.list SecretVersion fields

Total result count

If filter is set in a list request, the response does not indicate the total result count (total_size=0 in the response).

What's next