Configurar o agente para SQL Server

O Workload Manager para Microsoft SQL Server usa o agente do Google Cloud para SQL Server para detectar e coletar metadados para avaliar as configurações do SQL Server. O agente para SQL Server é necessário em todas as VMs que executam o SQL Server.

Este documento mostra como instalar, configurar e verificar o agente do Google Cloudpara SQL Server.

Pré-requisitos para instalar o agente

Antes de instalar o Agente para SQL Server, é necessário garantir que os pré-requisitos a seguir sejam atendidos e criar uma avaliação de carga de trabalho do SQL Server.

Conceder papéis do IAM à conta de serviço

O agente doGoogle Cloudpara SQL Server usa a conta de serviço do Identity and Access Management (IAM) anexada à VM para autenticação com Google Cloud e permissão para acessar recursos do Google Cloud . Para a coleta de métricas de validação do Workload Manager, use uma nova conta de serviço que inclua os seguintes papéis do IAM:

Cuidado: usar a conta de serviço padrão do Compute Engine para a coleta de métricas de validação do Workload Manager e conceder à conta acesso ao Secret Manager aumenta significativamente o risco de segurança. Em vez disso, recomendamos que você crie uma conta de serviço de finalidade única e limite o acesso do shell do usuário às VMs.

• Leitor do Compute (roles/compute.viewer)
• Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor)
• Administrador do Workload Manager (roles/workloadmanager.admin)
• Gravador de registros (roles/logging.logWriter), se você usa o recurso do Cloud Logging

Para adicionar um papel necessário à conta de serviço, siga estas etapas:

1. No console do Google Cloud, abra a página IAM.

   Acessar o IAM

2. Selecione seu projeto do Google Cloud.

3. Identifique a conta de serviço em que você quer incluir um papel.

   • Se a conta de serviço ainda não estiver na lista de principais, ela não terá nenhum papel atribuído a ela. Clique em Adicionar e digite o endereço de e-mail da conta do serviço.
   • Se a conta de serviço estiver na lista de principais, a conta de serviço já terá papéis. Clique no botão Editar da conta de serviço que você quer editar.

4. Selecione o papel necessário na lista de papéis disponíveis:

   • Compute Engine > Visualizador do Compute
   • Secret Manager > Acessador de secrets do Secret Manager

5. Clique em Adicionar ou Salvar para aplicar os papéis à conta de serviço.

Ativar o acesso às APIs Google Cloud

O Compute Engine recomenda configurar as instâncias de VM para permitir todos os escopos de acesso a todas as APIs do Cloud e usar apenas as permissões do IAM da conta de serviço da instância para controlar o acesso aos Google Cloud recursos. Para mais informações, consulte Criar uma VM que usa uma conta serviço gerenciado pelo usuário.

Se você limitar o acesso às APIs do Cloud, o Agente do SQL Server exigirá os seguintes escopos mínimos de acesso da API Cloud na instância da VM do host:

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

Para mais informações, consulte Práticas recomendadas de escopos.

Se você estiver executando aplicativos do SQL Server em uma instância de VM que não tenha um endereço IP externo, ative o Acesso privado do Google na sub-rede da VM para que o agente do SQL Server possa acessar as APIs e os serviços do Google. Para saber como ativar o Acesso privado do Google em uma sub-rede, consulte Como configurar o Acesso privado do Google.

Permissões necessárias no SQL Server

Use o script abaixo para atribuir as permissões necessárias à conta de usuário configurada no 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''
    '
  

Instalar o agente

Windows

No Windows, instale o agente para SQL Server usando o comando de gerenciamento de pacotes GooGet, googet. O comando de gerenciamento de pacotes conclui as seguintes tarefas:

• Faz o download da versão mais recente do agente para SQL Server.
• Cria um serviço do Windows chamado google-cloud-sql-server-agent e uma tarefa programada que é executada a cada minuto para verificar se o serviço ainda está em execução e, se necessário, reiniciá-lo.

Aviso: não interrompa manualmente o serviço do Windows nem exclua a tarefa programada.

Para instalar o agente em uma VM, siga estas etapas:

1. Conecte-se à instância da VM do Windows usando o RDP.
2. Como administrador, execute os seguintes comandos no PowerShell:

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

3. Revise o arquivo de configuração localizado em %ProgramFiles%\Google\google-cloud-sql-server-agent e atualize a seção credential_configuration usando os detalhes em Propriedades de configuração.
4. Reinicie o agente para que essa alteração entre em vigor.

Linux

No Linux, instale o Agente para SQL Server usando os comandos padrão de gerenciamento de pacotes do sistema operacional:

• No RHEL, use o comando yum.
• No SLES, use o comando zypper.

O comando de gerenciamento de pacotes conclui as seguintes tarefas:

• Faz o download da versão mais recente do agente para SQL Server.
• Cria o agente como um serviço systemd do Linux, chamado google-cloud-sql-server-agent.
• Ativa e inicia o serviço google-cloud-sql-server-agent.

Para instalar o agente em uma VM, siga estas etapas:

1. Estabeleça uma conexão SSH com a VM do host.
2. No seu terminal, instale o agente executando o comando específico para seu sistema operacional:

RHEL

sudo tee /etc/yum.repos.d/google-cloud-sql-server-agent.repo << EOM
[google-cloud-sql-server-agent]
name=Google Cloud Agent for SQL Server
baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-sql-server-agent-el$(cat /etc/redhat-release | cut -d . -f 1 | tr -d -c 0-9)
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-sql-server-agent

SLES 15

sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sql-server-agent-sles15 google-cloud-sql-server-agent
sudo zypper install google-cloud-sql-server-agent

SLES 12

sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sql-server-agent-sles12 google-cloud-sql-server-agent
sudo zypper install google-cloud-sql-server-agent

1. Revise o arquivo de configuração localizado em \etc\google-cloud-sql-server-agent e atualize a seção credential_configuration usando os detalhes em Propriedades de configuração.
2. Reinicie o agente para que essa alteração entre em vigor.

Propriedades de configuração

A tabela a seguir explica as propriedades do arquivo de configuração do agente.

Propriedades
collection_configuration.collect_guest_os_metrics	Boolean Para ativar a coleta de métricas do SO, defina o valor como true. O padrão é true. Não defina collection_configuration.collect_guest_os_metrics como false, a menos que isso seja orientado pelo Cloud Customer Care.
collection_configuration.guest_os_metrics_collection_interval_in_seconds	Int Frequência de coleta de métricas do sistema operacional do Workload Manager em segundos. O padrão é 3600 segundos. Você pode atualizar a frequência de coleta. No entanto, recomendamos manter o valor padrão.
collection_configuration.collect_sql_metrics	Boolean Para ativar a coleta de métricas do SQL Server, especifique true. O padrão é true. Não defina collection_configuration.collect_sql_metrics como false, a menos que isso seja orientado pelo Cloud Customer Care.
collection_configuration.collect_sql_metrics_collection_interval_in_seconds	Int Frequência de coleta de métricas do SQL Server do Workload Manager em segundos. O padrão é 3600 segundos. Você pode atualizar a frequência de coleta. No entanto, recomendamos manter o valor padrão.
log_level	String Para definir o nível de geração de registros do agente, adicione-os. Os níveis de registro disponíveis são os seguintes: DEBUG INFO WARNING ERROR O padrão é INFO. Não altere o nível de geração de registros, a menos que seja instruído pelo Cloud Customer Care.
log_to_cloud	Boolean Para redirecionar os registros do agente para o Cloud Logging, especifique true. O padrão é true.
disable_log_usage	Boolean Para desativar o registro de métricas de integridade do agente, especifique true. O padrão é false.
remote_collection	Boolean Especifique true para indicar que o agente está fazendo a coleta de dados remotamente. O padrão é false.
credential_configuration[].sql_configurations[].user_name	String Especifique a conta de usuário usada para consultar a instância do SQL Server. Para configurar as permissões da conta, revise as permissões necessárias no script da permissão e conceda-as de acordo com as políticas internas. Observação:se você estiver usando a autenticação do Windows, especifique o nome de usuário no seguinte formato: domain-name\\user-name
credential_configuration[].sql_configurations[].host	String O nome do host do SQL Server.
credential_configuration[].sql_configurations[].secret_name	String Para fornecer com segurança a senha da conta de usuário do banco de dados que o agente usa para consultar o SQL Server, especifique o nome do secret no Secret Manager que contém as credenciais de segurança para a conta de usuário do banco de dados. Observação:o secret e a instância de VM do host precisam existir no mesmo projeto do Google Cloud.
credential_configuration[].sql_configurations[].port_number	Int Especifique a porta em que a instância do SQL Server aceita consultas.
credential_configuration[].remote_win.server_name	String Endereço IP ou FQDN da VM remota
credential_configuration[].remote_win.guest_user_name	String Especifique a conta de usuário usada para se conectar remotamente à VM.
credential_configuration[].remote_win.guest_secret_name	String Para fornecer com segurança a senha da conta de usuário que o agente usa para se conectar remotamente à VM, especifique o nome do secret no Secret Manager que contém as credenciais de segurança da conta de usuário. Observação:o secret e a instância de VM do host precisam existir no mesmo projeto do Google Cloud.
credential_configuration[].remote_linux.server_name	String Endereço IP ou FQDN da VM remota
credential_configuration[].remote_linux.guest_user_name	String Especifique a conta de usuário usada para se conectar remotamente à VM.
credential_configuration[].remote_linux.guest_port_number	Int Especifique o número da porta SSH para a VM remota.
credential_configuration[].remote_linux.linux_ssh_private_key_path	String Caminho para o arquivo de chave privada SSH.
credential_configuration[].instance_name	String Especifique o nome da sua instância de VM do Compute Engine. Observação:opcional para a coleta local.
credential_configuration[].instance_id	String Especifique o ID da sua instância de VM do Compute Engine. Observação:opcional para coleta local.

O exemplo a seguir mostra um arquivo de configuração do Agente para SQL Server:

Coleta local

{
"collection_configuration": {
  "collect_guest_os_metrics":true,
  "guest_os_metrics_collection_interval_in_seconds":3600,
  "collect_sql_metrics":true,
  "sql_metrics_collection_interval_in_seconds":3600
},
"credential_configuration": [
  {
    "sql_configurations": [
      {
        "host":".",
        "user_name":"db_user_name",
        "secret_name":"db_pwd_secret_name",
        "port_number":1433
      }
    ],
  }
],
"log_level":"INFO",
"log_to_cloud":true,
"collection_timeout_seconds":10,
"max_retries":5,
"retry_interval_in_seconds":3600
}

Coleta remota

{
"collection_configuration": {
  "collect_guest_os_metrics":true,
  "guest_os_metrics_collection_interval_in_seconds":3600,
  "collect_sql_metrics":true,
  "sql_metrics_collection_interval_in_seconds":3600
},
"credential_configuration": [
  {
    "sql_configurations": [
      {
        "host":"sql_server_instance",
        "user_name":"db_user_name",
        "secret_name":"db_pwd_secret_name",
        "port_number":1433
      }
    ],
    "remote_win":{
      "server_name":"sql_server_instance",
      "guest_user_name":"user_name",
      "guest_secret_name":"pwd_secret_name"
    },
    "instance_name":"db01",
    "instance_id":"9999999999999999999"
  }
],
"remote_collection":true,
"log_level":"INFO",
"log_to_cloud":true,
"collection_timeout_seconds":10,
"max_retries":5,
"retry_interval_in_seconds":3600
}

Verificar a instalação do agente

Windows

1. Conecte-se à instância da VM do Windows usando o RDP.

2. Execute o seguinte comando no PowerShell como administrador:

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

   Se o agente estiver em execução, o status mostrará Running.

Linux

1. Estabeleça uma conexão SSH com a instância de VM do host.

2. Execute este comando:

   systemctl status google-cloud-sql-server-agent

   Se o agente estiver funcionando corretamente, a saída conterá active (running). Exemplo:

   google-cloud-sql-server-agent.service - Google Cloud Agent for SQL Server
   Loaded: loaded (/usr/lib/systemd/system/google-cloud-sql-server-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-sql-server-agent.service
           └─ 14412 /usr/bin/google_cloud_sql_server_agent --action=run
   

Verificar a versão do agente

Para acessar a versão do agente, siga estas etapas:

Windows

1. Use o RDP para se conectar à máquina host.
2. Como administrador, emita o seguinte comando no PowerShell:

   googet installed google-cloud-sql-server-agent

RHEL

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   yum info google-cloud-sql-server-agent

SUSE

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   zypper info google-cloud-sql-server-agent

Reinicie o agente.

Se o agente para SQL Server parar de funcionar ou você atualizar a configuração, reinicie o agente.

Selecione seu sistema operacional e siga estas etapas:

Windows

1. Use o RDP para se conectar à máquina host.
2. Como administrador, emita o seguinte comando no PowerShell:

   Restart-Service -Name 'google-cloud-sql-server-agent' -Force

Linux

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   sudo systemctl restart google-cloud-sql-server-agent

Atualizar o agente

Para garantir que você tenha a versão mais recente do agente, é necessário verificar se há atualizações periodicamente e atualizar o agente.

Verificar se há atualizações

Selecione seu sistema operacional e siga estas etapas:

Windows

1. Use o RDP para se conectar à máquina host.
2. Como administrador, emita o seguinte comando no PowerShell:

   googet latest google-cloud-sql-server-agent

RHEL

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   sudo yum check-update google-cloud-sql-server-agent

SLES

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   sudo zypper list-updates -r google-cloud-sql-server-agent

Instalar uma atualização

Selecione seu sistema operacional e siga estas etapas:

Windows

1. Use o RDP para se conectar à máquina host.
2. Como administrador, emita o seguinte comando no PowerShell:

   googet install google-cloud-sql-server-agent

RHEL

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   sudo yum --nogpgcheck update google-cloud-sql-server-agent

SLES

1. Use o SSH para se conectar à máquina host.
2. Execute este comando:

   sudo zypper --no-gpg-checks update google-cloud-sql-server-agent

Ver os registros do agente no Cloud Logging

Por padrão, os registros do agente para SQL Server são redirecionados das instâncias de VM para o Cloud Logging.

Para ver os registros do agente no Logging, siga estas etapas:

1. No console do Google Cloud, acesse a página do Explorador de registros.

   Acessar o "Explorador de registros"

2. Acesse o painel Consulta.

3. No menu suspenso Recursos, selecione Global e clique em Aplicar.

4. No editor de consultas, insira google-cloud-sql-server-agent.

5. Clique em Executar consulta.

   Você vai encontrar os registros gerados pelas instâncias do agente em execução em todas as instâncias de VM. Para filtrar os registros de uma máquina específica, use os filtros disponíveis na interface.

Desativar os registros do agente no Cloud Logging

Para desativar o redirecionamento padrão dos registros do agente para o Cloud Logging, siga estas etapas:

1. Estabeleça uma conexão RDP ou SSH com a instância de VM do host.

2. Abra o arquivo de configuração do agente:

   Windows

   %ProgramFiles%\Google\google-cloud-sql-server-agent\configuration.json

   Linux

   /etc/google-cloud-sql-server-agent/configuration.json

3. Para a propriedade log_to_cloud, atualize o valor para false.

4. Salve o arquivo de configuração.

5. Reinicie o agente para que essa alteração entre em vigor.

Solução de problemas

As seções a seguir fornecem informações sobre problemas comuns relacionados ao uso do Agente para SQL Server, suas causas e resolução.

Escopos de autenticação insuficientes

Problema:se você limitar os escopos de acesso na instância de VM do host, o agente para registros do SQL Server poderá mostrar um erro de permissões de IAM insuficiente.

  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:o agente para SQL Server exige escopos de acesso mínimos da API Cloud na instância da VM do host.

Solução:para resolver esse problema, ative os escopos de acesso necessários.

Falha ao carregar o arquivo de configuração

Problema:se o arquivo de configuração tiver valores inválidos, o seguinte erro vai aparecer.

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

Solução:para resolver esse problema, atualize o arquivo de configuração usando os detalhes em Propriedades de configuração.

Falha ao inicializar a coleta de dados

Problema:depois de instalar o agente, se o arquivo de configuração não for atualizado, você vai receber o seguinte erro:

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

Solução:para resolver esse problema, inicialize a configuração de credenciais usando as Propriedades de configuração.

A seguir

• Saiba mais sobre as avaliações de carga de trabalho.