Usar tags de entidade para controle de simultaneidade otimista

O Secret Manager é compatível com o uso de tags de entidade (ETags) para controle de simultaneidade otimista.

Em alguns casos, dois processos que atualizam o mesmo recurso em paralelo podem interferir no outro. O último processo substitui o esforço do anterior.

As ETags oferecem um meio para o controle de simultaneidade otimista, permitindo que os processos verifiquem se um recurso foi modificado antes de agir.

Usar ETags com o Secret Manager

As seguintes solicitações de modificação de recurso são compatíveis com ETags:

Em uma solicitação secrets.patch, a ETag da solicitação é incorporada aos dados Secret. Todas as outras solicitações aceitam um parâmetro etag opcional.

Se uma ETag for fornecida e corresponder à ETag do recurso atual, a solicitação será bem-sucedida. Caso contrário, ocorrerá uma falha com um erro FAILED_PRECONDITION e um código de status HTTP 400. Se uma ETag não for fornecida, a solicitação prosseguirá sem verificar o valor da ETag armazenada no momento.

As ETags do recurso são geradas na criação dos recursos (projects.secrets.create, projects.secrets.addVersion) e atualizadas para cada modificação listada acima. Uma solicitação de modificação só atualiza a ETag do recurso a que ela se aplica. Ou seja, a atualização de uma versão do secret não afeta a ETag do secret e vice-versa.

Uma atualização de recurso sem operação também atualiza a ETag do recurso. Por exemplo, considere o seguinte cenário: um autor da chamada emite uma solicitação para ativar uma versão do secret que já está ativada, sem que ele esteja ciente. A solicitação é processada com sucesso, não altera o estado da versão, mas altera a ETag da versão. Outro autor da chamada, usando a ETag mais antiga, tenta desativar a mesma versão. A solicitação falha, porque capturamos a intent para ativar a versão antes da solicitação de desativação na ETag modificada.

O recurso etag é retornado na resposta sempre que um recurso (Secret ou SecretVersion) for incluído.

Uso

Importante: para usar o Gerenciador de secrets com cargas de trabalho em execução no Compute Engine ou no Google Kubernetes Engine, a instância ou o nó subjacente precisa ter o escopo cloud-platform do OAuth de dados. Para mais informações, consulte Como acessar a API Secret Manager.

Excluir um secret com etags

Isso demonstra o uso de ETags ao excluir um secret. Se o secret tiver sido modificado por outro processo, a operação de exclusão falhará.

gcloud

Para usar o Secret Manager na linha de comando, primeiro instale ou faça upgrade para a versão 378.0.0 ou mais recente da Google Cloud CLI. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform.

A etag precisa incluir aspas. Por exemplo, se o valor de etag for "abc", o valor de escape do shell será "\"abc\"".

gcloud beta secrets delete "SECRET_ID" \
    --etag "ETAG"

Também é possível especificar ETags durante outras operações de mutação de secrets:

API

Esses exemplos usam curl para demonstrar o uso da API. É possível gerar tokens de acesso com o gcloud auth print-access-token. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform.

A ETag é especificada como parte da querystring do URL e precisa ser codificada para URL. Por exemplo, se o valor de etag for "abc", o valor codificado por URL será %22abc%22 porque o caractere de aspas está codificado como %22.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG" \
    --request "DELETE" \
    --header "Authorization: Bearer ACCESS_TOKEN"

Atualizar um secret com eTags

Isso demonstra o uso de ETags ao atualizar um secret. Se o secret tiver sido modificado por outro processo, a operação de atualização falhará.

gcloud

A etag precisa incluir aspas. Por exemplo, se o valor de etag for "abc", o valor de escape do shell será "\"abc\"".

gcloud beta secrets update "SECERT_ID" \
    --update-labels "foo=bar" \
    --etag "ETAG"

Também é possível especificar ETags durante outras operações de mutação de secrets:

API

A ETag é especificada como um campo no Secret e precisa incluir as aspas ao redor. Por exemplo, se o valor de etag for "abc", o valor de escape com JSON será {"etag":"\"abc\""}.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels" \
    --request "PATCH" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"etag":"ETAG", "labels":{"foo": "bar"}}'

Atualizar uma versão do secret com ETags

Isso demonstra o uso de ETags ao atualizar uma versão do secret. Se a versão do secret tiver sido modificada por outro processo, a operação de atualização falhará.

gcloud

A etag precisa incluir aspas. Por exemplo, se o valor de etag for "abc", o valor de escape do shell será "\"abc\"".

gcloud beta secrets versions disable "VERSION_ID" \
    --secret "SECRET_ID" \
    --etag "ETAG"

Também é possível especificar ETags durante outras operações de mutação de versão do secret:

API

A ETag é especificada como um campo no SecretVersion e precisa incluir as aspas ao redor. Por exemplo, se o valor de etag for "abc", o valor de escape com JSON será {"etag":"\"abc\""}.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable" \
    --request "POST" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"etag":"ETAG"}'

A seguir

Saiba como configurar programações de rotação para secrets.
Saiba como editar secrets.
Saiba como configurar notificações em um secret.