Gerenciar atributos usando metadados

Nesta página, descrevemos como gerenciar alguns recursos de instâncias do Workbench da Gemini Enterprise Agent Platform modificando os pares de chave-valor de metadados da instância.

Chaves de metadados

Para informações sobre recursos e as respectivas chaves de metadados, consulte a tabela a seguir.

Recurso	Descrição	Chave de metadados	Valores e padrões aceitos
Ativa o Cloud Storage FUSE em uma imagem de contêiner	Monta /dev/fuse no contêiner e ativa gcsfuse para uso no contêiner.	container-allow-fuse	true: ativa o Cloud Storage FUSE. false (padrão): não ativa o Cloud Storage FUSE.
nbconvert	Permite exportar e fazer o download de notebooks como um tipo de arquivo diferente.	notebook-disable-nbconvert	true: desativa o nbconvert. false (padrão): ativa o nbconvert.
Excluir para a lixeira	Usa o comportamento de lixeira do sistema operacional ao excluir do JupyterLab.	notebook-enable-delete-to-trash	true: ativa a exclusão para a lixeira. false (padrão): usa o comportamento padrão do JupyterLab.
Serviço Gerenciado para Apache Spark	Permite acesso aos kernels do Serviço Gerenciado para Apache Spark. Para mais informações, consulte Criar uma instância ativada para o Serviço Gerenciado para Apache Spark.	disable-mixer	true: desativa o acesso aos kernels do Serviço Gerenciado para Apache Spark. false (padrão): ativa o acesso aos kernels do Serviço Gerenciado para Apache Spark.
BigQuery	Ativa o plug-in do JupyterLab do BigQuery, que fornece um explorador de conjuntos de dados, um editor de consulta SQL e um histórico de consultas no JupyterLab.	disable-bigquery	true: desativa o plug-in do JupyterLab no BigQuery. false (padrão): ativa o plug-in do JupyterLab do BigQuery.
Encerramento por inatividade	Ativa o desligamento por inatividade. Para mais informações, consulte Desativação de inatividade.	idle-timeout-seconds	Um número inteiro que representa o tempo de inatividade em segundos. O valor padrão é de 10800 segundos (180 minutos).
Atributos de convidado	Ativa os atributos de convidado. Obrigatório para executar o desligamento por inatividade. Para mais informações, consulte Requisitos para executar o encerramento por inatividade.	enable-guest-attributes	true (padrão): ativa os atributos de convidado. false: desativa os atributos de convidado.
Correções do SO programadas	Programa atualizações automáticas do SO da instância. Ativa o serviço de upgrade não supervisionado do Debian e só se aplica a imagens baseadas em VM.	install-unattended-upgrades	true: ativa as atualizações automáticas do SO. false (padrão): desativa as atualizações automáticas do SO.
Usuário do Jupyter personalizado	Especifica o nome do usuário padrão do Jupyter. Essa configuração determina o nome da pasta para seus notebooks. Por exemplo, em vez do diretório /home/jupyter/ padrão, é possível alterar o diretório para /home/CUSTOM_NAME. Essa chave de metadados não afeta o acesso à instância.	jupyter-user	Uma string. O valor padrão é jupyter.
Permitir downloads do arquivo	Permite fazer o download de arquivos do JupyterLab.	notebook-disable-downloads	true: desativa o download de arquivos. false (padrão): ativa o download de arquivos.
Acesso raiz	Ativa o acesso raiz.	notebook-disable-root	true: desativa o acesso raiz. false (padrão): ativa o acesso raiz.
Acesso ao terminal	Permite o acesso ao terminal.	notebook-disable-terminal	true: desativa o acesso ao terminal. false (padrão): ativa o acesso ao terminal.
Upgrades programados	Programa upgrades automáticos da instância.	notebook-upgrade-schedule	A programação semanal ou mensal que você define, no formato unix-cron, por exemplo, 00 19 * * MON significa "semanalmente" às segundas-feiras, às 1900 horas, horário de Greenwich (GMT). Esse recurso fica desativado por padrão. Para desativar esse recurso ou mantê-lo desativado, omita a chave de metadados notebook-upgrade-schedule da configuração ou defina o valor dela como uma string vazia ("").
Script pós-inicialização	Executa um script personalizado depois que outros scripts de inicialização são concluídos. Para detalhes sobre a ordem de execução, consulte Ordem de execução do script de inicialização.	post-startup-script	O URI de um script de pós-inicialização no Cloud Storage, por exemplo: gs://bucket/hello.sh. Esse recurso fica desativado por padrão.
Comportamento do script de pós-inicialização	Define quando e como o script pós-inicialização é executado.	post-startup-script-behavior	run_once (padrão): executa o script de pós-inicialização uma vez após a criação ou o upgrade da instância. run_every_start: executa o script pós-inicialização após cada início. download_and_run_every_start: refaz o download do script de inicialização da origem e executa o script após cada início.
Reportar integridade do evento	Verifica a integridade a cada 30 segundos para métricas da VM.	report-event-health	true (padrão): ativa a geração de relatórios de integridade do evento. false: desativa os relatórios de integridade do evento.
Ativar o JupyterLab 4 ou mudar para o JupyterLab 3	Ative o JupyterLab 3. O JupyterLab 4 está ativado por padrão.	enable-jupyterlab4	true (padrão): ativa o JupyterLab 4. false: ativa o JupyterLab 3.
CLI do Antigravity	Ativa a CLI do Antigravity, com o bloco de inicialização, as habilidades de notebook, o plug-in e o comando mágico de célula %%agy, em instâncias que usam uma imagem do Debian 12 (workbench-instances-2603) ou posterior. A instância aplica o valor quando é iniciada.	enable-antigravity	true (padrão para novas instâncias): ativa a CLI do Antigravity. false: desativa a CLI do Antigravity.

Ordem de execução do script de inicialização

Se você usar vários scripts de inicialização para a instância do Agent Platform Workbench, eles serão executados na seguinte ordem:

1. startup-script: é executado primeiro durante cada inicialização após a inicialização inicial.
2. startup-script-url: é executado em segundo lugar durante cada inicialização após a inicialização inicial.
3. workbench-startup-scripts: é executado após a conclusão dos scripts de inicialização do Compute Engine (startup-script e startup-script-url).
4. post-startup-script: é executado após a conclusão de workbench-startup-scripts.

Para a chave de metadados post-startup-script, é preciso fornecer o script como um URI do Cloud Storage. Não é possível fornecer o conteúdo do script diretamente como o valor.

Metadados gerenciados pelo Compute Engine

Algumas das chaves de metadados são predefinidas pelo Compute Engine. Para mais informações, consulte Chaves de metadados predefinidas.

Chaves de metadados protegidas

Algumas chaves de metadados são reservadas somente para uso do sistema. Se você atribuir valores a essas chaves de metadados, os novos valores serão substituídos pelos do sistema.

As chaves de metadados reservadas incluem, entre outras:

• agent-health-check-interval-seconds
• agent-health-check-path
• cos-update-strategy
• custom-container-image
• custom-container-payload
• data-disk-uri
• dataproc-allow-custom-clusters
• dataproc-cluster-name
• dataproc-configs
• dataproc-default-subnet
• dataproc-locations-list
• dataproc-machine-types-list
• dataproc-notebooks-url
• dataproc-region
• dataproc-service-account
• disable-check-xsrf
• euc-enabled
• framework
• generate-diagnostics-bucket
• generate-diagnostics-file
• generate-diagnostics-options
• google-logging-enabled
• image-url
• install-monitoring-agent
• install-nvidia-driver
• installed-extensions
• last_updated_diagnostic
• last_updated_diagnostics
• notebooks-api
• notebooks-api-version
• notebooks-examples-location
• notebooks-location
• proxy-backend-id
• proxy-byoid-url
• proxy-mode
• proxy-status
• proxy-url
• proxy-user-mail
• report-container-health
• report-event-url
• report-notebook-metrics
• report-system-health
• report-system-status
• resource-url
• restriction
• serial-port-logging-enable
• service-account-mode
• shutdown-script
• title
• use-collaborative
• user-data
• version

Criar uma instância com metadados específicos

É possível criar uma instância do Agent Platform Workbench com metadados específicos usando o console do Google Cloud , a Google Cloud CLI, o Terraform ou a API Notebooks.

Console

Ao criar uma instância do Agent Platform Workbench, é possível adicionar metadados na seção Ambiente de Opções avançadas.

gcloud

Ao criar uma instância do Workbench da Plataforma de Agentes, é possível adicionar metadados usando o seguinte comando:

gcloud workbench instances create INSTANCE_NAME --metadata=KEY=VALUE

Terraform

Para adicionar metadados, crie o recurso com pares de chave-valor de metadados.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
    metadata = {
      key = "value"
    }
  }
}

API Notebooks

Use o método instances.create com valores de metadados para gerenciar os atributos correspondentes.

Atualizar os metadados de uma instância

É possível atualizar os metadados de uma instância do Agent Platform Workbench usando o console do Google Cloud , a Google Cloud CLI, o Terraform ou a API Notebooks.

Console

Para atualizar os metadados de uma instância do Agent Platform Workbench, faça o seguinte:

1. No console do Google Cloud , acesse a página Instâncias.

   Acesse "Instâncias"

2. Na lista de instâncias, clique no nome da instância que você quer atualizar.

3. Na página Detalhes da instância, clique em Software e segurança.

4. Na seção Metadados, atualize os pares de chave-valor de metadados que você quer alterar.

5. Clique em Enviar.

gcloud

É possível atualizar os metadados em uma instância do Agent Platform Workbench usando o comando a seguir:

gcloud workbench instances update INSTANCE_NAME --metadata=KEY=VALUE

Terraform

É possível alterar os pares de chave-valor de metadados para gerenciar os recursos correspondentes nas instâncias do Agent Platform Workbench.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
    metadata = {
      key = "updated_value"
    }
  }
}

API Notebooks

Use o método instances.patch com valores de metadados e gce_setup.metadata no updateMask para gerenciar os recursos correspondentes.

Remover metadados de uma instância

É possível remover metadados de uma instância do Agent Platform Workbench usando o console do Google Cloud , a Google Cloud CLI, o Terraform ou a API Notebooks.

Console

Para remover metadados de uma instância do Agent Platform Workbench, faça o seguinte:

1. No console do Google Cloud , acesse a página Instâncias.

   Acesse "Instâncias"

2. Na lista de instâncias, clique no nome da instância que você quer modificar.

3. Na página Detalhes da instância, clique em Software e segurança.

4. Na seção Metadados, à direita de um par de chave-valor que você quer excluir, clique em  Excluir.

5. Clique em Enviar.

gcloud

É possível remover metadados de uma instância do Agent Platform Workbench usando o seguinte comando:

gcloud workbench instances update INSTANCE_NAME --metadata=KEY

Terraform

É possível remover pares de chave-valor de metadados para gerenciar os recursos correspondentes de uma instância do Agent Platform Workbench.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
    metadata = {
    }
  }
}

API Notebooks

Use o método instances.patch com o valor de metadados definido como uma string vazia e gce_setup.metadata no updateMask para remover o atributo correspondente.