Funcionalidade do agente convidado

Este documento apresenta uma visão geral da funcionalidade principal do agente convidado, um componente essencial do ambiente 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, consulte Ambiente convidado.

Como o agente convidado funciona

A partir da versão 20250901.00, o agente convidado usa uma arquitetura baseada em plug-ins. Esse design melhora a confiabilidade e a flexibilidade separando as funções do agente em componentes distintos.

A arquitetura do agente convidado consiste em alguns componentes principais:

  • Gerenciador de agentes convidados: o processo central na sua instância que inicia, para e monitora todos os plug-ins.
  • Plug-in principal: processa os serviços essenciais que sua instância precisa para ser executada no Google Cloud. Não é possível desativar a funcionalidade dele.
  • Plug-ins opcionais: são plug-ins que integram sua instância a outros serviços do Google Cloud , como o Cloud Monitoring. Você pode controlar quais desses plug-ins são executados na sua instância.
  • Plano de controle do agente: é um serviço Google Cloud gerenciado que é executado na infraestrutura de back-end do Google e gerencia o ciclo de vida de plug-ins opcionais, incluindo instalação e atualizações.

Para mais informações sobre a arquitetura do agente convidado, consulte Sobre o agente convidado.

Principal recurso

O plug-in principal é responsável pelos serviços fundamentais de que sua instância precisa para funcionar no Compute Engine. A seção a seguir detalha as funções fornecidas pelo plug-in principal. É possível personalizar muitos desses recursos usando o arquivo de configuração do agente convidado.

Configuração e otimizações iniciais de instâncias

O agente convidado realiza várias tarefas de configuração para preparar a instância para execução no Compute Engine. Como mostrado na tabela a seguir, algumas tarefas são executadas apenas na primeira inicialização, enquanto outras são executadas em todas as inicializações.

Tarefa Frequência
Gerar chaves de host SSH Na primeira inicialização
Criar a configuração boto para usar o Cloud Storage Na primeira inicialização
Otimizar para SSD local A cada inicialização
Ativar várias filas em todos os dispositivos virtionet A cada inicialização

É possível controlar essas tarefas de configuração definindo as opções InstanceSetup do arquivo de configuração do agente convidado. Por exemplo, é possível desativar a otimização do SSD local definindo optimize_local_ssd = false.

Coleta de telemetria do sistema

O agente convidado registra algumas informações básicas de telemetria do sistema na inicialização e depois a cada 24 horas. As informações registradas incluem o seguinte:

  • Versão e arquitetura do agente convidado
  • Nome e versão do sistema operacional
  • Versão e lançamento do kernel do sistema operacional

Para desativar a coleta de telemetria, defina a chave de metadados disable-guest-telemetry como true. Para definir metadados, consulte Definir e remover metadados personalizados.

Sincronização do relógio (somente no Linux)

Para garantir uma marcação de tempo precisa, o agente convidado usa o componente clock_skew_daemon para corrigir periodicamente o relógio na instância e corresponder ao servidor físico em que ele é executado. Esse processo evita um problema chamado distorção de relógio e gera uma mensagem system time has changed nos registros da instância, que confirma que a hora foi sincronizada.

Normalmente, o agente sincroniza o relógio após um evento de parada ou início ou após uma migração.

Para desativar o componente clock_skew_daemon, defina clock_skew_daemon = false no arquivo de configuração do agente convidado.

Execução de script de metadados

É possível usar scripts de inicialização e scripts de desligamento para realizar tarefas automatizadas sempre que a instância for iniciada ou interrompida.

O agente convidado ajuda a executar esses scripts da seguinte maneira:

  • Executa scripts em um shell.
  • Se você especificar vários scripts (por exemplo, se usar startup-script e startup-script-url), o agente vai executar os dois.
  • Quando vários scripts são fornecidos para o mesmo evento, o agente executa primeiro o script do URL.
  • Depois que um script termina, o agente registra o status de saída.

É possível configurar a execução de scripts de metadados modificando as opções MetadataScripts no arquivo de configuração do agente convidado.

Gerenciamento de contas de usuário e chaves SSH

O agente convidado usa um accounts_daemon para gerenciar contas de usuários locais e chaves SSH, que controlam o acesso à instância. O comportamento específico varia entre os sistemas operacionais Linux e Windows.

Para modificar as opções de gerenciamento de contas, configure as opções Accounts no arquivo de configuração do agente convidado.

Linux

O Login do SO é usado para gerenciar o acesso SSH às instâncias usando o IAM, sem precisar criar e gerenciar chaves SSH individuais. Para mais informações sobre o Login do SO, consulte Login do SO. Em instâncias do Linux, se o Login do SO não estiver ativado, o agente vai criar e gerenciar contas de usuário locais e as chaves SSH delas usando configurações de metadados.

Quando você adiciona ou remove chaves SSH dos metadados da instância ou do projeto, o agente convidado cria ou exclui uma conta de usuário local. O agente convidado também realiza as seguintes ações para gerenciar essas contas de usuário locais:

  • Mantém o arquivo authorized_keys de cada conta de usuário gerenciada da seguinte forma:
    • Quando você adiciona chaves SSH aos metadados, o agente cria um arquivo authorized_keys para a conta de usuário.
    • Quando você remove todas as chaves SSH de um usuário dos metadados, o agente exclui o arquivo authorized_keys dessa conta de usuário.
  • Gerencia privilégios de administrador usando o grupo google-sudoers do Linux. Todos os membros desse grupo recebem permissões de sudo na instância.
  • Adiciona todas as contas de usuário provisionadas ao grupo google-sudoers.
  • Adiciona contas de usuário a outros grupos do Linux especificados na opção groups do arquivo de configuração do agente convidado.

Windows

Em instâncias do Windows, o agente cria automaticamente contas de usuário local para qualquer conta de usuário SSH especificada nas chaves SSH de metadados no nível da instância ou do projeto. O agente convidado também é responsável por criar contas de usuário e definir ou redefinir senhas. Essas contas de usuário locais são necessárias para se conectar a instâncias do Windows usando SSH.

É possível impedir o provisionamento não intencional de usuários do AD desativando o gerenciador de contas na instância do controlador do AD. Para mais informações sobre como configurar o AD no Compute Engine, consulte implantar controladores de domínio.

Configuração do Login do SO (somente Linux)

O Login do SO é usado para gerenciar o acesso SSH às instâncias usando o IAM, sem precisar criar e gerenciar chaves SSH individuais. Para mais informações sobre o Login do SO, consulte a documentação do Login do SO.

Quando você ativa o Login do SO, o agente convidado é responsável por configurar a instância para usar o Login do SO.

O agente convidado configura o Login do SO concluindo as seguintes tarefas:

  • Adiciona um bloco de configuração do Google ao arquivo de configuração SSHD e reinicia SSHD.
  • Adiciona entradas de login do SO ao arquivo nsswitch.conf.
  • Adiciona entradas de Login do SO ao arquivo de configuração PAM para SSHD.

Se você desativar o Login do SO, as mudanças de configuração serão removidas. As opções na seção Accounts do arquivo de configuração SSHD não se aplicam aos usuários do Login do SO.

Gerenciamento de rede

O agente convidado configura automaticamente as interfaces de rede da instância na inicialização. Ele lê a configuração de rede do servidor de metadados para garantir que sua instância se conecte à rede corretamente e possa acessar outros serviços do Google Cloud.

Para controlar o comportamento de gerenciamento de rede do agente, configure as opções de NetworkInterfaces no arquivo de configuração do agente convidado. Por exemplo, é possível definir a opção manage_primary_nic = true para que o agente gerencie a placa de rede (NIC) principal, além das NICs secundárias.

Em cada inicialização, o agente convidado realiza as seguintes tarefas principais:

  • Ativa interfaces de rede: o agente detecta o gerenciador de rede ativo no SO e o usa para ativar todas as NICs de rede secundárias.
  • Configura rotas IP: o agente configura as rotas IP necessárias (somente IPv4) para recursos como encaminhamento de IP e intervalos de IP de alias da seguinte maneira:
    • Define rotas na interface Ethernet principal.
    • Configura as rotas do Google por padrão, com o ID do protocolo de roteamento 66. Esse ID é um namespace para endereços IP configurados do agente convidado. Esse ID pode ser mudado usando a opção ethernet_proto_id no arquivo de configuração do agente convidado.
  • Cria uma rota para o servidor de metadados: o agente garante que a NIC principal sempre possa se comunicar com o servidor de metadados para receber informações da instância.
  • Configuração da VLAN: se a instância estiver configurada para se conectar a uma rede local virtual (VLAN), o agente convidado vai processar a configuração automaticamente. Ele lê a configuração da VLAN no servidor de metadados e configura a interface de rede na instância para usar a tag VLAN correta. Isso garante que a instância se comunique na rede lógica pretendida. É importante lembrar que, se a VLAN estiver anexada à NIC principal, o agente convidado a configurará mesmo que manage_primary_nic esteja desativado.

Seleção do gerenciador de rede

No Linux, o agente convidado detecta automaticamente qual gerenciador de rede está disponível no sistema e o usa para configurar as interfaces de rede. O agente verifica os gerenciadores compatíveis por ordem de prioridade, de netplan a dhclient.

A tabela a seguir lista os gerenciadores de rede compatíveis, organizados pelo sistema operacional com que são mais comumente associados por padrão. Sua configuração de instância específica pode ser diferente, mas esta tabela reflete o gerenciador de rede padrão para os sistemas operacionais listados.

Gerenciador de rede Sistema operacional Localização da configuração Exemplo de caminho Observações
netplan
  • Debian 12 ou mais recente
  • Ubuntu 20.04 ou mais recente
 /run/netplan/ /run/netplan/20-google-guest-agent-eth0.yaml O agente também pode usar um local de substituição em /etc/systemd/network/
wicked
  • SLES
 /etc/sysconfig/network/ /etc/sysconfig/network/ifcfg-eth0 Os arquivos ifcfg atuais não são substituídos e são ignorados.
NetworkManager
  • CentOS
  • RHEL
  • Rocky Linux
 /etc/NetworkManager/system-connections/ /etc/NetworkManager/system-connections/google-guest-agent-eth0.nmconnection
systemd-networkd
  • Debian
 /usr/lib/systemd/network/ /usr/lib/systemd/network/20-eth0-google-guest-agent.network
dhclient
  • Debian 11 ou anterior
  • Ubuntu 18.04 ou anterior
 /run/ /run/dhclient.google-guest-agent.eth0.ipv4.pid Se nenhum dos outros gerenciadores de rede for detectado, o agente convidado usará dhclient por padrão.

Gerenciamento seguro de credenciais do servidor de metadados (MDS)

As VMs protegidas agora oferecem suporte à comunicação segura com o servidor de metadados usando o endpoint HTTPS https://metadata.google.internal/computeMetadata/v1. Essa melhoria oferece um canal mais seguro para acesso a metadados.

Para ativar essa comunicação segura, o agente convidado recupera e armazena as credenciais necessárias no disco da instância. Essas credenciais são salvas em um local padrão, o que as torna acessíveis a qualquer aplicativo cliente em execução na instância. Para analisar esses locais, consulte Onde os certificados são armazenados.

A configuração de certificados HTTPS MDS está desativada por padrão. Para que as VMs protegidas configurem automaticamente os certificados MDS HTTPS, defina a chave de metadados disable-https-mds-setup como false na instância ou no projeto. Para definir metadados, consulte Definir e remover metadados personalizados.

O gerenciamento de credenciais pelo agente convidado inclui:

  • Atualização inicial: o certificado raiz e as credenciais do cliente são atualizados sempre que o processo do agente convidado é iniciado.
  • Atualização automática: para aumentar a segurança, o agente convidado atualiza automaticamente as credenciais do cliente a cada 48 horas.
  • Período de sobreposição: o agente gera e salva novas credenciais enquanto as antigas permanecem válidas. O período de sobreposição garante que os clientes tenham tempo suficiente para fazer a transição para as novas credenciais antes que as antigas expirem. Esse período de sobreposição também permite que o agente tente novamente a aquisição de credenciais em caso de falha, garantindo que credenciais válidas estejam em vigor antes que as atuais se tornem inválidas.
  • Composição: o agente convidado garante que as credenciais do cliente consistam em uma chave privada EC (curva elíptica) concatenada com o certificado do cliente.
  • Unicidade: o agente convidado garante que as credenciais sejam exclusivas de uma instância e não possam ser usadas em outro lugar.

Para mais informações sobre o endpoint do servidor de metadados HTTPS, consulte Sobre o endpoint do servidor de metadados HTTPS.

Por padrão, o agente convidado grava certificados diretamente no disco. No entanto, é possível configurar o agente para integrar certificados aos armazenamentos de certificados integrados do sistema operacional. Para ativar essa integração, defina a chave de metadados enable-https-mds-native-cert-store como true. Para definir metadados, consulte Definir e remover metadados personalizados.

O comportamento do agente para adicionar certificados a repositórios de confiança do SO varia de acordo com o SO, da seguinte forma:

Linux

O agente convidado executa as seguintes etapas:

  1. Adiciona o certificado raiz do MDS ao armazenamento confiável do sistema. O caminho específico depende da distribuição do SO. Para analisar esses locais, consulte Armazenamento de certificados raiz no repositório de confiança do SO.
  2. Atualize o armazenamento de confiança local executando o comando apropriado para o SO, como update-ca-certificates ou update-ca-trust.

Windows

O agente adiciona as credenciais do cliente a Cert:\LocalMachine\My e o certificado raiz a Cert:\LocalMachine\Root.

Suporte a cluster de failover do Windows (somente Windows)

O agente convidado monitora o nó ativo no cluster de failover do Windows Server e coordena com o balanceador de carga interno Google Cloud para encaminhar todo o tráfego do cluster ao nó esperado.

É possível controlar esse comportamento usando os seguintes campos nos metadados da instância ou no arquivo instance_configs.cfg:

  • enable-wsfc: quando definido como true, o agente ignora todas as informações de encaminhamento de IP e começa a responder à porta de verificação de integridade. A configuração padrão é false.
  • wsfc-agent-port: especifica a porta em que o agente responde às verificações de integridade. A configuração padrão é 59998.
  • wsfc-addrs: uma lista de endereços IP separados por vírgulas. Essa configuração avançada permite ter IPs de encaminhamento normais e IPs de cluster na mesma instância. Quando você define isso, o agente só ignora a configuração automática para os IPs nessa lista. Por padrão, esse valor não é definido.

A seguir