Configurar o agente convidado

Neste documento, descrevemos como gerenciar o serviço do agente convidado e configurar os recursos dele editando o arquivo de configuração.

O agente convidado é um componente essencial do ambiente de convidado. O ambiente convidado contém scripts, daemons e binários que as instâncias precisam para serem executadas no Compute Engine. Para mais informações sobre o ambiente convidado, consulte Ambiente convidado. Embora o agente convidado funcione por padrão com as configurações padrão em imagens de SO fornecidas pelo Google, talvez você queira personalizar o comportamento dele. Para mais informações sobre as funções principais do agente convidado, consulte Funcionalidade do agente convidado.

Reiniciar o agente convidado

O agente convidado é executado como um daemon nos sistemas operacionais Linux e Windows. No Linux, o agente convidado é iniciado como um serviço systemd, e no Windows, ele é um serviço do sistema.

As etapas de reinicialização variam entre os sistemas operacionais Linux e Windows da seguinte maneira:

Linux

Para reiniciar no Linux, escolha uma das seguintes opções:

  • Para a versão 20250901.00 ou mais recente do agente convidado, execute o seguinte comando:

    ggactl_plugin coreplugin restart

  • Para versões anteriores do agente convidado, execute o seguinte comando:

    systemctl restart google-guest-agent

Windows

Para reiniciar no Windows, escolha uma das seguintes opções:

  • Para a versão 20250901.00 ou mais recente do agente convidado, execute o seguinte comando:

    ggactl_plugin coreplugin restart

  • Para versões anteriores do agente convidado, use os seguintes comandos do PowerShell:

    1. Para interromper o agente convidado: 

      Stop-Service GCEAgent

    2. Para iniciar o agente convidado: 

      Start-Service GCEAgent

    Como alternativa, para reiniciar o agente convidado: 

    Restart-Service GCEAgent

Para todas as versões do agente convidado, você também pode usar o Gerenciador de tarefas: encontre o serviço GCEGuestAgent e reinicie-o.

Atualizar o arquivo de configuração do agente convidado

É possível personalizar o comportamento do agente convidado editando o arquivo de configuração dele, instance_configs.cfg. Com ele, é possível ativar ou desativar recursos e definir valores padrão para operações.

Para editar o arquivo instance_configs.cfg em sistemas operacionais Linux e Windows, consulte as seções a seguir.

Linux

Para editar o arquivo de configuração em uma VM Linux, faça o seguinte:

  1. Crie ou edite o arquivo de configuração localizado em /etc/default/instance_configs.cfg e defina a opção necessária. Para ver uma lista de opções, consulte Opções de configuração.

    Por exemplo, para personalizar como novos usuários são criados e especificar quais tipos de chave de host SSH gerar, crie ou atualize o arquivo com o seguinte conteúdo:

    [Accounts]
useradd_cmd = useradd -m -G google-sudoers
[InstanceSetup]
host_key_types = ecdsa,ed25519

    Observação:as distribuições Linux podem fornecer as próprias configurações padrão em /etc/default/instance_configs.cfg.distro. O agente lê essas configurações primeiro, mas as que você define em /etc/default/instance_configs.cfg substituem os padrões de distribuição. Isso garante que suas configurações personalizadas não sejam perdidas durante as atualizações de pacotes.

  2. Depois de modificar o arquivo de configuração, reinicie o agente convidado para que as mudanças entrem em vigor.

Windows

Em VMs do Windows, o arquivo de configuração está localizado em C:\Program Files\Google\Compute Engine\instance_configs.cfg. Para detalhes sobre como configurar o agente no Windows, consulte Como ativar e desativar recursos de instância do Windows.

Opções de configuração

As tabelas a seguir listam as opções de configuração disponíveis para o arquivo instance_configs.cfg.

Contas

Use as opções na seção Accounts do arquivo instance_configs.cfg para controlar o gerenciamento de usuários e grupos pelo agente convidado.

Opção Descrição Sistema operacional Valor padrão
deprovision_remove Se definido como true, quando uma conta de usuário é removida, o diretório inicial do usuário também é excluído. Por padrão, apenas a conta de usuário é removida, e o diretório permanece intacto. Linux false
groups Uma lista de grupos separados por vírgulas para novos usuários. Linux Vazio
useradd_cmd Define o comando que o agente convidado executa ao criar um novo usuário. Por exemplo, para criar um diretório inicial de um usuário e adicioná-lo ao grupo google-sudoers, defina o valor como useradd -m -G google-sudoers. Linux Padrão do sistema
userdel_cmd Define o comando que o agente convidado executa ao excluir um usuário. Por exemplo, para remover o diretório e os arquivos pessoais do usuário, defina o valor como userdel -r. Linux Padrão do sistema
usermod_cmd Define o comando que o agente convidado executa ao modificar os grupos de um usuário. Linux Padrão do sistema
gpasswd_add_cmd Define o comando que o agente convidado executa ao adicionar um usuário a um grupo. Linux Padrão do sistema
gpasswd_remove_cmd Define o comando que o agente convidado executa ao remover um usuário de um grupo. Linux Padrão do sistema
groupadd_cmd Define o comando que o agente convidado executa ao criar um novo grupo. Linux Padrão do sistema

Core

Use as opções na seção Core do arquivo instance_configs.cfg para controlar as funcionalidades principais do agente convidado.

Opção Descrição Sistema operacional Valor padrão
cloud_logging_enabled Se definido como false, o agente convidado não enviará registros de atividades para o Cloud Logging. Linux e Windows true
log_level Define o nível de geração de registros do agente convidado. Essa configuração se aplica a todos os registros gerados pelo agente convidado, não apenas ao Cloud Logging. As configurações e os níveis são os seguintes:
  • 0 (FATAL): registra erros críticos que fazem o agente parar.
  • 1 (ERROR): registra erros que podem impedir a execução do agente.
  • 2 (WARN): registra condições potencialmente prejudiciais.
  • 3 (INFO): registra mensagens informativas sobre a atividade do agente. Essa é a configuração padrão.
  • 4 (DEBUG): registra informações de depuração. Essas informações podem ser detalhadas, mas é possível reduzir o nível de detalhamento usando a opção log_verbosity.
 Linux e Windows 3
log_verbosity Define o nível de detalhamento da geração de registros para registros DEBUG. Os valores aceitos vão de 0 a 4. Quanto maior o valor, mais detalhada será a resposta. Linux e Windows 0

Daemons

Use as opções na seção Daemons do arquivo instance_configs.cfg para ativar ou desativar daemons em segundo plano específicos gerenciados pelo agente convidado.

Opção Descrição Sistema operacional Valor padrão
accounts_daemon Se definido como false, o agente convidado desativa o gerenciamento de contas de usuário e chaves SSH. Linux true
clock_skew_daemon Se definido como false, o agente convidado desativa a sincronização de relógio. Linux true
network_daemon Se definido como false, o agente convidado desativa o gerenciamento de rede. Linux true

Configuração da instância

Use as opções na seção InstanceSetup do arquivo instance_configs.cfg para controlar várias tarefas realizadas pelo agente convidado durante a configuração inicial da instância.

Opção Descrição Sistema operacional Valor padrão
host_key_types Uma lista separada por vírgulas de tipos de chaves de host a serem gerados. Linux ecdsa,ed25519,rsa
optimize_local_ssd Se definido como false, o convidado não otimiza o SSD local na inicialização. Linux true
network_enabled Se definido como false, o agente convidado vai ignorar as funções de configuração da instância que exigem informações de metadados. Definir essa opção como "false" também desativa a geração de chaves de host e impede que o agente convidado configure o arquivo de configuração boto. Linux e Windows true
set_boto_config Se definido como false, o agente convidado não vai criar nem atualizar o arquivo de configuração boto. Os aplicativos que usam a biblioteca Boto e dependem da configuração padrão do agente convidado para acesso ao Cloud Storage podem não funcionar como esperado sem uma configuração manual do boto. Linux e Windows true
set_host_keys Se definido como false, o agente convidado vai pular a geração de chaves de host na primeira inicialização. Linux true
set_multiqueue Se definido como false, o agente convidado não tentará otimizar o desempenho da rede ativando recursos de várias filas para os drivers de rede. Quando true, o agente configura o sistema para usar várias filas de tráfego de rede, o que pode melhorar a capacidade e reduzir a latência. Linux true

Encaminhamento de IP

Use as opções na seção IpForwarding do arquivo instance_configs.cfg para configurar como o agente convidado gerencia o encaminhamento e o roteamento de IP.

Opção Descrição Sistema operacional Valor padrão
ethernet_proto_id A string de ID do protocolo para rotas adicionadas pelo daemon. Linux 66
ip_aliases Se definido como false, o agente convidado não vai configurar rotas de IP de alias. Linux true
target_instance_ips Se definido como false, o agente convidado não vai ativar o balanceamento de carga de endereço IP interno. Linux true

Execução de script de metadados

Use as opções na seção MetadataScripts do arquivo instance_configs.cfg para controlar a execução de scripts de metadados, como scripts de inicialização e desligamento.

Opção Descrição Sistema operacional Valor padrão
default_shell O shell padrão para executar scripts. Linux /bin/bash
run_dir O diretório base para execução de scripts de metadados. Linux /var/run/google-startup-scripts
startup Se definido como false, o agente convidado não vai executar scripts de inicialização dos metadados. Linux e Windows true
shutdown Se definido como false, o agente convidado não executará scripts de desligamento dos metadados. Linux e Windows true

Interfaces de rede

Use as opções na seção NetworkInterfaces do arquivo instance_configs.cfg para controlar como o agente convidado gerencia as interfaces de rede na VM.

Opção Descrição Sistema operacional Valor padrão
setup Se definido como false, o agente convidado vai pular a configuração da interface de rede. Linux true
ip_forwarding Se definido como false, o agente convidado vai pular o encaminhamento de IP. Linux true
manage_primary_nic Se definido como true, o agente convidado gerencia as NICs primária e secundária. Linux false
dhcp_command O caminho para um executável DHCP alternativo para ativar interfaces de rede. Linux Vazio
restore_debian12_netplan_config Se definido como true, o agente convidado vai recriar a configuração padrão do netplan do Debian 12, que está localizada em /etc/netplan/90-default.yaml. Linux (Debian 12) true

Login do SO

Use as opções na seção OSLogin do arquivo instance_configs.cfg para configurar a integração do agente convidado com o login do SO.

Opção Descrição Sistema operacional Valor padrão
cert_authentication Se definido como false, o agente convidado não configura as chaves TrustedUserCAKeys, AuthorizedPrincipalsCommand e AuthorizedPrincipalsCommandUser do sshd. Linux true

A seguir