Filtre segredos regionais e versões de segredos

Esta página explica o processo de filtragem de segredos e versões de segredos no Secret Manager. Em ambientes com vários segredos, a filtragem ajuda a identificar rapidamente segredos ou versões específicos sem ter de percorrer manualmente toda a lista. Pode filtrar com base em critérios como etiquetas, datas de criação ou padrões específicos nos nomes dos segredos, o que permite uma gestão focada de grupos específicos de segredos.

No Secret Manager, pode filtrar segredos e versões de segredos através da opção Filtrar na consola Google Cloud ou especificando critérios de filtro numa chamada API. Na Google Cloud CLI, pode filtrar segredos e versões de segredos incluindo uma string filter ao listar segredos.

Filtre segredos

Para filtrar um segredo, use um dos seguintes métodos:

Consola

  1. Na Google Cloud consola, aceda à página Secret Manager.

    Aceda ao Secret Manager

  2. Na página Secret Manager, clique no separador Segredos regionais.

  3. Na tabela Segredos regionais, clique no campo Filtro.

  4. Escolha uma propriedade de filtro e o respetivo valor, por exemplo, Location:asia-east1.

    A tabela é filtrada automaticamente com base nos valores introduzidos. Os resultados são ordenados por nome por ordem ascendente.

gcloud

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • LOCATION: a Google Cloud localização do segredo
  • FILTER: a string de filtro, por exemplo, name:asecret OR name:bsecret. A CLI gcloud também suporta expressões regulares, por exemplo, name ~ "secret_ab.*".

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION: a Google Cloud localização do segredo
  • PROJECT_ID: o Google Cloud ID do projeto
  • FILTER: a string de filtro. Os filtros são especificados como o filter parâmetro de string de consulta e têm de ser codificados por URL. Por exemplo, o filtro name:asecret OR name:bsecret seria codificado por URL como name%3Aasecret+OR+name%3Absecret. As expressões regulares não são suportadas na API.

Método HTTP e URL:

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

Corpo JSON do pedido:

{}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte:

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

Go

Para executar este código, primeiro configure um ambiente de desenvolvimento Go e instale o SDK Go do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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 executar este código, primeiro configure um ambiente de desenvolvimento Java e instale o SDK Java do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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 executar este código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK Python do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito 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}")

Filtre uma versão do Secret

Para filtrar uma versão do Secret, faça o seguinte:

  • Na Google Cloud consola, selecione um segredo para aceder às respetivas versões e, de seguida, use a opção Filtrar na tabela Versões.

  • Se estiver a usar a CLI Google Cloud ou a API Secret Manager, inclua uma string filter quando listar versões secretas.

Exemplos de filtros

Exemplo de utilização Filtro
Secrets cujo nome contém a substring mysecret name:mysecret
Segredos com uma etiqueta específica labels.environment=production
Segredos criados no intervalo de data/hora create_time<2021-01-01T06:00:00Z AND create_time>2021-01-01T12:00:00Z
Segredos com replicação automática replication.automatic:*
Secrets com replicação gerida pelo utilizador, mas não armazenados em nenhuma das regiões indicadas replication.user_managed.replicas.location:* AND NOT replication.user_managed.replicas.location:(us-central1 OR us-east1)
Secrets encriptados com chaves CMEK replication.user_managed.replicas.customerManagedEncryption:*
Segredos encriptados com uma chave CMEK específica replication.user_managed.replicas.customerManagedEncryption.kmsKeyName=projects/p/locations/us-central1/keyRings/kr/cryptoKeys/my-cmek-key
Segredos sem um período de rotação NOT rotation.next_rotation_time:*
Segredos com um período de rotação superior a 30 dias rotation.rotation_period>259200s
Secrets com validade definida expire_time:*
Segredos que expiram antes de uma data expire_time<2021-07-31
Versões ativadas ou desativadas state:(ENABLED OR DISABLED)
Versões destruídas, destruídas após a data state:DESTROYED AND destroy_time>2021-01-01

Sintaxe do filtro

A sintaxe do filtro consiste numa expressão num ou mais campos dos objetos que estão a ser filtrados.

Pode usar os seguintes operadores de expressão.

Operador Descrição
= Igualdade.
> Maior que.
< Inferior a.
>= Maior ou igual a.
<= Menor ou igual a.
!=
-
NOT
Desigualdade. As seguintes opções são equivalentes:
name!="topsecret"
-name="topsecret"
NOT name="topsecret"
:

Contenção. Esta é uma correspondência de substring não sensível a maiúsculas e minúsculas.

Por exemplo, name:"myapp" filtra os recursos que contêm myapp (sem distinção entre maiúsculas e minúsculas) no nome do recurso.

AND

E lógico.

Um espaço é equivalente a AND, pelo que o seguinte é equivalente:
name:"myapp" AND name:"secret1"
name:"myapp" name:"secret1"

OR OU lógico.
*

Caráter universal.

Pode ser usado como um elemento autónomo onde field:* indica que field está definido.

De acordo com a Cloud Search API, as operações OR são avaliadas antes das operações AND, a menos que sejam usados parênteses para definir explicitamente uma ordem diferente.

Quando filtrar por valores time, codifique a hora como uma string no formato RFC 3399, como 2020-10-15T01:30:15Z.

Ao aceder a um subcampo, use a sintaxe de ponto. Por exemplo, o recurso Secret pode incluir o campo labels cujo valor é um par chave-valor map. Se for usada uma etiqueta color, pode filtrar os resultados Secret no subcampo labels.color da seguinte forma:

labels.color=red

Se quiser listar apenas segredos com a etiqueta color definida, use um caráter universal:

labels.color:*

Uma string entre aspas é interpretada como um único valor e não como uma sequência de valores.

Campos de filtro

Pode filtrar qualquer campo do objeto Secret ou SecretVersion.

Método de lista Link para campos filtráveis
projects.secrets.list Campos secretos
projects.secrets.versions.list Campos SecretVersion

Contagem total de resultados

Se filter estiver definido num pedido de lista, a resposta não indica a contagem total de resultados (total_size=0 na resposta).

O que se segue?