Configure o agente convidado

Este documento descreve como gerir o serviço de agente convidado e configurar as respetivas funcionalidades editando o ficheiro de configuração.

O agente convidado é um componente essencial do ambiente convidado. O ambiente convidado contém scripts, daemons e ficheiros binários que as instâncias precisam de executar no Compute Engine. Para mais informações sobre o ambiente convidado, consulte o artigo Ambiente convidado. Embora o agente convidado funcione por predefinição com as definições predefinidas nas imagens do SO fornecidas pela Google, pode querer personalizar o respetivo comportamento. Para mais informações sobre as funções essenciais do agente convidado, consulte o artigo Funcionalidade do agente convidado.

Reinicie o agente convidado

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

Os passos de reinício variam entre os sistemas operativos Linux e Windows da seguinte forma:

Linux

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

  • Para a versão 20250901.00 ou posterior 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 posterior 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 parar o agente convidado: 

      Stop-Service GCEAgent

    2. Para iniciar o agente convidado: 

      Start-Service GCEAgent

    Em alternativa, para reiniciar o agente convidado: 

    Restart-Service GCEAgent

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

Atualize o ficheiro de configuração do agente convidado

Pode personalizar o comportamento do agente convidado editando o respetivo ficheiro de configuração, instance_configs.cfg. Este ficheiro permite-lhe ativar ou desativar funcionalidades e definir valores predefinidos para operações.

Para editar o ficheiro instance_configs.cfg nos sistemas operativos Linux e Windows, reveja as secções seguintes.

Linux

Para editar o ficheiro de configuração numa VM do Linux, faça o seguinte:

  1. Crie ou edite o ficheiro 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 a forma como os novos utilizadores são criados e especificar que tipos de chaves de anfitrião SSH gerar, crie ou atualize o ficheiro com o seguinte conteúdo:

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

    Nota: as distribuições Linux podem fornecer as suas próprias definições predefinidas em /etc/default/instance_configs.cfg.distro. O agente lê primeiro estas definições, mas quaisquer definições que defina em /etc/default/instance_configs.cfg substituem as predefinições de distribuição. Isto garante que as suas configurações personalizadas não são perdidas durante as atualizações de pacotes.

  2. Depois de modificar o ficheiro de configuração, reinicie o agente convidado para que as alterações entrem em vigor.

Windows

Nas VMs do Windows, o ficheiro de configuração encontra-se em C:\Program Files\Google\Compute Engine\instance_configs.cfg. Para ver detalhes sobre a configuração do agente no Windows, consulte o artigo Ativar e desativar funcionalidades da instância do Windows.

Opções de configuração

As tabelas seguintes indicam as opções de configuração disponíveis para o ficheiro instance_configs.cfg.

Contas

Use as opções na secção Accounts do ficheiro instance_configs.cfg para controlar a gestão de utilizadores e grupos pelo agente convidado.

Opção Descrição Sistema operativo Valor predefinido
deprovision_remove Se estiver definida como true, quando uma conta de utilizador é removida, o diretório base do utilizador também é eliminado. Por predefinição, apenas a conta de utilizador é removida, e o diretório permanece intacto. Linux false
groups Uma lista de grupos separada por vírgulas para novos utilizadores. Linux Vazio
useradd_cmd Define o comando que o agente convidado executa quando cria um novo utilizador. Por exemplo, para criar o diretório base de um utilizador e adicioná-lo ao grupo google-sudoers, defina o valor como useradd -m -G google-sudoers. Linux Predefinição do sistema
userdel_cmd Define o comando que o agente convidado executa quando elimina um utilizador. Por exemplo, para remover o diretório pessoal e os ficheiros do utilizador, defina o valor como userdel -r. Linux Predefinição do sistema
usermod_cmd Define o comando que o agente convidado executa quando modifica os grupos de um utilizador. Linux Predefinição do sistema
gpasswd_add_cmd Define o comando que o agente convidado executa quando adiciona um utilizador a um grupo. Linux Predefinição do sistema
gpasswd_remove_cmd Define o comando que o agente convidado executa quando remove um utilizador de um grupo. Linux Predefinição do sistema
groupadd_cmd Define o comando que o agente convidado executa quando cria um novo grupo. Linux Predefinição do sistema

Principal

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

Opção Descrição Sistema operativo Valor predefinido
cloud_logging_enabled Se estiver definido como false, o agente convidado não envia registos de atividade para o Cloud Logging. Linux e Windows true
log_level Define o nível de registo para os registos do agente convidado. Esta definição aplica-se a todos os registos gerados pelo agente convidado e não apenas ao Cloud Logging. As definições e os níveis são os seguintes:
  • 0 (FATAL): regista erros críticos que fazem com que o agente pare.
  • 1 (ERROR): regista erros que podem impedir a execução do agente.
  • 2 (WARN): regista condições potencialmente prejudiciais.
  • 3 (INFO): regista mensagens informativas sobre a atividade do agente. Esta é a predefinição.
  • 4 (DEBUG): regista informações de depuração. Estas informações podem ser detalhadas, mas pode reduzir o nível de detalhe através da opção log_verbosity.
 Linux e Windows 3
log_verbosity Define o nível de detalhe do registo para os registos DEBUG. Os valores aceitáveis variam entre 0 e 4. Quanto mais elevado for o valor, mais detalhada é a resposta. Linux e Windows 0

Daemons

Use as opções na secção Daemons do ficheiro instance_configs.cfg para ativar ou desativar daemons de fundo específicos geridos pelo agente convidado.

Opção Descrição Sistema operativo Valor predefinido
accounts_daemon Se estiver definido como false, o agente convidado desativa a gestão de contas de utilizador e chaves SSH. Linux true
clock_skew_daemon Se estiver definido como false, o agente convidado desativa a sincronização do relógio. Linux true
network_daemon Se estiver definido como false, o agente convidado desativa a gestão de rede. Linux true

Configuração da instância

Use as opções na secção InstanceSetup do ficheiro 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 operativo Valor predefinido
host_key_types Uma lista separada por vírgulas de tipos de chaves de anfitrião a gerar. Linux ecdsa,ed25519,rsa
optimize_local_ssd Se estiver definido como false, o convidado não otimiza o SSD local no arranque. Linux true
network_enabled Se estiver definido como false, o agente convidado ignora as funções de configuração da instância que requerem informações de metadados. Se definir esta opção como false, também desativa a geração de chaves de anfitrião e impede que o agente convidado configure o ficheiro de configuração boto. Linux e Windows true
set_boto_config Se estiver definido como false, o agente convidado não cria nem atualiza o ficheiro de configuração boto. As aplicações que usam a biblioteca Boto e dependem da configuração do agente convidado predefinida para o acesso ao Cloud Storage podem não funcionar como esperado sem a configuração manual do boto. Linux e Windows true
set_host_keys Se estiver definido como false, o agente convidado ignora a geração de chaves de anfitrião no primeiro arranque. Linux true
set_multiqueue Se estiver definido como false, o agente convidado não tenta otimizar o desempenho da rede ativando funcionalidades de várias filas para os controladores de rede. Quando true, o agente configura o sistema para usar várias filas para o tráfego de rede, o que pode melhorar o débito e reduzir a latência. Linux true

Encaminhamento de IP

Use as opções na secção IpForwarding do ficheiro instance_configs.cfg para configurar a forma como o agente convidado gere o encaminhamento e o reencaminhamento de IP.

Opção Descrição Sistema operativo Valor predefinido
ethernet_proto_id A string do ID do protocolo para rotas adicionadas pelo daemon. Linux 66
ip_aliases Se estiver definido como false, o agente convidado não configura caminhos de IP de alias. Linux true
target_instance_ips Se estiver definido como false, o agente convidado não ativa o equilíbrio de carga do endereço IP interno. Linux true

Execução de scripts de metadados

Use as opções na secção MetadataScripts do ficheiro para controlar a execução de scripts de metadados, como scripts de arranque e encerramento.instance_configs.cfg

Opção Descrição Sistema operativo Valor predefinido
default_shell A shell predefinida para executar scripts. Linux /bin/bash
run_dir O diretório base para a execução de scripts de metadados. Linux /var/run/google-startup-scripts
startup Se estiver definido como false, o agente convidado não executa scripts de inicialização a partir de metadados. Linux e Windows true
shutdown Se estiver definido como false, o agente convidado não executa scripts de encerramento a partir de metadados. Linux e Windows true

Interfaces de rede

Use as opções na secção NetworkInterfaces do ficheiro para controlar a forma como o agente convidado gere as interfaces de rede na VM.instance_configs.cfg

Opção Descrição Sistema operativo Valor predefinido
setup Se estiver definido como false, o agente convidado ignora a configuração da interface de rede. Linux true
ip_forwarding Se estiver definido como false, o agente convidado ignora o encaminhamento de IP. Linux true
manage_primary_nic Se estiver definido como true, o agente convidado gere as NICs principal 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 estiver definido como true, o agente convidado recria a configuração do netplan predefinida do Debian 12 que se encontra em /etc/netplan/90-default.yaml. Linux (Debian 12) true

Início de sessão do SO

Use as opções na secção OSLogin do ficheiro instance_configs.cfg para configurar a integração do agente convidado com o Início de sessão do SO.

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

O que se segue?