Configurar coletores agregados

Neste documento, você verá como criar coletores agregados. Para informações sobre como gerenciar coletores existentes, consulte Configurar e gerenciar coletores.

Visão geral

Os coletores agregados combinam e roteiam entradas de registro dos recursos do Google Cloud contidos por uma organização ou pasta. Por exemplo, é possível agregar e rotear entradas de registro de auditoria de todas as pastas contidas em uma organização para um bucket do Cloud Storage.

Sem o recurso de coletor agregado, os coletores são limitados ao encaminhamento de entradas de registro do recurso exato em que o coletor foi criado: um projeto, uma organização, uma pasta ou uma conta de faturamento do Google Cloud.

É possível criar coletores agregados para pastas e organizações do Google Cloud. Como nem os projetos do Cloud nem as contas de faturamento contêm recursos filhos, não é possível criar coletores agregados para eles.

Destinos possíveis

Você pode usar coletores agregados para rotear registros dentro ou entre as mesmas organizações e pastas para os seguintes destinos:

  • Cloud Storage: arquivos JSON armazenados nos buckets do Cloud Storage.
  • Pub/Sub: mensagens JSON entregues aos tópicos do Pub/Sub. Compatível com integrações de terceiros, como o Splunk, com o Logging.
  • BigQuery: tabelas criadas em conjuntos de dados do BigQuery.
  • Outro bucket do Cloud Logging: entradas de registro mantidas em buckets de registro do Cloud Logging.

Antes de começar

Antes de criar um coletor, verifique se:

  • Você tem uma pasta ou organização do Google Cloud com registros que podem ver no Explorador de registros.

  • Você tem um dos seguintes papéis do IAM para a organização ou pasta do Google Cloud a partir da qual está roteando registros.

    • Proprietário (roles/owner)
    • Administrador do Logging (roles/logging.admin)
    • Gravador de configuração de registros (roles/logging.configWriter)

    As permissões contidas nesses papéis permitem criar, excluir ou modificar coletores. Para informações sobre como definir papéis do IAM, consulte o Guia de controle de acesso do Logging.

  • Você tem um recurso em um destino compatível ou pode criar um.

    O destino de roteamento precisa ser criado antes do coletor por meio da CLI do Google Cloud, do console ou das APIs do Google Cloud. É possível criar o destino em qualquer projeto do Cloud em qualquer organização, mas é preciso verificar se a conta de serviço do coletor tem permissões de gravação no destino.

Criar um coletor agregado

Para usar coletores agregados, crie um coletor em uma organização ou pasta do Google Cloud e defina o parâmetro includeChildren do coletor como True. Assim, esse coletor poderá encaminhar entradas de registro da organização ou pasta e, de maneira recursiva, de qualquer pasta, contas de faturamento ou projetos contidos. Defina os filtros de inclusão e exclusão do coletor para especificar as entradas de registro que você quer rotear para o destino.

É possível criar até 200 coletores por pasta ou organização.

Para criar um coletor agregado para sua pasta ou organização, faça o seguinte:

Console

  1. No console, acesse a página Logging > Log Router.

    Acessar o roteador de registros

  2. Selecione uma pasta ou organização existente.

  3. Selecione Criar coletor.

  4. No painel Detalhes do coletor, insira os seguintes detalhes:

    • Nome do coletor: forneça um identificador para o coletor. Depois de criar o coletor, não será possível renomeá-lo, mas será possível excluí-lo e criar um novo coletor.

    • Descrição do coletor (opcional): descreva a finalidade ou o caso de uso do coletor.

  5. No painel Destino do coletor, selecione o serviço de coletor e o destino:

    • Selecionar serviço de coletor: selecione o serviço em que você quer os registros roteados.

    Com base no serviço selecionado, é possível selecionar os seguintes destinos:

    • Bucket do Cloud Logging: selecione ou crie um bucket do Logging.
    • Tabela do BigQuery: selecione ou crie o conjunto de dados específico para receber os registros roteados. Você também tem a opção de usar tabelas particionadas.
    • Bucket do Cloud Storage: selecione ou crie o bucket específico do Cloud Storage para receber os registros roteados.
    • Tópico do Pub/Sub: selecione ou crie o tópico específico para receber os registros roteados.
    • Splunk: selecione o tópico do Pub/Sub do serviço Splunk.

      Por exemplo, se o destino do coletor for um conjunto de dados do BigQuery, o destino do coletor será o seguinte:

      bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
      
  6. No painel Escolher registros a serem incluídos no coletor, faça o seguinte:

    1. Selecione Incluir registros ingeridos por este recurso e todos os recursos filhos, que cria um coletor agregado.

    2. No campo Criar inclusão de filtro, insira uma expressão de filtro que corresponda às entradas de registro que você quer incluir. Se você não definir um filtro, todos os registros do recurso selecionado serão roteados para o destino.

      Por exemplo, é possível criar um filtro para encaminhar todos os registros de acesso a dados para um único bucket do Logging. Esse filtro tem a seguinte aparência:

      LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")
      

      O comprimento de um filtro não pode exceder 20.000 caracteres.

    3. Para conferir se você inseriu o filtro correto, selecione Visualizar registros. Isso abre o Explorador de registros em uma nova guia com o filtro pré-preenchido.

  7. (Opcional) No painel Escolher registros a serem excluídos do coletor, faça o seguinte:

    1. No campo Nome do filtro de exclusão, insira um nome.

    2. No campo Criar um filtro de exclusão, insira uma expressão de filtro que corresponda às entradas de registro que você quer excluir. Também é possível usar a função sample para selecionar uma parte das entradas de registro a serem excluídas.

    É possível criar até 50 filtros de exclusão por coletor. O comprimento de um filtro não pode exceder 20.000 caracteres.

  8. Selecione Criar coletor.

API

Para criar um coletor, use organizations.Sinks.create ou folders.Sinks.create na API Logging. Prepare os argumentos do método da seguinte maneira:

  1. Defina o parâmetro parent como a organização ou pasta do Google Cloud em que o coletor será criado. O pai precisa ser um dos seguintes parâmetros:

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID
  2. No objeto LogSink no corpo da solicitação do método, faça o seguinte:

  3. Chame organizations.sinks.create ou folders.sinks.create para criar o coletor.

  4. Recupere o nome da conta de serviço no campo writer_identity retornado da resposta da API.

  5. Conceda a essa conta de serviço permissão para gravar no destino do coletor.

    Se você não tiver permissão para fazer essa alteração no destino do coletor, envie o nome da conta de serviço para alguém que possa fazer essa alteração.

    Para mais informações sobre a concessão de permissões de contas de serviço para recursos, consulte a seção definir permissões de destino.

gcloud

Para criar um coletor, use o comando logging sinks create.

  1. Forneça o nome do coletor, o destino do coletor, o filtro e o ID da pasta ou organização de onde você está roteando os registros:

    gcloud logging sinks create SINK_NAME
    SINK_DESTINATION  --include-children \
    --folder=FOLDER_ID filter
    

    Por exemplo, se você estiver criando um coletor agregado no nível da pasta e cujo destino for um conjunto de dados do BigQuery, o comando poderá ter a seguinte aparência:

    gcloud logging sinks create SINK_NAME \
    bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID --include-children \
    --folder=FOLDER_ID --log-filter="logName:activity"

    Observações:

    • Para criar um coletor no nível da organização, substitua --folder=FOLDER_ID por --organization=ORGANIZATION_ID.

    • Para que o coletor inclua todos os recursos da organização, a sinalização --include-children precisa ser definida, mesmo quando a sinalização --organization for passada para create. Quando for definido como false (padrão), um coletor encaminhará apenas registros do recurso host.

    • Para alguns exemplos de filtros úteis, consulte Criar filtros para coletores agregados.

  2. Recupere o nome da conta de serviço usado para criar o coletor com base na saída do comando.

  3. Conceda a essa conta de serviço permissão para gravar no destino do coletor.

    Se você não tiver permissão para fazer essa alteração no destino do coletor, envie o nome da conta de serviço para alguém que possa fazer essa alteração.

    Para mais informações sobre a concessão de permissões de contas de serviço para recursos, consulte a seção definir permissões de destino.

As alterações feitas em um coletor podem levar alguns minutos para serem aplicadas.

Criar filtros para coletores agregados

Como qualquer outro, o coletor agregado contém um filtro que seleciona entradas de registro individuais. Para exemplos de filtros que você pode usar para criar um coletor agregado, consulte Consultas de amostra usando o Explorador de registros.

Veja a seguir alguns exemplos de comparações de filtros que são úteis ao usar o recurso de coletores agregados. Alguns exemplos utilizam a seguinte notação:

  • :: é o operador de substring. Não substitua o operador =.
  • ... representa qualquer comparação de filtros adicional.
  • As variáveis são indicadas por texto colorido. As substitua por valores válidos.

O comprimento de um filtro não pode exceder 20.000 caracteres.

Para mais detalhes sobre a sintaxe da filtragem, consulte Linguagem de consulta do Logging.

Selecionar a origem do registro

Para rotear registros de projetos, pastas ou organizações específicas do Cloud, use uma das seguintes comparações de amostra:

logName:"projects/PROJECT_ID/logs/" AND ... 
logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ... 
logName:"folders/FOLDER_ID/logs/" AND ... 
logName:"organizations/ORGANIZATION_ID/logs/" AND ... 

Selecione o recurso monitorado.

Para rotear registros de apenas um recurso monitorado específico em um projeto do Cloud, use várias comparações para especificar o recurso exatamente:

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

Para uma lista de tipos de recursos, consulte Tipos de recursos monitorados.

Selecione uma amostra de entradas de registro

Para encaminhar uma amostra aleatória de entradas de registro, adicione a função incorporada sample. Por exemplo, para rotear somente 10% das entradas de registro correspondentes ao seu filtro atual, use esta adição:

sample(insertId, 0.10) AND ...

Para mais informações, consulte a função sample.

Para mais informações sobre os filtros do Cloud Logging, consulte Linguagem de consulta do Logging.

Definir permissões de destino

Nesta seção, descrevemos como conceder permissões de gerenciamento de identidade e acesso ao Logging para gravar registros no destino do coletor. Para a lista de papéis e permissões do Logging, consulte Controle de acesso.

Quando você cria um coletor, o Logging cria uma nova conta de serviço para ele, chamada de identidade única de gravador. Essa conta de serviço precisa ter permissão do destino do coletor para gravar entradas de registro. Não é possível gerenciar essa conta de serviço diretamente porque ela pertence e é gerenciada pelo Cloud Logging. A conta de serviço será excluída se o coletor for excluído.

Para rotear registros para um recurso protegido por um perímetro de serviço, é necessário adicionar a conta de serviço desse coletor a um nível de acesso e, em seguida, atribuí-la ao perímetro de serviço de destino de dados. Isso não é necessário para coletores não agregados. Para detalhes, consulte VPC Service Controls: Cloud Logging.

Para definir permissões a fim de rotear o coletor para o destino, faça o seguinte:

Console

  1. Consiga a identidade de gravador do coletor, um endereço de e-mail, com o novo coletor. Acesse a página Roteador de registros e selecione Menu > Ver detalhes do coletor. A identidade do gravador é exibida no painel Detalhes do coletor.

  2. Caso você tenha acesso de proprietário ao destino, adicione a conta de serviço ao destino da seguinte maneira:

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor ao bucket do Cloud Storage e conceda o papel de criador de objetos do Storage.
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor ao conjunto de dados e conceda o papel de editor de dados do BigQuery.
    • Para o Pub/Sub, incluindo o Splunk, adicione a identidade do gravador do coletor ao seu tópico e atribua a ele o papel de editor do Pub/Sub.
    • Para destinos de bucket do Logging em diferentes projetos do Cloud, adicione a identidade de gravador do coletor ao bucket de destino e conceda a permissão roles/logging.bucketWriter.

    Se você não tiver proprietário ao destino do coletor, envie o nome da conta de serviço da identidade do gravador para alguém que tenha essa capacidade. Essa pessoa precisará seguir as instruções contidas no passo anterior para adicionar a identidade de gravador ao destino do coletor.

API

  1. Consiga a conta de serviço no campo writerIdentity no seu coletor chamando o método de API organizations.Sinks.get ou folders.Sinks.get de dados.

    A conta de serviço é semelhante a esta:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
    
  2. Adicione a identidade de gravador do novo coletor à lista de permissões do destino, dando permissão ao gravador para gravar no destino.

    Se você tiver acesso de Proprietário do IAM ao destino, adicione a conta de serviço ao destino da seguinte maneira:

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor ao bucket e conceda o papel de criador de objetos do Storage.
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor ao conjunto de dados e conceda o papel de editor de dados do BigQuery.
    • Para o Pub/Sub, incluindo o Splunk, adicione a identidade do gravador do coletor ao seu tópico e atribua a ele o papel de editor do Pub/Sub.
    • Para destinos de bucket do Logging em diferentes projetos do Cloud, adicione a identidade de gravador do coletor ao bucket de registro de destino e conceda a permissão roles/logging.bucketWriter.

    Se você não tiver proprietário ao destino do coletor, envie o nome da conta de serviço da identidade do gravador para alguém que tenha essa capacidade. Essa pessoa precisará seguir as instruções contidas no passo anterior para adicionar a identidade de gravador ao destino do coletor.

gcloud

  1. Consiga a identidade de gravador do coletor, um endereço de e-mail, com o novo coletor:

  2. Consiga a conta de serviço do campo writerIdentity no seu coletor:

    gcloud logging sinks describe SINK_NAME
    

    A conta de serviço é semelhante a esta:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
    
  3. Se você tiver acesso de Proprietário do IAM ao destino, adicione a conta de serviço ao destino da seguinte maneira:

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor ao bucket do Cloud Storage e conceda o papel de criador de objetos do Storage.
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor ao conjunto de dados e conceda o papel de editor de dados do BigQuery.
    • Para o Pub/Sub, incluindo o Splunk, adicione a identidade do gravador do coletor ao seu tópico e atribua a ele o papel de editor do Pub/Sub.
    • Para destinos de bucket do Logging em diferentes projetos do Cloud, adicione a identidade de gravador do coletor ao bucket de registro de destino e conceda a permissão roles/logging.bucketWriter.

    Se você não tiver proprietário ao destino do coletor, envie o nome da conta de serviço da identidade do gravador para alguém que tenha essa capacidade. Essa pessoa precisará seguir as instruções contidas no passo anterior para adicionar a identidade de gravador ao destino do coletor.

    Por exemplo, se você estiver roteando registros entre buckets do Logging em diferentes projetos do Cloud, adicione roles/logging.bucketWriter à conta de serviço da seguinte maneira:

    1. Consiga a política do Identity and Access Management para o projeto de destino e grave-a em um arquivo local no formato JSON:

      gcloud projects get-iam-policy DESTINATION_PROJECT_ID --format json > output.json
      
    2. Adicione uma condição do IAM que permita à conta de serviço gravar apenas no destino criado. Exemplo:

      {
      "bindings": [
       {
         "members": [
           "user:username@gmail.com"
         ],
         "role": "roles/owner"
       },
       {
         "members": [
           "SERVICE_ACCOUNT"
         ],
         "role": "roles/logging.bucketWriter",
         "condition": {
             "title": "Bucket writer condition example",
             "description": "Grants logging.bucketWriter role to service account SERVICE_ACCOUNT used by sink SINK_NAME",
             "expression":
               "resource.name.endsWith(\'locations/global/buckets/BUCKET_ID\')"
         }
       }
      ],
      "etag": "BwWd_6eERR4=",
      "version": 3
      }
    3. Atualize a política do IAM:

      gcloud projects set-iam-policy DESTINATION_PROJECT_ID output.json
      

A seguir