Destroy a secret version

This topic describes how you can destroy a secret version. In the destroyed state, the secret version's contents are discarded. Destroying a secret version is permanent. You won't be able to access the secret any more. The secret version can't be changed to another state.

Before destroying a secret version, try disabling it and observe your application's behavior. You can re-enable the secret version if you encounter unexpected issues.

When you disable or destroy a secret or secret version, the change takes time to propagate through the system. If necessary, you can revoke IAM access to the secret. Changes to IAM permissions are consistent within seconds.

Important: To use Secret Manager with workloads running on Compute Engine or Google Kubernetes Engine, the underlying instance or node must have the cloud-platform OAuth scope. See accessing the Secret Manager API for more information.

Required roles

To get the permissions that you need to destroy a secret version, ask your administrator to grant you the Secret Manager Secret Version Manager (roles/secretmanager.secretVersionManager) IAM role on a secret. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Destroy a secret version

Console

1. Go to the Secret Manager page in the Google Cloud console.

   Go to the Secret Manager page

2. On the Secret Manager page, click on the Name of a secret.

3. On the Secret details page, in the Versions table, locate a secret version to access.

4. In the Actions column, click View more.

5. Click Destroy from the menu.

6. In the Destroy secret version dialog, enter the name of the secret.

7. Click the Destroy selected versions button.

gcloud

To use Secret Manager on the command line, first Install or upgrade to version 378.0.0 or higher of the Google Cloud CLI. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

$ gcloud secrets versions destroy version-id --secret="secret-id"

C#

To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

using Google.Cloud.SecretManager.V1;

public class DestroySecretVersionSample
{
    public SecretVersion DestroySecretVersion(
      string projectId = "my-project", string secretId = "my-secret", string secretVersionId = "123")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the resource name.
        SecretVersionName secretVersionName = new SecretVersionName(projectId, secretId, secretVersionId);

        // Call the API.
        SecretVersion version = client.DestroySecretVersion(secretVersionName);
        return version;
    }
}

Go

To run this code, first set up a Go development environment and install the Secret Manager Go SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

import (
	"context"
	"fmt"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)

// destroySecretVersion destroys the given secret version, making the payload
// irrecoverable. Other secrets versions are unaffected.
func destroySecretVersion(name string) error {
	// name := "projects/my-project/secrets/my-secret/versions/5"

	// Create the client.
	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &secretmanagerpb.DestroySecretVersionRequest{
		Name: name,
	}

	// Call the API.
	if _, err := client.DestroySecretVersion(ctx, req); err != nil {
		return fmt.Errorf("failed to destroy secret version: %w", err)
	}
	return nil
}

Java

To run this code, first set up a Java development environment and install the Secret Manager Java SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretVersion;
import com.google.cloud.secretmanager.v1.SecretVersionName;
import java.io.IOException;

public class DestroySecretVersion {

  public static void destroySecretVersion() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String secretId = "your-secret-id";
    String versionId = "your-version-id";
    destroySecretVersion(projectId, secretId, versionId);
  }

  // Destroy an existing secret version.
  public static void destroySecretVersion(String projectId, String secretId, String versionId)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {
      // Build the name from the version.
      SecretVersionName secretVersionName = SecretVersionName.of(projectId, secretId, versionId);

      // Destroy the secret version.
      SecretVersion version = client.destroySecretVersion(secretVersionName);
      System.out.printf("Destroyed secret version %s\n", version.getName());
    }
  }
}

Node.js

To run this code, first set up a Node.js development environment and install the Secret Manager Node.js SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const name = 'projects/my-project/secrets/my-secret/versions/5';

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Instantiates a client
const client = new SecretManagerServiceClient();

async function destroySecretVersion() {
  const [version] = await client.destroySecretVersion({
    name: name,
  });

  console.info(`Destroyed ${version.name}`);
}

destroySecretVersion();

PHP

To run this code, first learn about using PHP on Google Cloud and install the Secret Manager PHP SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\DestroySecretVersionRequest;

/**
 * @param string $projectId Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId  Your secret ID (e.g. 'my-secret')
 * @param string $versionId Your version ID (e.g. 'latest' or '5');
 */
function destroy_secret_version(string $projectId, string $secretId, string $versionId): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the secret version.
    $name = $client->secretVersionName($projectId, $secretId, $versionId);

    // Build the request.
    $request = DestroySecretVersionRequest::build($name);

    // Destroy the secret version.
    $response = $client->destroySecretVersion($request);

    // Print a success message.
    printf('Destroyed secret version: %s', $response->getName());
}

Python

To run this code, first set up a Python development environment and install the Secret Manager Python SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

def destroy_secret_version(
    project_id: str, secret_id: str, version_id: str
) -> secretmanager.DestroySecretVersionRequest:
    """
    Destroy the given secret version, making the payload irrecoverable. Other
    secrets versions are unaffected.
    """

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

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret version
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

    # Destroy the secret version.
    response = client.destroy_secret_version(request={"name": name})

    print(f"Destroyed secret version: {response.name}")

Ruby

To run this code, first set up a Ruby development environment and install the Secret Manager Ruby SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope.

# project_id = "YOUR-GOOGLE-CLOUD-PROJECT"  # (e.g. "my-project")
# secret_id  = "YOUR-SECRET-ID"             # (e.g. "my-secret")
# version_id = "YOUR-VERSION"               # (e.g. "5" or "latest")

# Require the Secret Manager client library.
require "google/cloud/secret_manager"

# Create a Secret Manager client.
client = Google::Cloud::SecretManager.secret_manager_service

# Build the resource name of the secret version.
name = client.secret_version_path(
  project:        project_id,
  secret:         secret_id,
  secret_version: version_id
)

# Destroy the secret version.
response = client.destroy_secret_version name: name

# Print a success message.
puts "Destroyed secret version: #{response.name}"

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.

$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id/versions/version-id:destroy" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json"

Delayed destruction of secret versions

The Secret Manager Admin can set up delayed destruction of secret versions by turning on the feature Delay secret version dstroy on the secret. If this feature is turned on, the secret version isn't immediately destroyed upon request. Instead, the secret version is disabled and scheduled for destruction at a later date. During this time, the Secret Manager Admin can restore the secret version. To learn more, see Delay destruction of secret versions

What's next

• Learn how to ensure data integrity.
• Learn about best practices.