Set up the agent for MySQL workloads

This document shows how to install Agent for Compute Workloads on a Compute Engine instance, and configure the agent to connect with a MySQL workload running on that compute instance.

Before you begin

Before you install and configure Agent for Compute Workloads, you need to make sure that the following prerequisites are met:

You've deployed a MySQL workload on a compute instance.
You've granted the required IAM roles to the service account attached to compute instance.
You've enabled access to Cloud APIs.

Required IAM roles

Agent for Compute Workloads uses the service account attached to the compute instance for authentication and to access Google Cloud resources.

To improve security, we recommend that you use a single-purpose service account rather than using the Compute Engine default service account.

To ensure that the service account has the necessary permissions to let Agent for Compute Workloads authenticate with Google Cloud and access Google Cloud resources, ask your administrator to grant the service account the following IAM roles on your project:

Compute Viewer (roles/compute.viewer): to collect metrics from the compute instance.
Workload Manager Insights Writer (roles/workloadmanager.insightWriter): to write data to Workload Manager data warehouse.
(Recommended) Logs Writer (roles/logging.logWriter): to send agent logs to Cloud Logging.
(Optional) Secret Manager Secret Accessor (roles/secretmanager.secretAccessor): if you are using Secret Manager to store the password to connect with the MySQL instance.

For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give the service account the required permissions through custom roles or other predefined roles.

Enable access to Cloud APIs

Compute Engine recommends configuring your instances to allow all access scopes to all Cloud APIs and using only the IAM permissions of the instance service account to control access to Google Cloud resources. For more information, see Create a VM that uses a user-managed service account.

If you limit access to the Cloud APIs, then the Agent for Compute Workloads requires at minimum the following Cloud APIs access scopes on the host compute instance:

https://www.googleapis.com/auth/cloud-platform

For more information, see Scopes best practice.

If you're running MySQL applications on a compute instance that doesn't have an external IP address, then you need to enable Private Google Access on the instance's subnet so that Agent for Compute Workloads can access the Google APIs and services. For information about how to enable Private Google Access, see Configure Private Google Access.

Install and configure the agent

To install the Agent for Compute Workloads on your compute instance, and configure it to connect with a MySQL instance, complete the following steps:

RHEL

On Red Hat Enterprise Linux (RHEL), you install Agent for Compute Workloads by using the yum package management command. This command completes the following tasks:

Downloads the latest version of the agent.
Creates a systemd service for the agent, named google-cloud-workload-agent.
Enables and starts the google-cloud-workload-agent service.

To install and configure Agent for Compute Workloads on a RHEL based compute instance, complete the following steps:

Establish an SSH connection with your compute instance.

In your terminal, install the agent:

sudo tee /etc/yum.repos.d/google-cloud-workload-agent.repo << EOM
[google-cloud-workload-agent]
name=Google Cloud Agent for Compute Workloads
baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-workload-agent-$basearch
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM
sudo yum install google-cloud-workload-agent

Open the agent's configuration file:

/etc/google-cloud-workload-agent/configuration.json

Specify values for all mandatory parameters, as described in Configuration parameters.
Save the configuration file
Restart the agent for the changes to take effect.

SLES

On SUSE Linux Enterprise Server (SLES), you install Agent for Compute Workloads by using the zypper package management command. This command completes the following tasks:

Downloads the latest version of the agent.
Creates a systemd service for the agent, named google-cloud-workload-agent.
Enables and starts the google-cloud-workload-agent service.

To install and configure Agent for Compute Workloads on a SLES based compute instance, complete the following steps:

Establish an SSH connection with your compute instance.

In your terminal, install the agent:

sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-workload-agent-$basearch
google-cloud-workload-agent
sudo zypper install google-cloud-workload-agent

Open the agent's configuration file:

/etc/google-cloud-workload-agent/configuration.json

Specify values for all mandatory parameters, as described in Configuration parameters.
Save the configuration file
Restart the agent for the changes to take effect.

Debian

On Debian, you install Agent for Compute Workloads by using the apt package management command. This command completes the following tasks:

Downloads the latest version of the agent.
Creates a systemd service for the agent, named google-cloud-workload-agent.
Enables and starts the google-cloud-workload-agent service.

To install and configure Agent for Compute Workloads on a Debian based compute instance, complete the following steps:

Establish an SSH connection with your compute instance.

In your terminal, install the agent:

echo 'deb https://packages.cloud.google.com/apt google-cloud-workload-agent-x86-64-apt main' | sudo tee -a /etc/apt/sources.list.d/google-cloud-workload-agent.list
sudo apt-get update
sudo apt-get install google-cloud-workload-agent

Open the agent's configuration file:

/etc/google-cloud-workload-agent/configuration.json

Specify values for all mandatory parameters, as described in Configuration parameters.
Save the configuration file
Restart the agent for the changes to take effect.

Windows

On Windows, you install Agent for Compute Workloads by using the googet package management command. This command completes the following tasks:

Downloads the latest version of the agent.
Creates a Windows service named google-cloud-workload-agent.
Creates a scheduled task that runs every minute to check if the service is running and if necessary, restart the service.

To install and configure Agent for Compute Workloads on a Windows based compute instance, complete the following steps:

Establish a connection with your compute instance by using RDP.

For information about how to do this, see Connect to Windows VMs using RDP.

As an administrator, run the following commands from PowerShell:

googet addrepo google-cloud-workload-agent  https://packages.cloud.google.com/yuck/repos/google-cloud-workload-agent-windows-x86_64
googet install google-cloud-workload-agent

Open the agent's configuration file:

%ProgramFiles%\Google\google-cloud-workload-agent\conf\configuration.json

Specify values for all mandatory parameters, as described in Configuration parameters.
Save the configuration file
Restart the agent for the changes to take effect.

Verify agent installation

To verify that the agent is running as expected, complete the following steps:

RHEL

Establish an SSH connection with your compute instance.

Check the status of the agent package:

systemctl status google-cloud-workload-agent

If the agent package is running as expected, then the output contains active (running). For example:

google-cloud-workload-agent.service - Google Cloud Agent for Compute Workloads
Loaded: loaded (/usr/lib/systemd/system/google-cloud-workload-agent.service; enabled; vendor preset: disabled)
Active: active (running) since Sun 2025-07-30 18:59:12 UTC; 10s ago
Main PID: 14412 (google_cloud_sq)
  Tasks: 7
Memory: 12.9M (max: 1.0G limit: 1.0G available: 1011.0M)
CGroup: /system.slice/google-cloud-workload-agent.service
        └─ 14412 /usr/bin/google_cloud_sql_server_agent --action=run

SLES

Establish an SSH connection with your compute instance.

Check the status of the agent package:

systemctl status google-cloud-workload-agent

If the agent package is running as expected, then the output contains active (running). For example:

google-cloud-workload-agent.service - Google Cloud Agent for Compute Workloads
Loaded: loaded (/usr/lib/systemd/system/google-cloud-workload-agent.service; enabled; vendor preset: disabled)
Active: active (running) since Sun 2025-07-30 18:59:12 UTC; 10s ago
Main PID: 14412 (google_cloud_sq)
  Tasks: 7
Memory: 12.9M (max: 1.0G limit: 1.0G available: 1011.0M)
CGroup: /system.slice/google-cloud-workload-agent.service
        └─ 14412 /usr/bin/google_cloud_sql_server_agent --action=run

Debian

Establish an SSH connection with your compute instance.

Check the status of the agent package:

systemctl status google-cloud-workload-agent

If the agent package is running as expected, then the output contains active (running). For example:

google-cloud-workload-agent.service - Google Cloud Agent for Compute Workloads
Loaded: loaded (/usr/lib/systemd/system/google-cloud-workload-agent.service; enabled; vendor preset: disabled)
Active: active (running) since Sun 2025-07-30 18:59:12 UTC; 10s ago
Main PID: 14412 (google_cloud_sq)
  Tasks: 7
Memory: 12.9M (max: 1.0G limit: 1.0G available: 1011.0M)
CGroup: /system.slice/google-cloud-workload-agent.service
        └─ 14412 /usr/bin/google_cloud_sql_server_agent --action=run

Windows

Establish a connection with your compute instance by using RDP.

For information about how to do this, see Connect to Windows VMs using RDP.
As an administrator, run the following command from PowerShell:
```
$(Get-Service -Name 'google-cloud-workload-agent' -ErrorAction Ignore).Status
```
If the agent is running as expected, then you see the status as Running.

Example configuration file

The following is an example configuration that lets Agent for Compute Workloads connect with a MySQL instance. For authentication, a Secret Manager secret is used, which is stored in the same Google Cloud project where the MySQL instance is running.

{
  "log_level": "INFO",
  "common_discovery": {
    "collection_frequency": "10800s"
  },
  "mysql_configuration": {
    "enabled": true,
    "connection_parameters": {
      "username": "db_user_name",
      "secret": {
        "secret_name": "db_pwd_secret_name",
        "project_id": ""
      },
      "host": "localhost",
      "port": 1433
    }
  }
}

Configuration parameters

The following table describes the configuration parameters of Agent for Compute Workloads that support evaluations for MySQL workloads:

Parameters
`log_level`	`String` To set the logging level of the agent, set the required value. The available log levels are as follows: `DEBUG` `INFO` `WARNING` `ERROR` The default log level is `INFO`. Don't change the logging level unless you are directed by Cloud Customer Care.
`log_to_cloud`	`Boolean` To redirect the agent's logs to Cloud Logging, specify `true`. The default value is `true`.
`agent_properties.log_usage_metrics`	`Boolean` To enable logging of the agent's health metrics, set the value to `true`. The default value is `false`.
`common_discovery.collection_frequency`	`Duration` Specify the frequency, in seconds, at which the agent's workload discovery service runs. The default value is `10800s`. Make sure that this parameter's value ends with a lowercase `s`.
`mysql_configuration.enabled`	`Boolean` To let the agent collect metrics from the MySQL instance, set the value to `true`. The default value is `false`. Important: For the other MySQL specific agent parameters to work, you must set `mysql_configuration.enabled` to `true`.
`mysql_configuration.connection_parameters.username`	`String` Specify the user account that the agent uses to query the MySQL instance.
`mysql_configuration.connection_parameters.password`	`String` Specify the plain text password for the user account that the agent uses to query the MySQL instance. Instead of specifying a plain text password, we recommend that you use the `secret.name` and `secret.project_id` parameters. For authentication, the agent uses the following order of preference: if specified, the `secret` set of parameters are preferred over the `password` parameter. We recommend that you set only one authentication option in the agent's configuration file.
`mysql_configuration.connection_parameters.secret.secret_name`	`String` Optional. To securely provide the password for the user account that the agent uses to query the MySQL instance, specify the name of the Secret Manager secret that contains the password. For authentication, the agent uses the following order of preference: if specified, the `secret` set of parameters are preferred over the `password` parameter. We recommend that you set only one authentication option in the agent's configuration file.
`mysql_configuration.connection_parameters.secret.project_id`	`String` Optional. To use the `secret.secret_name` parameter for authenticating the specified user account, specify the project ID of the Google Cloud project where the Secret Manager secret is stored. If the secret and the workload are in the same Google Cloud project, then set the value of this parameter to an empty string (`""`).
`mysql_configuration.connection_parameters.host`	`String` Specify the MySQL hostname.
`mysql_configuration.connection_parameters.port`	`Int` Specify the port at which your MySQL instance accepts queries.

What's next

Create and run an evaluation
Learn about the Workload Manager best practices for MySQL

Set up the agent for MySQL workloads Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required IAM roles

Enable access to Cloud APIs

Install and configure the agent

RHEL

SLES

Debian

Windows

Verify agent installation

RHEL

SLES

Debian

Windows

Example configuration file

Configuration parameters

What's next

Set up the agent for MySQL workloads