Adicione uma versão do segredo

Os dados secretos são imutáveis e a maioria das operações ocorre em versões secretas. Uma versão secreta contém os dados secretos reais, juntamente com o estado e os metadados sobre o segredo. Esta página descreve como adicionar uma versão secreta.

Para mais informações sobre o controlo de versões, consulte este vídeo sobre o controlo de versões.

Funções necessárias

Para receber as autorizações de que precisa para adicionar uma versão secreta, peça ao seu administrador que lhe conceda as seguintes funções de IAM num segredo:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Não é possível conceder funções da IAM numa versão do Secret.

Adicione uma versão do segredo

Para adicionar uma versão secreta, 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, localize o segredo para o qual quer adicionar a nova versão.

  3. Clique no menu Ações associado a esse segredo e, de seguida, clique em Adicionar nova versão. É apresentada a caixa de diálogo Adicionar nova versão.

  4. No campo Valor secreto, introduza um valor para o segredo, como abcd1234. Em alternativa, pode carregar um ficheiro que contenha o valor secreto.

  5. Clique em Adicionar nova versão.

gcloud

Adicione uma versão do Secret a partir do conteúdo de um ficheiro no disco

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

  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
  • FILE_PATH: o caminho completo (incluindo o nome do ficheiro) para o ficheiro que contém os detalhes da versão

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

Windows (PowerShell)

gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

Windows (cmd.exe)

gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

A resposta contém a versão do Secret recém-criada.

Adicione uma versão do Secret diretamente na linha de comandos

Também pode adicionar uma versão secreta diretamente na linha de comandos, mas isto não é recomendado porque aparece como texto simples na lista de processos e pode ser capturada por outros utilizadores do sistema. Tenha em atenção que o comando com o texto simples também vai estar no histórico da shell.

  echo -n "SECRET_DATA" | \
      gcloud secrets versions add SECRET_ID --data-file=-

Substitua o seguinte:

  • SECRET_DATA: os dados que quer armazenar na versão secreta
  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo

Opcional: adicione uma versão a partir do conteúdo de um ficheiro quando criar um segredo pela primeira vez

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

  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
  • FILE_PATH: o caminho completo (incluindo o nome do ficheiro) para o ficheiro que contém os detalhes da versão

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets create SECRET_ID --data-file="FILE_PATH"

Windows (PowerShell)

gcloud secrets create SECRET_ID --data-file="FILE_PATH"

Windows (cmd.exe)

gcloud secrets create SECRET_ID --data-file="FILE_PATH"

A resposta contém a versão do Secret recém-criada.

REST

Codifique os dados secretos em Base64 e guarde-os como uma variável de shell.

$ SECRET_DATA=$(echo "seCr3t" | base64)

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

  • PROJECT_ID: o Google Cloud ID do projeto
  • SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo

Método HTTP e URL: 

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID:addVersion

Corpo JSON do pedido: 

{"payload": {"data": "${SECRET_DATA}"}}

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 POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID:addVersion"

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 POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID:addVersion" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/1",
  "createTime": "2024-03-25T08:24:13.153705Z",
  "state": "ENABLED",
  "etag": "\"161477e6071da9\""
}

C#

Para executar este código, primeiro configure um ambiente de programação em C# e instale o SDK em C# do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform. 


using System.Text;
using Google.Cloud.SecretManager.V1;
using Google.Protobuf;

public class AddSecretVersionSample
{
    public SecretVersion AddSecretVersion(
      string projectId = "my-project", string secretId = "my-secret",
      string data = "my secret data")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the resource name.
        SecretName secretName = new SecretName(projectId, secretId);

        // Convert the payload to bytes.
        SecretPayload payload = new SecretPayload
        {
            Data = ByteString.CopyFrom(data, Encoding.UTF8),
        };

        // Call the API.
        SecretVersion version = client.AddSecretVersion(secretName, payload);
        return version;
    }
}

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"
	"hash/crc32"
	"io"

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

// addSecretVersion adds a new secret version to the given secret with the
// provided payload.
func addSecretVersion(w io.Writer, parent string) error {
	// parent := "projects/my-project/secrets/my-secret"

	// Declare the payload to store.
	payload := []byte("my super secret data")
	// Compute checksum, use Castagnoli polynomial. Providing a checksum
	// is optional.
	crc32c := crc32.MakeTable(crc32.Castagnoli)
	checksum := int64(crc32.Checksum(payload, crc32c))

	// 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.AddSecretVersionRequest{
		Parent: parent,
		Payload: &secretmanagerpb.SecretPayload{
			Data:       payload,
			DataCrc32C: &checksum,
		},
	}

	// Call the API.
	result, err := client.AddSecretVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to add secret version: %w", err)
	}
	fmt.Fprintf(w, "Added secret version: %s\n", result.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.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.cloud.secretmanager.v1.SecretPayload;
import com.google.cloud.secretmanager.v1.SecretVersion;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.util.zip.CRC32C;
import java.util.zip.Checksum;

public class AddSecretVersion {

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

  // Add a new version to the existing secret.
  public static void addSecretVersion(String projectId, String secretId) 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()) {
      SecretName secretName = SecretName.of(projectId, secretId);
      byte[] data = "my super secret data".getBytes();
      // Calculate data checksum. The library is available in Java 9+.
      // If using Java 8, the following library may be used:
      // https://cloud.google.com/appengine/docs/standard/java/javadoc/com/google/appengine/api/files/Crc32c
      Checksum checksum = new CRC32C();
      checksum.update(data, 0, data.length);

      // Create the secret payload.
      SecretPayload payload =
          SecretPayload.newBuilder()
              .setData(ByteString.copyFrom(data))
              // Providing data checksum is optional.
              .setDataCrc32C(checksum.getValue())
              .build();

      // Add the secret version.
      SecretVersion version = client.addSecretVersion(secretName, payload);
      System.out.printf("Added secret version %s\n", version.getName());
    }
  }
}

Node.js

Para executar este código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform. 

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

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

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

// Payload is the plaintext data to store in the secret
const payload = Buffer.from('my super secret data', 'utf8');

async function addSecretVersion() {
  const [version] = await client.addSecretVersion({
    parent: parent,
    payload: {
      data: payload,
    },
  });

  console.log(`Added secret version ${version.name}`);
}

addSecretVersion();

PHP

Para executar este código, saiba primeiro como usar o PHP no Google Cloud e instale o SDK PHP do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform. 

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

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

    // Build the resource name of the parent secret and the payload.
    $parent = $client->secretName($projectId, $secretId);
    $secretPayload = new SecretPayload([
        'data' => 'my super secret data',
    ]);

    // Build the request.
    $request = AddSecretVersionRequest::build($parent, $secretPayload);

    // Access the secret version.
    $response = $client->addSecretVersion($request);

    // Print the new secret version name.
    printf('Added secret version: %s', $response->getName());
}

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. 

from google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

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

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

Ruby

Para executar este código, primeiro configure um ambiente de desenvolvimento Ruby e instale o SDK Ruby do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform. 

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

# 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_path project: project_id, secret: secret_id

# Add the secret version.
version = client.add_secret_version(
  parent:  name,
  payload: {
    data: "my super secret data"
  }
)

# Print the new secret version name.
puts "Added secret version: #{version.name}"

Estados da versão do Secret

Uma versão secreta pode estar num dos seguintes estados em qualquer altura:

  • Ativada: neste estado, é possível aceder à versão secreta e descrevê-la. Este é o estado predefinido de uma nova versão do segredo.

  • Desativada: neste estado, não é possível aceder à versão do Secret, mas o conteúdo do Secret continua a existir. Pode reativar a versão do Secret para restaurar o acesso.

  • Destruído: neste estado, o conteúdo da versão do segredo é rejeitado. Não é possível alterar a versão do Secret para outro estado.

As versões secretas ativadas e desativadas são faturadas. As versões do Secret no estado destruído não estão sujeitas a cobrança.

O que se segue?