Criar e gerenciar anotações

Nesta página, descrevemos como adicionar anotações a um secret regional e como editar e visualizar essas anotações.

Visão geral

É possível usar anotações para armazenar metadados personalizados sobre um secret. Por exemplo, talvez você queira anotar um segredo com o caminho em que ele será montado. As anotações podem ser úteis das seguintes maneiras:

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

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

  • Para fornecer dicas sobre como o secret deve ser usado ou considerações especiais para o tratamento dele.

Por exemplo, se você tiver um secret com uma senha de banco de dados, adicione anotações como estas:

  • environment:production

  • purpose:database_access

  • owner:database_team

Com essas anotações, fica fácil identificar a finalidade do secret, o ambiente dele e quem é responsável por ele. Além disso, uma carga de trabalho que acessa esse secret pode usar as anotações para confirmar que está usando a senha correta para o ambiente de produção.

As anotações não são iguais aos rótulos. Os rótulos são usados para classificar, filtrar e agrupar recursos, enquanto as anotações são usadas para armazenar metadados arbitrários e não identificadores em um secret. Há uma restrição de caracteres e comprimento de caracteres ao especificar metadados em um rótulo. Os metadados de uma anotação podem ser pequenos ou grandes, estruturados ou não estruturados e incluir caracteres que não são permitidos em rótulos.

Funções exigidas

  • Para adicionar ou atualizar anotações em um secret, é necessário ter o papel de administrador do Secret Manager (roles/secretmanager.admin) no secret, projeto, pasta ou organização.

  • Para ver anotações, é necessário ter o papel de leitor do Secret Manager (roles/secretmanager.viewer) no secret, projeto, pasta ou organização.

Não é possível conceder papéis do Identity and Access Management (IAM) em uma versão do secret. Consulte Controle de acesso com o IAM para mais informações.

Adicionar anotações a um secret

É possível adicionar anotações ao criar ou atualizar um secret. Os metadados em uma anotação são armazenados como pares de chave-valor. Para adicionar anotações, use um dos métodos a seguir:

Console

  1. No console Google Cloud , acesse a página Secret Manager.

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais e em Criar secret regional.

  3. Na página Criar secret regional, insira um nome para o secret no campo Nome.

  4. Insira um valor para o secret (por exemplo, abcd1234). Também é possível fazer upload de um arquivo de texto com o valor do secret usando a opção Fazer upload do arquivo. Essa ação cria automaticamente a versão do secret.

  5. Selecione o local em que você quer armazenar o secret regional na lista Região.

  6. Acesse a seção Anotações e clique em Adicionar anotação.

  7. Insira a chave e o valor correspondente.

  8. Clique em Criar secret.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou o identificador totalmente qualificado do secret.
  • LOCATION: o Google Cloud local do secret
  • 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 --location=LOCATION \
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (PowerShell)

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

Windows (cmd.exe)

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

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o Google Cloud local do secret
  • PROJECT_ID: o ID do projeto Google Cloud
  • SECRET_ID: o ID do secret ou o identificador totalmente qualificado do secret.
  • KEY: a chave de anotação
  • VALUE: o valor correspondente da chave de anotação.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "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 secret, consulte a seção Editar anotações deste documento.

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

  • As chaves precisam ser exclusivas de um secret. Não é possível repetir uma chave no mesmo secret.

  • As chaves precisam ter entre 1 e 63 caracteres.

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

  • As chaves precisam começar e terminar com um caractere alfanumérico.

  • As chaves podem ter traços, sublinhados e pontos entre os caracteres alfanuméricos.

  • O tamanho total das chaves e dos valores de anotação precisa ser menor que 16 KiB.

Editar anotações

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

Console

  1. No console Google Cloud , acesse a página Secret Manager.

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais.

  3. Localize o secret na lista e clique no menu Ações associado a ele. No menu Ações, clique em Editar.

  4. Na página Editar secret, acesse a seção Anotações. Aqui, você pode mudar o valor de uma anotação, excluir ou adicionar uma nova.

  5. Depois de fazer as mudanças, clique em Atualizar segredo.

gcloud

Editar anotações

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou o identificador totalmente qualificado do secret.
  • LOCATION: o Google Cloud local do secret
  • 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 --location=LOCATION --update-annotations= KEY=VAL

Windows (PowerShell)

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

Windows (cmd.exe)

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

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

Remover uma anotação específica

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

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

Limpar todas as anotações

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

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o Google Cloud local do secret
  • PROJECT_ID: o ID do projeto Google Cloud
  • SECRET_ID: o ID do secret ou o identificador totalmente qualificado do secret.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{'annotations': {}}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

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

Ver anotações

Para conferir as anotações anexadas a um secret, use um dos seguintes métodos:

Console

  1. No console Google Cloud , acesse a página Secret Manager.

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais e depois no secret cujas anotações você quer visualizar.

  3. A página de detalhes do secret é aberta. Clique na guia Visão geral. Aqui você pode conferir as anotações anexadas ao secret. As chaves são listadas na coluna à esquerda, e os valores são mostrados na coluna à direita.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou o identificador totalmente qualificado do secret.
  • LOCATION: o Google Cloud local do secret

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets describe SECRET_ID --location=LOCATION

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o Google Cloud local do secret
  • PROJECT_ID: o ID do projeto Google Cloud
  • SECRET_ID: o ID do secret ou o identificador totalmente qualificado do secret.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

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

A seguir