Adicione uma versão do Secret regional

Os dados secretos são imutáveis e a maioria das operações ocorre em versões secretas. Uma versão do Secret contém os dados secretos reais, juntamente com o estado e os metadados sobre o Secret. 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, clique no separador Segredos regionais e, de seguida, 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

Certifique-se de que configurou o Secret Manager para usar um ponto final regional para gerir segredos regionais.

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
  • LOCATION: a Google Cloud localização 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 --location=LOCATION --data-file="FILE_PATH"

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud secrets versions add SECRET_ID --location=LOCATION --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 --location=LOCATION --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
  • LOCATION: a Google Cloud localização 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
  • LOCATION: a Google Cloud localização 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 --location=LOCATION --data-file="FILE_PATH"

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION --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:

  • LOCATION: a Google Cloud localização do segredo
  • 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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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\""
}

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"
	"google.golang.org/api/option"
)

// addSecretVersion adds a new secret version to the given secret with the
// provided payload.
func AddRegionalSecretVersion(w io.Writer, projectId, locationId, secretId string) error {
	// parent := "projects/my-project/locations/my-location/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()

	//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/secrets/%s", projectId, locationId, secretId)

	// 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 regional secret version: %w", err)
	}
	fmt.Fprintf(w, "Added regional 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.SecretManagerServiceSettings;
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 AddRegionalSecretVersion {

  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";
    // Resource ID of the secret.
    String secretId = "your-secret-id";
    addRegionalSecretVersion(projectId, locationId, secretId);
  }

  // Add a new version to the existing regional secret.
  public static SecretVersion addRegionalSecretVersion(
      String projectId, String locationId, String secretId) 
      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 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)) {
      SecretName secretName = 
          SecretName.ofProjectLocationSecretName(projectId, locationId, secretId);
      byte[] data = "my super secret data".getBytes();
      // Calculate data checksum. The library is available in Java 9+.
      // For Java 8, use:
      // 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 regional secret version %s\n", version.getName());

      return version;
    }
  }
}

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 projectId = 'my-project';
// const locationId = 'location';
// const secretId = 'my-secret';

const parent = `projects/${projectId}/locations/${locationId}/secrets/${secretId}`;
// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Adding the endpoint to call the regional secret manager sever
const options = {};
options.apiEndpoint = `secretmanager.${locationId}.rep.googleapis.com`;

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

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

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

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

addRegionalSecretVersion();

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_v1
import google_crc32c


def add_regional_secret_version(
    project_id: str,
    location_id: str,
    secret_id: str,
    payload: str,
) -> secretmanager_v1.SecretVersion:
    """
    Adds a new secret version to the given secret with the provided payload.
    """

    # 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 secret.
    parent = f"projects/{project_id}/locations/{location_id}/secrets/{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}")
    return response

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?