Troubleshoot VM Extension Manager policies for the Ops Agent

To diagnose problems with VM Extension Manager policies that manage the Ops Agent, use the troubleshooting techniques described in this document. For information about troubleshooting the Ops Agent, see Troubleshoot the Ops Agent.

gcloud compute zone-vm-extension-policies commands fail

When a gcloud compute zone-vm-extension-policies command fails, the response includes troubleshooting suggestions. Correct any errors in the command flags or arguments suggested by the error message.

If the output of the command mentions insufficient IAM permissions, then review the necessary roles and permissions described in Grant the roles required to use VM Extension Manager.

The extension policy is created, but the Ops Agent status is "not detected"

You successfully created an extension policy, but the Ops Agent shows a "not detected" status on the VM.

The Ops Agent might show as "not detected" if either of the following occurs:

• The extension policy fails to install the Ops Agent.
• An installed Ops Agent encounters an error condition that prevents it from running.

The following sections describe how to diagnose these cases.

Verify that the Ops Agent was installed by the policy

VM Extension Manager policies use the Compute Engine guest agent to manage the Ops Agent as a VM extension.

To determine if the Ops Agent was installed by the extension policy, use one of the following to look for log entries from the guest agent:

Logs Explorer

1. In the Google Cloud console, go to the segment Logs Explorer page:

   Go to Logs Explorer

   If you use the search bar to find this page, then select the result whose subheading is Logging.

2. Enter the following query and click Run query:

   log_id("GCEGuestAgentManager")

Linux

Run the following command on the Compute Engine VM:

journalctl -u google-guest-agent-manager

Windows

Run the following command on the Compute Engine VM:

Get-Eventlog -Source google_guest_agent_manager -LogName Application

If you see logs containing a string like Failed to install plugin "ops-agent-plugin" ..., or the query returns no logs, then the extension policy failed to install the Ops Agent. For next steps, see Extension policy fails to install the Ops Agent.

If you see logs containing a string like Successfully installed plugin "ops-agent_nnnnnnnn", then the extension policy successfully installed the Ops Agent. For next steps, see Installed Ops Agent is "not detected".

Extension policy fails to install the Ops Agent

An extension policy might be ineffective if one of the following is true:

• The guest agent is not installed on the VM. To diagnose and fix this condition, do the following:

  1. Verify that the VM is using one of the operating systems supported for the Compute Engine guest environment.

  2. View the packages installed on the VM to verify that google-guest-agent is included.

  3. If the google-guest-agent is not installed, then install the guest agent.

• The guest agent is installed but outdated. To diagnose and fix this condition, do the following:

  1. Validate the guest environment to determine the version of the google-guest-agent package. VM Extension Manager requires version 20241209.01 or newer.

  2. If the version of the google-guest-agent is older than 20241209.01, then update the guest environment.

• The VM's operating system is not supported by VM Extension Manager. For more information, see Review supported operating systems.

Installed Ops Agent has status "not detected"

The Ops Agent can have a status of "not detected" if one of the following is true:

• There are observability agents installed on the VM already. Existing agents can cause conflicts and must be uninstalled. For more information, see Uninstall any observability agents.

  After uninstalling any previously installed agents, you can restart the Ops Agent.

• The Ops Agent has insufficient permissions to send data to Cloud Logging and Cloud Monitoring. For more information, see Common reasons for telemetry-transmission failures.

Verify that the Ops Agent configuration is valid

You provided a custom configuration to the Ops Agent by creating or updating an extension policy, but the agent status is "not detected". The problem might be an error in your custom configuration. Use the guest agent debug logs to look for configuration errors.

Enable guest agent debug logging

For information about enabling debug logging for the guest agent, see View debug logs for the guest agent.

Examine debug logs

Logs Explorer

1. In the Google Cloud console, go to the segment Logs Explorer page:

   Go to Logs Explorer

   If you use the search bar to find this page, then select the result whose subheading is Logging.

2. Enter the following query and click Run query:

   severity>=DEBUG log_id("GCEGuestAgentManager") "The agent config file is not valid"

Linux

Run the following command on the Linux Compute Engine VM:

journalctl -u google-guest-agent-manager | grep "The agent config file is not valid"

Windows

Run the following command on the Windows Compute Engine VM:

Get-Eventlog -Source google_guest_agent_manager -LogName Application | Where-Object {$_.Message -like "*The agent config file is not valid*"}

If you see logs containing the string The agent config file is not valid, then the custom configuration for the Ops Agent you provided when creating or updating the extension policy is invalid.

To fix this problem, do the following:

• Correct the configuration by referring to Configure the Ops Agent. For information about the structure of an Ops Agent configuration file.

• Update the extension policy with the corrected configuration.

Linux systemctl status and Windows Get-Service commands don't work with the Ops Agent

You run a command like sudo systemctl status google-cloud-ops-agent"*" but it returns no information.

When the Ops Agent is installed and managed by VM Extension Manager, the Ops Agent isn't managed by the system-management service of the operating system, that is, systemd on Linux or the Windows Service Manager on Windows.

To find the status information for an Ops Agent managed by VM Extension Manager, see the following:

• Agent health checks
• Agent self logs.

Linux systemctl restart and Windows Restart-Service commands don't work with the Ops Agent

You run a command like sudo systemctl restart google-cloud-ops-agent but the Ops Agent isn't restarted.

When the Ops Agent is installed and managed by VM Extension Manager, the Ops Agent isn't managed by the system-management service of the operating system, that is, systemd on Linux or the Windows Service Manager on Windows. Therefore, you can't stop or start the Ops Agent manually, and commands like the following don't work with the Ops Agent:

• Linux: sudo systemctl [stop|start|restart]
• Windows: Stop-Service, Start-Service, Restart-Service

To stop or restart an Ops Agent managed by VM Extension Manager, you must uninstall the agent by deleting the extension policy. For more information about stopping or restarting the Ops Agent, see Restart an Ops Agent installed by an extension policy.

Additional troubleshooting information

For more information about troubleshooting the creation and use of VM Extension Manager policies, see Troubleshoot VM extensions.

For more information about troubleshooting the Ops Agent, see Troubleshoot the Ops Agent.