Configurare Agent for Compute Workloads

Workload Manager per Microsoft SQL Server utilizza l'agente per i carichi di lavoro di calcolo di Google Cloudper rilevare e raccogliere i metadati per la valutazione delle configurazioni di SQL Server.

Questo documento mostra come installare, configurare e verificare Agent for Compute Workloads nelle istanze Compute Engine che eseguono SQL Server.

Prerequisiti per l'installazione dell'agente

Prima di installare l'agente per i carichi di lavoro di Compute, devi assicurarti che siano soddisfatti i seguenti prerequisiti e che sia stata creata una valutazione del carico di lavoro di SQL Server.

Concedi i ruoli IAM all'account di servizio

L'agente diGoogle Cloudper i carichi di lavoro di Compute utilizza il account di servizio Identity and Access Management (IAM) collegato alla VM per l'autenticazione con Google Cloud e per l'autorizzazione per accedere alle risorse Google Cloud . Per la raccolta delle metriche di convalida di Workload Manager, utilizza un nuovo account di servizio che includa i seguenti ruoli IAM:

Per aggiungere un ruolo obbligatorio all'account di servizio:

  1. Nella console Google Cloud, vai alla pagina IAM.

    Vai a IAM

  2. Selezionare il tuo progetto Google Cloud.

  3. Identifica l'account di servizio a cui vuoi aggiungere un ruolo.

    • Se l'account di servizio non è già presente nell'elenco delle entità, non sono stati assegnati ruoli. Fai clic su Aggiungi e inserisci l'indirizzo email dell'account di servizio.
    • Se l'account di servizio è già presente nell'elenco dei principali, significa che ha già dei ruoli. Fai clic sul pulsante Modifica per l'account di servizio che vuoi modificare.

  4. Seleziona il ruolo richiesto dall'elenco dei ruoli disponibili:

    • Compute Engine > Visualizzatore Compute
    • Secret Manager > Secret Manager Secret Accessor

  5. Fai clic su Aggiungi o Salva per applicare i ruoli all'account di servizio.

Attivare l'accesso alle Google Cloud API

Compute Engine consiglia di configurare le istanze VM in modo da consentire tutti gli ambiti di accesso a tutte le API Cloud e di utilizzare solo le autorizzazioni IAM dell'account di servizio dell'istanza per controllare l'accesso alle risorse. Google Cloud Per ulteriori informazioni, consulta Creare una VM che utilizza un account di servizio gestito dall'utente.

Se limiti l'accesso alle API Cloud, Agent for Compute Workloads richiede i seguenti ambiti di accesso alle API Cloud minimi sull'istanza VM host:

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

Per ulteriori informazioni, consulta le best practice per gli ambiti.

Se esegui applicazioni SQL Server su un'istanza VM che non ha un indirizzo IP esterno, devi attivare l'accesso privato Google sulla subnet della VM in modo che l'agente per i carichi di lavoro di Compute possa accedere alle API e ai servizi Google. Per scoprire come abilitare l'accesso privato Google in una subnet, consulta Configurare l'accesso privato Google.

Autorizzazioni richieste su SQL Server

Utilizza il seguente script per assegnare le autorizzazioni richieste all'account utente configurato nell'agente.

    USE [master]
    GO 

    GRANT VIEW SERVER STATE TO [user_name]
    GRANT VIEW ANY DEFINITION TO [user_name] 

    -- Adds db_datareader role to the user
    EXEC sp_MSForEachDB
    '
    USE ?
    IF NOT EXISTS(SELECT * FROM sys.database_principals WHERE name = ''user_name'')
    BEGIN
      CREATE USER [user_name] FOR LOGIN [user_name]
    END
    EXEC sp_addrolemember ''db_datareader'', ''user_name''
    '

Installa l'agente

Per installare la versione più recente di Agent for Compute Workloads, completa i seguenti passaggi:

Windows Linux

Su Windows, installa Agent for Compute Workloads utilizzando il comando di gestione del pacchetto GooGet, googet. Il comando di gestione dei pacchetti completa le seguenti attività:

  • Scarica la versione più recente di Agent for Compute Workloads.
  • Crea un servizio Windows denominato google-cloud-workload-agent e un'attività pianificata che viene eseguita ogni minuto per verificare se il servizio è ancora in esecuzione e, se necessario, riavviarlo.

Per installare l'agente su una VM:

  1. Connettiti all'istanza VM Windows utilizzando RDP.
  2. In qualità di amministratore, esegui i seguenti comandi da 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
  3. Esamina il file di configurazione in %ProgramFiles%\Google\google-cloud-workload-agent\conf e aggiornalo utilizzando i dettagli riportati in Proprietà di configurazione.
  4. Riavvia l'agente per applicare la modifica.

Su Linux, installa Agent for Compute Workloads utilizzando i comandi di gestione dei pacchetti del sistema operativo standard:

  • Su RHEL, utilizza il comando yum
  • Su SLES, utilizza il comando zypper
  • Su Debian, utilizza il comando apt

Il comando di gestione dei pacchetti completa le seguenti attività:

  • Scarica la versione più recente di Agent for Compute Workloads.
  • Crea l'agente come servizio systemd Linux denominato google-cloud-workload-agent.
  • Attiva e avvia il servizio google-cloud-workload-agent.

Per installare l'agente su una VM:

  1. Stabilisci una connessione SSH alla VM host.
  2. Nel terminale, installa l'agente eseguendo il comando specifico per il tuo sistema operativo:
RHEL SLES Debian 
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
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
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
  1. Esamina il file di configurazione in \etc\google-cloud-workload-agent e aggiornalo utilizzando i dettagli in Proprietà di configurazione.
  2. Riavvia l'agente per applicare la modifica.

Proprietà di configurazione

La seguente tabella descrive le proprietà del file di configurazione dell'agente.

Proprietà
log_level

String

Per impostare il livello di logging dell'agente, aggiungi i livelli di log. I livelli di log disponibili sono i seguenti:
  • DEBUG
  • INFO
  • WARNING
  • ERROR
Il valore predefinito è INFO. Non modificare il livello di registrazione a meno che non ti venga indicato dall'assistenza clienti Google Cloud.
log_to_cloud

Boolean

Per reindirizzare i log dell'agente a Cloud Logging, specifica true. Il valore predefinito è true.
common_discovery.collection_frequency

Duration

Frequenza di raccolta per il servizio di rilevamento comune, in secondi.
Il valore predefinito è 10800s.
agent_properties.log_usage_metrics

Boolean

Per attivare il logging delle metriche relative allo stato dell'agente, imposta il valore su true. Il valore predefinito è false.
sqlserver_configuration.enabled

Boolean

Per attivare le raccolte di metriche di SQL Server all'interno dell'agente, imposta il valore su true. Il valore predefinito è false.
sqlserver_configuration.collection_configuration.collect_guest_os_metrics

Boolean

Per attivare la raccolta delle metriche del sistema operativo, imposta il valore su true. Il valore predefinito è true.
Non impostare sqlserver_configuration.collection_configuration.collect_guest_os_metrics su false a meno che non ti venga indicato dall'assistenza clienti Google Cloud.
sqlserver_configuration.collection_configuration.collect_sql_metrics

Boolean

Per abilitare la raccolta delle metriche di SQL Server, specifica true. Il valore predefinito è true.
Non impostare sqlserver_configuration.collection_configuration.collect_sql_metrics su false a meno che non ti venga indicato dall'assistenza clienti Google Cloud.
sqlserver_configuration.collection_configuration.collection_frequency

Duration

Frequenza di raccolta delle metriche di Agent for Compute Workloads, in secondi. Il valore predefinito è 3600s. Puoi aggiornare la frequenza di raccolta. Tuttavia, ti consigliamo di mantenere il valore predefinito.
sqlserver_configuration.credential_configurations[].connection_parameters[].host

String

Il nome host di SQL Server.
sqlserver_configuration.credential_configurations[].connection_parameters[].username

String

Specifica l'account utente utilizzato per eseguire query sull'istanza SQL Server. Per configurare le autorizzazioni dell'account, esamina le autorizzazioni richieste nello script di autorizzazione e assegnale in base alle tue norme interne.

Nota: se utilizzi l'autenticazione Windows, assicurati di specificare il nome utente nel seguente formato: domain-name\\user-name

sqlserver_configuration.credential_configurations[].connection_parameters[].secret.project_id

String

L'ID del progetto in cui è archiviato il secret. Impostalo su una stringa vuota ("") se il segreto e l'istanza VM host esistono nello stesso progetto Google Cloud.
sqlserver_configuration.credential_configurations[].connection_parameters[].secret.secret_name

String

Per fornire in modo sicuro la password per l'account utente del database utilizzato dall'agente per eseguire query su SQL Server, specifica il nome del segreto in Secret Manager che contiene le credenziali di sicurezza per l'account utente del database.

Nota:il segreto e l'istanza VM host devono esistere nello stesso progetto Google Cloud.
sqlserver_configuration.credential_configurations[].connection_parameters[].port

Int

Specifica la porta su cui l'istanza SQL Server accetta le query.
sqlserver_configuration.credential_configurations[].remote_win.connection_parameters.host

String

Indirizzo IP o FQDN della VM Windows remota
sqlserver_configuration.credential_configurations[].remote_win.connection_parameters.username

String

Specifica l'account utente utilizzato per connettersi da remoto alla VM Windows.
sqlserver_configuration.credential_configurations[].remote_win.connection_parameters.secret.secret_name

String

Per fornire in modo sicuro la password dell'account utente Windows utilizzato dall'agente per connettersi da remoto alla VM, specifica il nome del secret in Secret Manager che contiene le credenziali di sicurezza per l'account utente del database.

Nota:il segreto e l'istanza VM host devono esistere nello stesso progetto Google Cloud.
sqlserver_configuration.credential_configurations[].local_collection

Boolean

Specifica true per indicare che l'agente sta eseguendo la raccolta dei dati locali. Il valore predefinito è true.
sqlserver_configuration.credential_configurations[].remote_linux.connection_parameters.host

String

Indirizzo IP o FQDN della VM Linux remota.
sqlserver_configuration.credential_configurations[].remote_linux.connection_parameters.username

String

Specifica l'account utente utilizzato per connettersi da remoto alla VM Linux.
sqlserver_configuration.credential_configurations[].remote_linux.connection_parameter.port

Int

Specifica il numero di porta SSH per la VM Linux remota.
sqlserver_configuration.credential_configurations[].remote_linux.linux_ssh_private_key_path

String

Specifica il percorso del file della chiave privata SSH.
sqlserver_configuration.credential_configurations[].vm_properties.instance_name

String

Specifica il nome dell'istanza VM di Compute Engine.

Nota:facoltativo per la raccolta locale.
sqlserver_configuration.credential_configurations[].vm_properties.instance_id

String

Specifica l'ID dell'istanza VM di Compute Engine.

Nota:facoltativo per la raccolta locale.
sqlserver_configuration.collection_timeout

Duration

Il timeout per la raccolta delle metriche, in secondi. Il valore predefinito è "10s".
sqlserver_configuration.max_retries

Int

Il numero massimo di tentativi quando si verifica una raccolta non riuscita. Il valore predefinito è "3".
sqlserver_configuration.retry_frequency

Duration

Specifica la frequenza con cui l'agente deve riprovare quando una raccolta non va a buon fine. Il valore predefinito è "3600s".
sqlserver_configuration.remote_collection

Boolean

Specifica true per indicare che l'agente sta eseguendo la raccolta dei dati da remoto. Il valore predefinito è false.

L'esempio seguente mostra un file di configurazione per Agent for Compute Workloads:

Raccolta localeRaccolta remota

{
"log_level": "INFO",
"common_discovery": {
    "collection_frequency": "10800s"
},
"sqlserver_configuration": {
    "enabled": true,
    "collection_configuration": {
        "collect_guest_os_metrics": true,
        "collect_sql_metrics": true,
        "collection_frequency": "60s"
    },
    "credential_configurations": [
        {
            "connection_parameters": [
                {
                    "host": ".",
                    "username": "db_user_name",
                    "secret": {
                        "project_id": "",
                        "secret_name": "idb_pwd_secret_name"
                    },
                    "port": 1433
                }
            ],
            "local_collection": true
        }
    ],
    "collection_timeout": "60s",
    "max_retries": 5,
    "retry_frequency": "3600s"
}
}

{
"log_level": "INFO",
"common_discovery": {
    "collection_frequency": "10800s"
},
"sqlserver_configuration": {
    "enabled": true,
    "collection_configuration": {
        "collect_guest_os_metrics": true,
        "collect_sql_metrics": true,
        "collection_frequency": "60s"
    },
    "credential_configurations": [
        {
            "connection_parameters": [
                {
                    "host": "sql_server_instance",
                    "username": "db_user_name",
                    "secret": {
                        "project_id": "",
                        "secret_name": "db_pwd_secret_name"
                    },
                    "port": 1433
                }
            ],
            "remote_win": {
                "connection_parameters": {
                    "host": "sql_server_instance",
                    "username": "user_name",
                    "secret": {
                        "project_id": "",
                        "secret_name": "pwd_secret_name"
                    }
                }
            },
            "vm_properties": {
                "instance_name": "db01",
                "instance_id": "9999999999999999999"
            }
        },
        {
            "connection_parameters": [
                {
                    "host": "sql_server_instance",
                    "username": "db_user_name",
                    "secret": {
                        "project_id": "",
                        "secret_name": "db_pwd_secret_name"
                    },
                    "port": 1433
                }
            ],
            "remote_linux": {
                "connection_parameters": {
                    "host": "sql_server_instance",
                    "username": "user_name",
                    "secret": {
                        "project_id": "",
                        "secret_name": "pwd_secret_name"
                    },
                    "port": 22
                },
                "linux_ssh_private_key_path": "path of the private key"
            },
            "vm_properties": {
                "instance_name": "db02",
                "instance_id": "9999999999999999999"
            }
        }
    ],
    "collection_timeout": "10s",
    "max_retries": 3,
    "retry_frequency": "3600s",
    "remote_collection": true
}
}

Verificare l'installazione dell'agente

Windows Linux
  1. Connettiti all'istanza VM Windows utilizzando RDP.

  2. Esegui il seguente comando da PowerShell come amministratore:

    $(Get-Service -Name 'google-cloud-workload-agent' -ErrorAction Ignore).Status

    Se l'agente è in esecuzione, lo stato visualizzato è Running.

  1. Stabilisci una connessione SSH con l'istanza VM host.

  2. Esegui questo comando: 

    systemctl status google-cloud-workload-agent

    Se l'agente funziona correttamente, l'output contiene active (running). Ad esempio: 

    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 2023-12-31 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

Controllare la versione dell'agente

Per controllare la versione dell'agente:

Windows RHEL SUSE Debian
  1. Utilizza RDP per connetterti alla macchina host.
  2. In qualità di amministratore, esegui il seguente comando da PowerShell: 
    googet installed google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    yum info google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    zypper info google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    dpkg -s google-cloud-workload-agent | grep version

Riavvia l'agente

Se l'agente per i carichi di lavoro di Compute Engine smette di funzionare o se aggiorni la relativa configurazione, riavvia l'agente.

Seleziona il tuo sistema operativo e segui i passaggi:

Windows Linux
  1. Utilizza RDP per connetterti alla macchina host.
  2. In qualità di amministratore, esegui il seguente comando da PowerShell: 
    Restart-Service -Name 'google-cloud-workload-agent' -Force
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo systemctl restart google-cloud-workload-agent

Aggiorna l'agente

Per assicurarti di avere la versione più recente dell'agente, devi controllare periodicamente la disponibilità di aggiornamenti e aggiornare l'agente.

Cerca aggiornamenti

Seleziona il tuo sistema operativo e segui i passaggi:

Windows RHEL SLES Debian
  1. Utilizza RDP per connetterti alla macchina host.
  2. In qualità di amministratore, esegui il seguente comando da PowerShell: 
    googet latest google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo yum check-update google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo zypper list-updates -r google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo apt list google-cloud-workload-agent

Installare un aggiornamento

Seleziona il tuo sistema operativo e segui i passaggi:

Windows RHEL SLES Debian
  1. Utilizza RDP per connetterti alla macchina host.
  2. In qualità di amministratore, esegui il seguente comando da PowerShell: 
    googet install google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo yum --nogpgcheck update google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo zypper --no-gpg-checks update google-cloud-workload-agent
  1. Utilizza SSH per connetterti alla macchina host.
  2. Esegui questo comando: 
    sudo apt-get install google-cloud-workload-agent

Visualizza i log dell'agente in Cloud Logging

Per impostazione predefinita, i log di Agent for Compute Workloads vengono reindirizzati dalle istanze VM a Cloud Logging.

Per visualizzare i log dell'agente in Log:

  1. Nella console Google Cloud, vai alla pagina Esplora log.

    Vai a Esplora log

  2. Vai al riquadro Query.

  3. Nel menu a discesa Risorse, seleziona Globale e poi fai clic su Applica.

  4. Nell'editor di query, inserisci google-cloud-workload-agent.

  5. Fai clic su Esegui query.

    Dovresti vedere i log generati dalle istanze dell'agente in esecuzione su tutte le istanze VM. Per filtrare i log di una macchina specifica, utilizza i filtri disponibili nell'interfaccia.

Disattivare i log dell'agente in Cloud Logging

Per disattivare il reindirizzamento predefinito dei log dell'agente a Cloud Logging, segui questi passaggi:

  1. Stabilisci una connessione RDP o SSH con l'istanza VM host.

  2. Apri il file di configurazione dell'agente:

    Windows Linux 

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

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

  3. Per la proprietà log_to_cloud, aggiorna il valore su false.

  4. Salva il file di configurazione.

  5. Riavvia l'agente per applicare la modifica.

Risoluzione dei problemi

Le sezioni seguenti forniscono informazioni sui problemi comuni relativi all'utilizzo di Agent for Compute Workloads, sulle relative cause e sulla loro risoluzione.

Ambiti di autenticazione insufficienti

Problema: se limiti gli ambiti di accesso nell'istanza VM host, i log di Agent for Compute Workloads potrebbero mostrare un errore di autorizzazioni IAM insufficienti. 

  googleapi: Error 403: Request had insufficient authentication scopes.
  Details:
  [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "domain": "googleapis.com",
      "metadata": {
        "method": "google.cloud.workloadmanager.datawarehouse.v1.DataCollectService.WriteInsight",
        "service": "workloadmanager.googleapis.com"
      },
      "reason": "ACCESS_TOKEN_SCOPE_INSUFFICIENT"
    }
  ]



More details:
  Reason: insufficientPermissions, Message: Insufficient Permission

Causa: l'agente per i workload di Compute richiede ambiti di accesso minimi all'API Cloud nell'istanza VM host.

Soluzione:per risolvere il problema, attiva i campi di accesso richiesti

Impossibile caricare il file di configurazione

Problema: se il file di configurazione contiene valori non validi, viene visualizzato il seguente errore. 

"Failed to load configuration","pid":3524,"error":"proto: (line 19:42): unknown
field "{field_name}"

Risoluzione: per risolvere il problema, aggiorna il file di configurazione utilizzando i dettagli in Proprietà di configurazione

Impossibile inizializzare la raccolta dei dati

Problema: dopo aver installato l'agente, se il file di configurazione non viene aggiornato, viene visualizzato il seguente errore: 

"Failed to initialize guest collection","pid":2112,"error":"invalid value for "user_name" "secret_name"

Risoluzione: per risolvere il problema, inizializza la configurazione delle credenziali utilizzando le proprietà di configurazione.

Passaggi successivi