Filtrar secrets regionais e versões de secrets

Esta página explica o processo de filtragem de secrets e versões de secrets no Secret Manager. Em ambientes com vários secrets, a filtragem ajuda a identificar rapidamente secrets ou versões específicos sem rolar manualmente a lista inteira. É possível filtrar com base em critérios como rótulos, datas de criação ou padrões específicos em nomes de segredos, permitindo o gerenciamento focado de grupos específicos de segredos.

No Secret Manager, é possível filtrar segredos e versões de segredos usando a opção Filtrar no console do Google Cloud ou especificando critérios de filtro em uma chamada de API. Na Google Cloud CLI, é possível filtrar segredos e versões de segredos incluindo uma string filter ao listar segredos.

Filtrar secrets

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

Console

1. Acesse a página do Secret Manager no console do Google Cloud:

   Acessar o Secret Manager

2. Na página Secret Manager, clique na guia Secrets regionais.

3. Na tabela Chaves secretas regionais, clique no campo Filtro.

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

   A tabela é filtrada automaticamente com base nos valores inseridos. Os resultados são classificados por nome em ordem crescente.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

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

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• LOCATION: o local do Google Cloud do segredo
• PROJECT_ID: o ID do projeto do Google Cloud
• FILTER: a string de filtro. Os filtros são especificados como o parâmetro de querystring filter e precisam ser codificados para URL. Por exemplo, o filtro name:asecret OR name:bsecret seria codificado como URL como name%3Aasecret+OR+name%3Absecret. As expressões regulares não são compatíveis com a API.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Go

Para executar esse código, primeiro configure um ambiente de desenvolvimento do Go e instale o SDK do Go do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do 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 esse código, primeiro configure um ambiente de desenvolvimento do Java e instale o SDK do Java do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do 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 esse código, primeiro configure um ambiente de desenvolvimento do Python e instale o SDK do Python do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do 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}")

Filtrar uma versão do secret

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

• No console do Google Cloud, selecione um segredo para acessar as versões dele e use a opção Filtro na tabela Versões.

• Se você estiver usando a Google Cloud CLI ou a API Secret Manager, inclua uma string filter ao listar versões de segredos.

Exemplos de filtros

Caso de uso	Filtro
Os secrets com nome que contém a substring mysecret	name:mysecret
Secrets com um rótulo específico	labels.environment=production
Secrets criados dentro do intervalo de data/hora	create_time<2021-01-01T06:00:00Z AND create_time>2021-01-01T12:00:00Z
Secrets com replicação automática	replication.automatic:*
Secrets com replicação gerenciada pelo usuário, mas não armazenados em nenhuma das regiões informadas	replication.user_managed.replicas.location:* AND NOT replication.user_managed.replicas.location:(us-central1 OR us-east1)
Secrets criptografados com chaves CMEK	replication.user_managed.replicas.customerManagedEncryption:*
Secrets criptografados com uma chave CMEK específica	replication.user_managed.replicas.customerManagedEncryption.kmsKeyName=projects/p/locations/us-central1/keyRings/kr/cryptoKeys/my-cmek-key
Chaves secretas sem um período de rotação	NOT rotation.next_rotation_time:*
Secrets com período de rotação > 30d	rotation.rotation_period>259200s
Secrets com expiração definida	expire_time:*
Os secrets 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 em uma expressão em um ou mais campos dos objetos que estão sendo filtrados.

Você pode usar os seguintes operadores de expressão.

Operador	Descrição
=	Igual a
>	Maior que
<	Menor que
>=	Maior que ou igual a
<=	Menor que ou igual a
!= - NOT	Diferente de Os seguintes são equivalentes: name!="topsecret" -name="topsecret" NOT name="topsecret"
:	Contenção. Essa é uma correspondência de substring que não diferencia maiúsculas de minúsculas. Por exemplo, name:"myapp" filtra recursos que contêm myapp (não diferencia maiúsculas de minúsculas) no nome do recurso.
AND	Lógico AND Um espaço é equivalente a AND, portanto, o seguinte é equivalente: name:"myapp" AND name:"secret1" name:"myapp" name:"secret1"
OR	"OU" lógico.
*	Curinga. Pode ser usada como autônoma, em que field:* indica que field está definido.

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

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

Ao acessar um subcampo, use a sintaxe de ponto. Por exemplo, o recurso Secret pode incluir o campo labels, cujo valor é uma chave-valor map. Se um rótulo color for usado, será possível filtrar os resultados de Secret no subcampo labels.color da seguinte maneira:

labels.color=red

Para listar apenas secrets com o rótulo color definido, use um caractere curinga:

labels.color:*

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

Filtrar campos

É possível filtrar por qualquer campo de objeto Secret ou SecretVersion.

Método de lista	Link para campos que aceitam filtros
projects.secrets.list	Campos secretos
projects.secrets.versions.list	Campos SecretVersion

Contagem total de resultados

Se filter estiver definido em uma solicitação de lista, a resposta não indicará a contagem total de resultados (total_size=0 na resposta).

A seguir

• Editar um secret regional
• Definir a data de validade de um secret regional