Crie e faça a gestão de anotações

Esta página descreve como adicionar anotações a um segredo e como editar e ver estas anotações.

Vista geral

Pode usar anotações para armazenar metadados personalizados sobre um segredo. Por exemplo, pode querer anotar um segredo com o caminho no qual vai ser montado. As anotações podem ser úteis das seguintes formas:

  • Para categorizar segredos com base na respetiva finalidade, ambiente (desenvolvimento, teste, produção) ou nível de sensibilidade. Isto facilita a pesquisa, a filtragem e a organização de segredos no Secret Manager.

  • Para indicar o formato ou a estrutura específicos do valor do segredo, ajudando a carga de trabalho a interpretá-lo corretamente.

  • Para fornecer sugestões sobre como o segredo deve ser usado ou quaisquer considerações especiais para o respetivo processamento.

Por exemplo, se tiver um segredo que contenha uma palavra-passe da base de dados, pode adicionar anotações, como as seguintes:

  • environment:production

  • purpose:database_access

  • owner:database_team

Estas anotações facilitam a identificação da finalidade do segredo, do respetivo ambiente e do responsável pelo mesmo. Além disso, uma carga de trabalho que aceda a este segredo pode usar as anotações para confirmar que está a usar a palavra-passe correta para o ambiente de produção.

As anotações não são o mesmo que as etiquetas. As etiquetas são usadas para ordenar, filtrar e agrupar recursos, enquanto as anotações são usadas para armazenar metadados arbitrários e não identificadores num segredo. Existe uma restrição de carateres e comprimento de carateres quando especifica metadados numa etiqueta. Os metadados numa anotação podem ser pequenos ou grandes, estruturados ou não estruturados, e podem incluir carateres não permitidos por etiquetas.

Funções necessárias

  • A adição de anotações a uma chave secreta e a atualização das anotações requerem a função de administrador do Secret Manager (roles/secretmanager.admin) na chave secreta, no projeto, na pasta ou na organização.

  • A visualização de anotações requer a função de visualizador do Secret Manager (roles/secretmanager.viewer) no segredo, projeto, pasta ou organização.

Não é possível conceder funções da gestão de identidade e de acesso (IAM) numa versão secreta. Consulte o artigo Controlo de acesso com a IAM para mais informações.

Adicione anotações a um segredo

Pode adicionar anotações no momento da criação de um novo segredo ou da atualização de um segredo existente. Os metadados numa anotação são armazenados como pares de chave-valor. Para adicionar anotações, 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 em Criar segredo.

  3. Na página Criar segredo, introduza um nome para o segredo no campo Nome.

  4. Introduza um valor para o segredo (por exemplo, abcd1234). Também pode carregar um ficheiro de texto que contenha o valor do segredo através da opção Carregar ficheiro. Esta ação cria automaticamente a versão do Secret.

  5. Aceda à secção Anotações e, de seguida, clique em Adicionar anotação.

  6. Introduza a chave e o valor correspondente.

  7. Clique em Criar segredo.

gcloud

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
  • KEY: a chave de anotação
  • VALUE: o valor correspondente da chave de anotação

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets create SECRET_ID \
    --set-annotations= KEY1=VAL1,KEY2=VAL2

Windows (PowerShell)

gcloud secrets create SECRET_ID `
    --set-annotations= KEY1=VAL1,KEY2=VAL2

Windows (cmd.exe)

gcloud secrets create SECRET_ID ^
    --set-annotations= KEY1=VAL1,KEY2=VAL2

A resposta contém o segredo e as anotações.

REST

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
  • KEY: a chave de anotação
  • VALUE: o valor correspondente da chave de anotação

Método HTTP e URL: 

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

Corpo JSON do pedido: 

{'annotations': {'KEY1': 'VALUE1', 'KEY2': 'VALUE2' }}

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 PATCH \
     -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?updateMask=annotations"

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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

Para adicionar anotações a um segredo existente, consulte a secção Editar anotações deste documento.

As chaves de anotação têm os seguintes requisitos:

  • As chaves têm de ser exclusivas de um segredo. Não pode repetir uma chave no mesmo segredo.

  • As chaves têm de ter entre 1 e 63 carateres.

  • As chaves têm de ter uma codificação UTF-8 de, no máximo, 128 bytes.

  • As chaves têm de começar e terminar com um caráter alfanumérico.

  • As chaves podem ter travessões, sublinhados e pontos entre os carateres alfanuméricos.

  • O tamanho total das chaves e dos valores de anotação tem de ser inferior a 16 KiB.

Edite anotações

Para editar anotações, use um dos seguintes métodos:

Consola

  1. Na Google Cloud consola, aceda à página Secret Manager.

    Aceda ao Secret Manager

  2. Localize o segredo na lista e clique no menu Ações associado a esse segredo. No menu Ações, clique em Editar.

  3. Na página Editar segredo, aceda à secção Anotações. Aqui, pode alterar o valor de uma anotação existente, eliminar a anotação ou adicionar uma nova anotação.

  4. Depois de fazer as alterações, clique em Atualizar segredo.

gcloud

Edite anotações existentes

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
  • KEY: a chave de anotação
  • VALUE: o valor correspondente da chave de anotação

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

Windows (PowerShell)

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

Windows (cmd.exe)

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

A resposta edita o segredo e as anotações.

Remova uma anotação específica

Para remover anotações, use o seguinte comando:

gcloud secrets update SECRET_ID --remove-annotations= KEY=VAL

Limpe todas as anotações

Para limpar todas as anotações, use o seguinte comando:

gcloud secrets update SECRET_ID --clear-annotations

REST

Para limpar todas as anotações, use o seguinte comando:

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: 

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

Corpo JSON do pedido: 

{'annotations': {}}

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 PATCH \
     -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?updateMask=annotations"

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

Deve receber uma resposta JSON semelhante à seguinte:

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

Veja anotações

Para ver as anotações anexadas a um segredo, 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 segredo cujas anotações quer ver.

  3. É apresentada a página de detalhes do segredo. Clique no separador Vista geral. Aqui, pode ver as anotações anexadas ao segredo. As chaves são apresentadas na coluna do lado esquerdo, enquanto os valores são apresentados na coluna do lado direito.

gcloud

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

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets describe SECRET_ID

Windows (PowerShell)

gcloud secrets describe SECRET_ID

Windows (cmd.exe)

gcloud secrets describe SECRET_ID

A resposta contém o segredo e as anotações.

REST

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: 

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

Corpo JSON do pedido: 

{}

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 GET \
     -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"

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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

O que se segue?