Criar e gerenciar anotações

Esta página descreve como adicionar anotações a um segredo regional e como editar e visualizar essas anotações.

Visão geral

É possível usar anotações para armazenar metadados personalizados sobre um segredo. 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:

• Categorizar segredos com base na finalidade, no ambiente (desenvolvimento, testes, produção) ou no nível de sensibilidade. Isso facilita a pesquisa, o filtro e a organização de segredos no Secret Manager.

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

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

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

• environment:production

• purpose:database_access

• owner:database_team

Essas anotações facilitam a identificação da finalidade do segredo, do ambiente e de quem é responsável por ele. Além disso, uma carga de trabalho que acessa esse segredo pode usar as anotações para confirmar se 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 segredo. Há uma restrição de caracteres e comprimento 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 por rótulos.

Funções exigidas

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

• Para visualizar anotações, é necessário ter o papel de leitor de secrets (roles/secretmanager.viewer) no secret, no projeto, na pasta ou na 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 um novo secret ou atualizar um existente. Os metadados em uma anotação são armazenados como pares de chave-valor. Para adicionar anotações, use um dos seguintes métodos:

Console

1. Acesse a página do Secret Manager no console do Google Cloud:

   Acessar o Secret Manager

2. Na página Secret Manager, clique na guia Regional secrets 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 do identificador totalmente qualificado
• LOCATION: o local do Google Cloud 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

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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 local do Google Cloud do segredo
• PROJECT_ID: o ID do projeto do Google Cloud
• SECRET_ID: o ID do secret ou do identificador totalmente qualificado
• 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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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 para 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 destes métodos:

Console

1. Acesse a página do Secret Manager no console do Google Cloud:

   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 existente, excluí-la 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 do identificador totalmente qualificado
• LOCATION: o local do Google Cloud 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

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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 local do Google Cloud do segredo
• PROJECT_ID: o ID do projeto do Google Cloud
• SECRET_ID: o ID do secret ou do identificador totalmente qualificado

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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

Conferir anotações

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

Console

1. Acesse a página do Secret Manager no console do Google Cloud:

   Acessar o Secret Manager

2. Na página Secret Manager, clique na guia Regional secrets e, em seguida, clique no secret com as anotações que você quer conferir.

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 do identificador totalmente qualificado
• LOCATION: o local do Google Cloud do segredo

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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 local do Google Cloud do segredo
• PROJECT_ID: o ID do projeto do Google Cloud
• SECRET_ID: o ID do secret ou do identificador totalmente qualificado

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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

• Criar programações de rotação
• Definir a data de validade de um secret regional