Filtra secretos regionales y versiones de secretos

En esta página, se explica el proceso de filtrar secretos y versiones de secretos en Secret Manager. En entornos con muchos secretos, el filtrado ayuda a identificar rápidamente secretos o versiones específicos sin desplazarse manualmente por toda la lista. Puedes filtrar según criterios como etiquetas, fechas de creación o patrones específicos dentro de los nombres de secretos, lo que permite una administración enfocada de grupos específicos de secretos.

En Secret Manager, puedes filtrar secretos y versiones de secretos con la opción Filtrar en la consola de Google Cloud o especificando criterios de filtro dentro de una llamada a la API. En Google Cloud CLI, puedes filtrar secretos y versiones de secretos si incluyes una cadena filter cuando enumeras secretos.

Filtra secretos

Para filtrar un secreto, usa uno de los siguientes métodos:

Console

1. Ve a la página de Secret Manager en la consola de Google Cloud.

   Ir a Secret Manager

2. En la página de Secret Manager, haz clic en la pestaña Secretos regionales.

3. En la tabla Secretos regionales, haz clic en el campo Filtro.

4. Elige una propiedad de filtro y su valor correspondiente, por ejemplo, Location:asia-east1.

   La tabla se filtra automáticamente según los valores ingresados. Los resultados se ordenan por nombre en orden ascendente.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

• LOCATION: La ubicación de Google Cloud del secreto
• FILTER: Es la cadena de filtro, por ejemplo, name:asecret OR name:bsecret. Gcloud CLI también admite expresiones regulares, por ejemplo, name ~ "secret_ab.*".

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud secrets list --location=LOCATION --filter="FILTER"

Windows (PowerShell)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud secrets list --location=LOCATION --filter="FILTER"

Windows (cmd.exe)

Nota: Asegúrate de haber inicializado Google Cloud CLI con autenticación y un proyecto mediante la ejecución de gcloud init o gcloud auth login y gcloud config set project.

gcloud secrets list --location=LOCATION --filter="FILTER"

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• LOCATION: La ubicación de Google Cloud del secreto
• PROJECT_ID: El ID del proyecto de Google Cloud
• FILTER: Es la cadena de filtro. Los filtros se especifican como el parámetro de cadena de consulta filter y se deben codificar como URL. Por ejemplo, el filtro name:asecret OR name:bsecret se codificaría como URL como name%3Aasecret+OR+name%3Absecret. Las expresiones regulares no son compatibles con la API.

Método HTTP y URL:

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?filter=FILTER

Cuerpo JSON de la solicitud:

{}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?filter=FILTER"

PowerShell

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?filter=FILTER" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "secrets": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
      "createTime": "2024-09-02T07:14:00.281541Z",
      "etag": "\"16211dd90b37e7\""
    }
  ]
}

Go

Para ejecutar este código, primero configura un entorno de desarrollo de Go e instala el SDK de Go para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

// listSecretsWithFilter lists all filter-matching secrets in the given project.
func ListRegionalSecretsWithFilter(w io.Writer, projectId, locationId string, filter string) error {
	// parent := "projects/my-project/locations/my-location"
	// Follow https://cloud.google.com/secret-manager/docs/filtering
	// for filter syntax and examples.
	// filter := "name:name-substring"

	// Create the client.
	ctx := context.Background()
	//Endpoint to send the request to regional server
	endpoint := fmt.Sprintf("secretmanager.%s.rep.googleapis.com:443", locationId)
	client, err := secretmanager.NewClient(ctx, option.WithEndpoint(endpoint))

	if err != nil {
		return fmt.Errorf("failed to create regional secretmanager client: %w", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s", projectId, locationId)
	// Build the request.
	req := &secretmanagerpb.ListSecretsRequest{
		Parent: parent,
		Filter: filter,
	}

	// Call the API.
	it := client.ListSecrets(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}

		if err != nil {
			return fmt.Errorf("failed to list regional secrets: %w", err)
		}

		fmt.Fprintf(w, "Found regional secret %s\n", resp.Name)
	}

	return nil
}

Java

Para ejecutar este código, primero configura un entorno de desarrollo de Java e instala el SDK de Java para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

import com.google.cloud.secretmanager.v1.ListSecretsRequest;
import com.google.cloud.secretmanager.v1.LocationName;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient.ListSecretsPage;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient.ListSecretsPagedResponse;
import com.google.cloud.secretmanager.v1.SecretManagerServiceSettings;
import java.io.IOException;

public class ListRegionalSecretsWithFilter {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your GCP project ID.
    String projectId = "your-project-id";
    // Location of the secret.
    String locationId = "your-location-id";
    // Filter to be applied. 
    // See https://cloud.google.com/secret-manager/docs/filtering
    // for filter syntax and examples.
    String filter = "name:your-secret-substring AND expire_time<2022-01-01T00:00:00Z";
    listRegionalSecretsWithFilter(projectId, locationId, filter);
  }

  // List all secrets for a project
  public static ListSecretsPage listRegionalSecretsWithFilter(
      String projectId, String locationId, String filter) throws IOException {

    // Endpoint to call the regional secret manager sever
    String apiEndpoint = String.format("secretmanager.%s.rep.googleapis.com:443", locationId);
    SecretManagerServiceSettings secretManagerServiceSettings =
        SecretManagerServiceSettings.newBuilder().setEndpoint(apiEndpoint).build();

    // Initialize the client that will be used to send requests. This client only needs to be
    // created once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = 
        SecretManagerServiceClient.create(secretManagerServiceSettings)) {
      // Build the parent name.
      LocationName parent = LocationName.of(projectId, locationId);

      // Get filtered secrets.
      ListSecretsRequest request =
          ListSecretsRequest.newBuilder()
              .setParent(parent.toString())
              .setFilter(filter)
              .build();

      ListSecretsPagedResponse pagedResponse = client.listSecrets(request);

      // List all secrets.
      pagedResponse
          .iterateAll()
          .forEach(
              secret -> {
                System.out.printf("Regional secret %s\n", secret.getName());
              });

      return pagedResponse.getPage();
    }
  }
}

Python

Para ejecutar este código, primero configura un entorno de desarrollo de Python e instala el SDK de Python para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

# Import the Secret Manager client library.
from google.cloud import secretmanager_v1


def list_regional_secrets_with_filter(
    project_id: str, location_id: str, filter_str: str
) -> None:
    """
    Lists all regional secrets in the given project.
    """

    # Endpoint to call the regional secret manager sever.
    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"

    # Create the Secret Manager client.
    client = secretmanager_v1.SecretManagerServiceClient(
        client_options={"api_endpoint": api_endpoint},
    )

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}/locations/{location_id}"

    # List all secrets.
    for secret in client.list_secrets(request={"parent": parent, "filter": filter_str}):
        print(f"Found secret: {secret.name}")

Cómo filtrar una versión del Secret

Para filtrar una versión de un Secret, haz lo siguiente:

• En la consola de Google Cloud, selecciona un secreto para acceder a sus versiones y, luego, usa la opción Filtrar en la tabla Versiones.

• Si usas Google Cloud CLI o la API de Secret Manager, incluye una cadena filter cuando enumeres las versiones de secretos.

Ejemplos de filtros

Caso de uso	Filtro
Secretos cuyo nombre contiene la substring mysecret	name:mysecret
Secretos con una etiqueta específica	labels.environment=production
Secretos creados en un intervalo de tiempo o una fecha	create_time<2021-01-01T06:00:00Z AND create_time>2021-01-01T12:00:00Z
Secretos con replicación automática	replication.automatic:*
Secretos con replicación administrada por el usuario, pero no almacenados en ninguna de las regiones determinadas	replication.user_managed.replicas.location:* AND NOT replication.user_managed.replicas.location:(us-central1 OR us-east1)
Secretos encriptados con claves CMEK	replication.user_managed.replicas.customerManagedEncryption:*
Secretos encriptados con una clave CMEK específica	replication.user_managed.replicas.customerManagedEncryption.kmsKeyName=projects/p/locations/us-central1/keyRings/kr/cryptoKeys/my-cmek-key
Secretos sin un período de rotación	NOT rotation.next_rotation_time:*
Secretos con un período de rotación > 30d	rotation.rotation_period>259200s
Secretos con vencimiento establecido	expire_time:*
Secretos que vencen antes de una fecha	expire_time<2021-07-31
Versiones que están habilitadas o inhabilitadas	state:(ENABLED OR DISABLED)
Versiones destruidas, destruidas después de la fecha	state:DESTROYED AND destroy_time>2021-01-01

Sintaxis de filtro

La sintaxis de filtro consiste en una expresión de uno o más campos del objeto que se filtra.

Puedes usar los siguientes operadores de expresión.

Operador	Descripción
=	Igualdad
>	Superior a
<	Inferior a
>=	Superior o igual a
<=	Inferior o igual a
!= - NOT	Desigualdad Los siguientes son equivalentes: name!="topsecret" -name="topsecret" NOT name="topsecret"
:	Contención. Esta es una coincidencia de substring con distinción entre mayúsculas y minúsculas. Por ejemplo, name:"myapp" filtra en los recursos que contienen myapp (no distingue mayúsculas de minúsculas) en el nombre del recurso.
AND	AND lógico. Un espacio es equivalente a AND, por lo que los siguientes son equivalentes: name:"myapp" AND name:"secret1" name:"myapp" name:"secret1"
OR	Lógica OR.
*	Comodín. Se puede usar como un archivo independiente en el que field:* indica que está configurado field.

De acuerdo con la API de Cloud Search, las operaciones OR se evalúan antes que las operaciones AND, a menos que se usen paréntesis para definir explícitamente un orden diferente.

Cuando filtras valores time, codifica la hora como una string en el formato RFC 3399, como 2020-10-15T01:30:15Z.

Cuando accedas a un subcampo, usa la sintaxis de punto. Por ejemplo, el recurso Secret puede incluir el campo labels cuyo valor es un par clave-valor map. Si se usa una etiqueta color, puedes filtrar los resultados de Secret en el subcampo labels.color de la siguiente manera:

labels.color=red

Si deseas enumerar solo los secretos con el conjunto de etiquetas color, usa un comodín:

labels.color:*

Una string entre comillas se interpreta como un valor único en lugar de como una secuencia de valores.

Filtra campos

Puedes filtrar en cualquier campo de objeto Secret o SecretVersion.

Método de lista	Vínculo a los campos filtrables
projects.secrets.list	Campos secretos
projects.secrets.versions.list	Campos SecretVersion

Recuento total de resultados

Si filter se establece en una solicitud de lista, la respuesta no indica el recuento total de resultados (total_size=0 en la respuesta).

¿Qué sigue?

• Cómo editar un Secret regional
• Cómo establecer una fecha de vencimiento para un Secret regional