Regionale Secrets und Secret-Versionen filtern

Auf dieser Seite wird beschrieben, wie Sie Secrets und Secret-Versionen in Secret Manager filtern. In Umgebungen mit zahlreichen Secrets können Sie mithilfe des Filters schnell bestimmte Secrets oder Versionen finden, ohne manuell durch die gesamte Liste scrollen zu müssen. Sie können nach Kriterien wie Labels, Erstellungsdatum oder bestimmten Mustern in geheimen Namen filtern, um bestimmte Gruppen von Geheimnissen gezielt zu verwalten.

In Secret Manager können Sie mit der Option Filter in der Google Cloud Console oder durch Angabe von Filterkriterien in einem API-Aufruf nach Geheimnissen und Geheimversionsvarianten filtern. In der Google Cloud CLI können Sie Secrets und Secret-Versionen filtern, indem Sie beim Auflisten von Secrets einen filter-String angeben.

Secrets filtern

Sie haben folgende Möglichkeiten, ein Secret zu filtern:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie auf der Seite Secret Manager auf den Tab Regionale Secrets.

  3. Klicken Sie in der Tabelle Regionale Secrets in das Feld Filter.

  4. Wählen Sie ein Filterattribut und den entsprechenden Wert aus, z. B. Location:asia-east1.

    Die Tabelle wird automatisch anhand der eingegebenen Werte gefiltert. Die Ergebnisse werden in aufsteigender Reihenfolge nach Name sortiert.

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • LOCATION: den Speicherort des Geheimnisses in Google Cloud
  • FILTER: Der Filterstring, z. B. name:asecret OR name:bsecret. Die gcloud CLI unterstützt auch reguläre Ausdrücke, z. B. name ~ "secret_ab.*".

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • LOCATION: den Speicherort des Geheimnisses in Google Cloud
  • PROJECT_ID: die Google Cloud-Projekt-ID
  • FILTER: den Filterstring. Filter werden als filter-Abfragestringparameter angegeben und müssen URL-codiert sein. Der Filter name:asecret OR name:bsecret wäre beispielsweise als name%3Aasecret+OR+name%3Absecret URL-codiert. Reguläre Ausdrücke werden in der API nicht unterstützt.

HTTP-Methode und URL:

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

JSON-Text der Anfrage:

{}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

Go

Um diesen Code auszuführen, müssen Sie zuerst eine Go-Entwicklungsumgebung einrichten und das Secret Manager Go SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Java-Entwicklungsumgebung einrichten und das Secret Manager Java SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

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

Um diesen Code auszuführen, müssen Sie zuerst eine Python-Entwicklungsumgebung einrichten und das Secret Manager Python SDK installieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

# 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}")

Secret-Version filtern

So filtern Sie eine geheime Version:

  • Wählen Sie in der Google Cloud Console ein Geheimnis aus, um auf seine Versionen zuzugreifen, und verwenden Sie dann die Option Filter in der Tabelle Versionen.

  • Wenn Sie die Google Cloud CLI oder die Secret Manager API verwenden, fügen Sie beim Auflisten von Secret-Versionen einen filter-String hinzu.

Beispiele für Filter

Anwendungsfall Filter
Secrets, deren Name den Teilstring mysecret enthält name:mysecret
Secrets mit einem bestimmten Label labels.environment=production
Secrets, die innerhalb des Datums-/Zeitbereichs erstellt wurden create_time<2021-01-01T06:00:00Z AND create_time>2021-01-01T12:00:00Z
Secrets mit automatischer Replikation replication.automatic:*
Secrets mit vom Nutzer verwalteter Replikation, die aber in keiner der angegebenen Regionen gespeichert sind replication.user_managed.replicas.location:* AND NOT replication.user_managed.replicas.location:(us-central1 OR us-east1)
Mit CMEK-Schlüsseln verschlüsselte Secrets replication.user_managed.replicas.customerManagedEncryption:*
Secrets, die mit einem bestimmten CMEK-Schlüssel verschlüsselt wurden replication.user_managed.replicas.customerManagedEncryption.kmsKeyName=projects/p/locations/us-central1/keyRings/kr/cryptoKeys/my-cmek-key
Secrets ohne Rotationszeitraum NOT rotation.next_rotation_time:*
Secrets mit einem Rotationszeitraum > 30 d rotation.rotation_period>259200s
Secrets mit festgelegtem Ablauf expire_time:*
Secrets, die vor einem Datum ablaufen expire_time<2021-07-31
Aktivierte oder deaktivierte Versionen state:(ENABLED OR DISABLED)
Nach dem Datum gelöschte Versionen state:DESTROYED AND destroy_time>2021-01-01

Filtersyntax

Die Filtersyntax besteht aus einem Ausdruck für ein oder mehrere Felder der zu filternden Objekte.

Sie können die folgenden Operatoren verwenden.

Operator Beschreibung
= Gleich.
> Größer als.
< Kleiner als.
>= Größer als oder gleich.
<= Kleiner als oder gleich.
!=
-
NOT
Ungleich. Folgendes ist äquivalent:
name!="topsecret"
-name="topsecret"
NOT name="topsecret"
:

Eingrenzung. Dies ist ein Teilstring-Abgleich, bei dem die Groß- und Kleinschreibung nicht berücksichtigt wird.

Beispielsweise filtert name:"myapp" nach Ressourcen, deren Ressourcenname myapp enthält (ohne Berücksichtigung der Groß-/Kleinschreibung).

AND

Logisches UND.

Ein Leerzeichen ist gleichbedeutend mit AND. Daher ist Folgendes äquivalent:
name:"myapp" AND name:"secret1"
name:"myapp" name:"secret1"

OR Logisches ODER.
*

Platzhalter.

Kann eigenständig verwendet werden, wobei field:* angibt, dass field festgelegt ist.

Wie bei der Cloud Search API werden OR-Vorgänge vor AND-Vorgängen ausgewertet, sofern nicht durch Klammern eine andere Reihenfolge explizit definiert wird.

Wenn nach time-Werten gefiltert wird, codieren Sie die Zeit als einen String im RFC 3399-Format. Beispiel: 2020-10-15T01:30:15Z

Verwenden Sie für den Zugriff auf ein untergeordnetes Feld die Punktsyntax. Die Ressource Secret kann beispielsweise das Feld labels enthalten, dessen Wert ein Schlüssel/Wert-Paar map ist. Wenn ein color-Label verwendet wird, können Sie Secret-Ergebnisse so nach dem Unterfeld labels.color filtern:

labels.color=red

Wenn Sie nur Secrets mit dem Label color auflisten möchten, verwenden Sie einen Platzhalter:

labels.color:*

Ein String in Anführungszeichen wird als einzelner Wert und nicht als Folge von Werten interpretiert.

Felder filtern

Sie können nach einem beliebigen Feld des Objekts Secret oder SecretVersion filtern.

List-Methode Link zu filterbaren Feldern
projects.secrets.list Secret-Felder
projects.secrets.versions.list SecretVersion-Felder

Gesamtzahl der Ergebnisse

Wenn filter in einer Auflistungsanfrage festgelegt ist, gibt die Antwort nicht die Gesamtzahl der Ergebnisse (total_size=0 in der Antwort) an.

Nächste Schritte